QPrinter Class

成员函数文档

[explicit] QPrinter::QPrinter(QPrinter::PrinterMode mode = ScreenResolution)

使用给定的mode 创建一个新的打印机对象。

[explicit] QPrinter::QPrinter(const QPrinterInfo &printer, QPrinter::PrinterMode mode = ScreenResolution)

使用给定的printer 和mode 创建一个新的打印机对象。

[virtual noexcept] QPrinter::~QPrinter()

销毁打印机对象并释放所有已分配的资源。如果在打印作业进行过程中销毁打印机，这可能会或可能不会影响该打印作业。

bool QPrinter::abort()

中止当前的打印作业。如果打印作业成功中止，则返回true ；此时调用printerState()将返回QPrinter::Aborted ；否则返回false 。

并非总能中止打印作业。例如，所有数据已发送至打印机，但打印机在被要求时无法或拒绝取消该作业。

bool QPrinter::collateCopies() const

如果选中“多份打印”且“排序”功能已启用，则返回true ；如果选中“多份打印”且“排序”功能已禁用，则返回false 。当“排序”功能禁用时，每页的打印将重复 numCopies() 次，然后才开始打印下一页。当“排序”功能启用时，所有页面将先全部打印完毕，然后才开始打印这些页面的下一份副本。

另请参阅 setCollateCopies()。

QPrinter::ColorMode QPrinter::colorMode() const

返回当前的颜色模式。

另请参阅 setColorMode()。

int QPrinter::copyCount() const

返回将要打印的份数。默认值为 1。

另请参阅 setCopyCount() 和supportsMultipleCopies()。

QString QPrinter::creator() const

返回创建该文档的应用程序的名称。

另请参阅 setCreator()。

QString QPrinter::docName() const

返回文档名称。

另请参阅 setDocName() 和QPrintEngine::PrintEnginePropertyKey 。

QPrinter::DuplexMode QPrinter::duplex() const

返回当前的双工模式。

另请参阅 setDuplex()。

bool QPrinter::fontEmbeddingEnabled() const

如果启用了字体嵌入，则返回true 。

另请参阅 setFontEmbeddingEnabled()。

int QPrinter::fromPage() const

返回待打印页面范围中的第一页页码（即“起始页”设置）。文档中的页面编号遵循“第一页为第1页”的惯例。

默认情况下，此函数返回特殊值 0，表示“起始页”设置未指定。

另请参阅 setFromTo()、toPage() 和pageRanges()。

bool QPrinter::fullPage() const

如果打印机坐标系的原点位于页面的角落，则返回true ；如果位于可打印区域的边缘，则返回false。

有关详细信息和注意事项，请参阅setFullPage()。

另请参阅 setFullPage() 和QPagedPaintDevice::pageLayout()。

bool QPrinter::isValid() const

如果当前选定的打印机是系统中的有效打印机或纯PDF打印机，则返回true ；否则返回false 。

要检测其他错误，请检查QPainter::begin() 或QPrinter::newPage() 的返回结果。

    QPrinter printer;
    printer.setOutputFormat(QPrinter::PdfFormat);
    printer.setOutputFileName("/foobar/nonwritable.pdf");
    QPainter painter;
    if(!painter.begin(&printer)) {// 无法打开文件
        qWarning("failed to open file, is it writable?");
       return 1;
    }
    painter.drawText(10, 10, "Test");
    if(!printer.newPage()) {
        qWarning("failed in flushing page to disk, disk full?");
       return 1;
    }
    painter.drawText(10, 10, "Test 2");
    painter.end();

另请参阅 setPrinterName()。

[override virtual] bool QPrinter::newPage()

重写了：QPagedPaintDevice::newPage()。

指示打印机弹出当前页面，并在新页面上继续打印。若操作成功，则返回true ；否则返回false 。

对非活动状态的 `QPrinter ` 对象调用 `newPage()` 方法将始终失败。

QString QPrinter::outputFileName() const

返回输出文件的名称。默认情况下，该值是一个空字符串（表示打印机不应将内容打印到文件中）。

另请参阅 setOutputFileName() 和QPrintEngine::PrintEnginePropertyKey 。

QPrinter::OutputFormat QPrinter::outputFormat() const

返回该打印机的输出格式。

另请参阅 setOutputFormat()。

QPrinter::PageOrder QPrinter::pageOrder() const

返回当前的页面顺序。

默认的页面顺序为FirstPageFirst 。

另请参阅 setPageOrder()。

QRectF QPrinter::pageRect(QPrinter::Unit unit) const

返回页面在unit 中的矩形；该矩形通常比paperRect()返回的值更小，因为页面边框与纸张之间通常存在边距。

另请参阅 QPagedPaintDevice::pageLayout()。

[override virtual] QPaintEngine *QPrinter::paintEngine() const

重写：QPaintDevice::paintEngine() const。

返回打印机所使用的绘制引擎。

QRectF QPrinter::paperRect(QPrinter::Unit unit) const

返回unit 中的纸张矩形；该矩形通常比pageRect()返回的矩形更大。

另请参阅 pageRect()。

QPrinter::PaperSource QPrinter::paperSource() const

返回打印机的纸张来源。该值可以是Manual ，也可以是打印机纸盘或纸盒。

另请参阅 setPaperSource()。

QPagedPaintDevice::PdfVersion QPrinter::pdfVersion() const

返回该打印机的 PDF 版本。默认值为PdfVersion_1_4 。

另请参阅 setPdfVersion()。

QPrintEngine *QPrinter::printEngine() const

返回打印机所使用的打印引擎。

QString QPrinter::printProgram() const

返回将打印输出发送至打印机的程序名称。

默认情况下返回空字符串；这意味着QPrinter 会根据系统特性智能地进行处理。仅在 X11 环境下，您可以将其设置为其他值以使用特定的打印程序。在其他平台上，此函数返回空字符串。

另请参阅 setPrintProgram() 和setPrinterSelectionOption()。

QPrinter::PrintRange QPrinter::printRange() const

返回QPrinter 的页面范围。在打开打印设置对话框后，此函数将返回用户所选的值。

另请参阅 setPrintRange()。

QString QPrinter::printerName() const

返回打印机名称。该值初始设置为默认打印机的名称。

另请参阅 setPrinterName()。

QString QPrinter::printerSelectionOption() const

返回打印机选项选择字符串。只有在显式设置了打印命令时，此方法才有用。

默认值（空字符串）表示应根据系统情况选择打印机。

任何其他值都表示应使用给定的值。

在 Windows 和 Mac 上，此函数总是返回一个空字符串。

另请参阅 setPrinterSelectionOption() 和setPrintProgram()。

QPrinter::PrinterState QPrinter::printerState() const

返回打印机的当前状态。该状态可能并非总是准确的（例如，如果打印机不具备向操作系统报告其状态的功能）。

int QPrinter::resolution() const

返回打印机当前的预设分辨率，该分辨率由setResolution()函数或打印机驱动程序设置。

另请参阅 setResolution()。

void QPrinter::setCollateCopies(bool collate)

设置打印对话框出现时“分页”复选框的默认值。如果collate 为true，则会启用setCollateCopiesEnabled()。默认值为false。该值将根据用户在打印对话框中的点击操作而发生变化。

另请参阅 collateCopies()。

void QPrinter::setColorMode(QPrinter::ColorMode newColorMode)

将打印机的颜色模式设置为newColorMode ，该模式可以是Color 或GrayScale 。

另请参阅 colorMode()。

void QPrinter::setCopyCount(int count)

将打印份数设置为count 。

打印机驱动程序会读取此设置，并按指定数量打印副本。

另请参阅 copyCount() 和supportsMultipleCopies()。

void QPrinter::setCreator(const QString &creator)

将创建该文档的应用程序名称设置为creator 。

此函数仅适用于 Qt 的 X11 版本。如果未指定创建者名称，则创建者将被设置为“Qt”后跟某个版本号。

另请参阅 creator()。

void QPrinter::setDocName(const QString &name)

将文档名称设置为name 。

在 X11 环境下，文档名会被用作 `QPrintDialog` 中的默认输出文件名。请注意，如果打印机正在将内容打印到文件中，文档名不会影响文件名。此时请使用 `setOutputFile()` 函数。

另请参阅 docName() 和QPrintEngine::PrintEnginePropertyKey 。

void QPrinter::setDuplex(QPrinter::DuplexMode duplex)

启用基于duplex 模式的双面打印。

另请参阅 duplex()。

[protected] void QPrinter::setEngines(QPrintEngine *printEngine, QPaintEngine *paintEngine)

QPrinter 的子类会使用此函数来指定自定义的打印和绘图引擎（分别是printEngine 和paintEngine ）。

QPrinter 该函数不会获取引擎的所有权，因此您需要自行管理这些引擎实例。

请注意，更改引擎将重置打印机的状态及其所有属性。

另请参阅 printEngine()、paintEngine() 和setOutputFormat()。

void QPrinter::setFontEmbeddingEnabled(bool enable)

根据enable 的设置，启用或禁用字体嵌入。

另请参阅 fontEmbeddingEnabled()。

void QPrinter::setFromTo(int from, int to)

设置要打印的页面范围，涵盖由from 和to 指定的页码，其中from 对应该范围中的第一页，to 对应最后一页。

该函数主要用于设置默认值，当调用 setup() 时，用户可在打印对话框中覆盖该默认值。

另请参阅 fromPage()、toPage() 和pageRanges()。

void QPrinter::setFullPage(bool fp)

如果fp 为 true，则启用对整个页面的绘制支持；否则，将绘制范围限制在设备报告的可打印区域内。

默认情况下，全页打印功能处于禁用状态。此时，QPrinter 坐标系的原点与可打印区域的左上角重合。

如果启用了全页打印，则QPrinter 坐标系的原点与纸张本身的左上角重合。 在这种情况下，device metrics 报告的尺寸将与 {QPageSize} 指示的尺寸完全一致。由于打印机的页边距，可能无法在整个物理页面上打印，因此应用程序必须自行处理页边距。

另请参阅 fullPage()、QPagedPaintDevice::pageLayout() 和QPagedPaintDevice::setPageSize()。

void QPrinter::setOutputFileName(const QString &fileName)

将输出文件的名称设置为fileName 。

设置为空（0 或 ""）将禁用写入文件。设置非空名称将启用写入文件。

这可能会更改outputFormat() 的值。如果文件名带有 ".pdf" 后缀，则生成 PDF 文件；如果文件名带有除 ".pdf" 以外的其他后缀，则使用的输出格式为通过setOutputFormat() 分别设置的 Qt 跨平台 PDF 打印引擎。

QPrinter 分别使用 Qt 的跨平台 PDF 打印引擎。如果您能够原生生成此格式（例如，macOS 可以通过其打印引擎生成 PDF），请将输出格式重置为 `NativeFormat`。

另请参阅 outputFileName() 和setOutputFormat()。

void QPrinter::setOutputFormat(QPrinter::OutputFormat format)

将此打印机的输出格式设置为format 。

如果format 与当前设置的值相同，则不会进行任何更改。

如果 `format ` 与当前设置的值相同，则不会进行任何更改。如果 ` ` 为 `NativeFormat `，则 `printerName ` 将被设置为默认打印机。如果未配置任何有效的打印机，则不会进行任何更改。如果您想将 `NativeFormat ` 设置为特定的 `printerName `，请使用 `setPrinterName()`。

另请参阅 outputFormat() 和setPrinterName()。

void QPrinter::setPageOrder(QPrinter::PageOrder pageOrder)

将页面顺序设置为pageOrder 。

页面顺序可以是QPrinter::FirstPageFirst 或QPrinter::LastPageFirst 。应用程序负责读取页面顺序并据此进行打印。

此函数主要用于设置默认值，用户可在打印对话框中覆盖该值。

此函数仅在 X11 环境下受支持。

另请参阅 pageOrder()。

void QPrinter::setPaperSource(QPrinter::PaperSource source)

将纸张来源设置为source 。

仅限 Windows：此选项可在打印过程中更改，并将在下次调用newPage() 时生效

另请参阅 paperSource()。

void QPrinter::setPdfVersion(QPagedPaintDevice::PdfVersion version)

将此打印机的 PDF 版本设置为version 。

如果version 与当前设置的值相同，则不会进行任何更改。

另请参阅 pdfVersion()。

void QPrinter::setPrintProgram(const QString &printProg)

将负责处理打印任务的程序名称设置为printProg 。

在 X11 环境下，此函数用于设置处理 PDF 输出的程序。在其他平台上，此函数无任何作用。

另请参阅 printProgram()。

void QPrinter::setPrintRange(QPrinter::PrintRange range)

将打印范围选项设置为range 。

另请参阅 printRange()。

void QPrinter::setPrinterName(const QString &name)

将打印机名称设置为name 。

如果name 为空，则输出格式将设置为PdfFormat 。

如果name 不是有效的打印机，则不会进行任何更改。

如果name 是有效的打印机，则输出格式将设置为NativeFormat 。

另请参阅 printerName()、isValid() 和setOutputFormat()。

void QPrinter::setPrinterSelectionOption(const QString &option)

将打印机设置为使用option 来选择打印机。option 默认值为null（这意味着Qt应能智能地正确推断），但可以将其设置为其他值以使用特定的打印机选择选项。

如果在打印机处于活动状态时更改了打印机选择选项，当前的打印任务可能会受到影响，也可能不受影响。

此函数在 Windows 或 Mac 上无效。

另请参阅 printerSelectionOption() 和setPrintProgram()。

void QPrinter::setResolution(int dpi)

要求打印机以dpi 为坐标系进行打印，或尽可能接近dpi 坐标系。

此设置会影响坐标系，例如由QPainter::viewport() 返回的坐标系。

为了在所有平台上生效，必须在调用QPainter::begin() 之前调用此函数。

另请参阅 resolution() 和QPagedPaintDevice::setPageSize()。

QList<QPrinter::PaperSource> QPrinter::supportedPaperSources() const

返回该打印机支持的纸张尺寸。

返回值要么是与QPrinter::PaperSource 枚举中的条目相匹配的值，要么是驱动程序特有的值。驱动程序特有的值大于在wingdi.h中声明的常量DMBIN_USER。

QList<int> QPrinter::supportedResolutions() const

返回打印机声称支持的分辨率列表（即每英寸点数（dpi）的整数列表）。

对于所有打印操作均直接输出为 PDF 的 X11 环境，该函数将始终返回一个仅包含 PDF 分辨率（即 72，72 dpi——但请参阅PrinterMode ）的单项列表。

bool QPrinter::supportsMultipleCopies() const

如果打印机支持在一个打印任务中打印同一文档的多份副本，则返回true ；否则返回false。

在大多数系统上，此函数将返回 true。但在不支持 CUPS 的 X11 系统上，此函数将返回 false。这意味着应用程序必须通过将同一文档打印所需次数来处理副本数量。

另请参阅 setCopyCount() 和copyCount()。

int QPrinter::toPage() const

返回待打印页面范围中的最后一页页码（即“到第X页”设置）。文档中的页面编号遵循“第一页为第1页”的惯例。

默认情况下，此函数返回特殊值 0，表示“到页”设置未设置。

程序员有责任读取此设置并据此进行打印。

另请参阅 setFromTo()、fromPage() 和pageRanges()。