QPrinter 类

成员函数文档

[显式] QPrinter::QPrinter(QPrinter::PrinterMode mode = ScreenResolution)

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

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

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

[虚拟 noexcept] QPrinter::~QPrinter()

销毁打印机对象并释放任何分配的资源。如果在打印作业进行中销毁打印机，则此操作可能会或可能不会影响打印作业。

bool QPrinter::abort()

终止当前的打印任务。如果成功终止打印任务并且printerState()将返回QPrinter::Aborted，则返回true；否则返回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

返回要打印的页面范围的起始页码（“起始页”设置）。文档中的页面根据惯例编号，即第一页为第一页。

默认情况下，此函数返回一个特殊值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)) { // failed to open file
        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。

[覆盖虚函数] 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。

[重写虚拟] 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。

[受保护] 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为真，则启用对整个页面的绘图支持；否则将绘图限制为设备报告的可打印区域。

默认情况下，全页打印被禁用。在这种情况下，QPrinter坐标系的原点与可打印区域的左上角重合。

如果启用全页打印，则QPrinter坐标系的原点与纸张本身的左上角重合。在这种情况下，设备度量将报告与{QPageSize}指示相同的尺寸。由于打印机的边距，可能无法打印整个物理页面，因此应用程序必须自己计算边距。

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

void QPrinter::setOutputFileName(const QString &fileName)

设置输出文件名为 fileName。

设置空或空字符串（0或""）将禁用文件打印。设置非空字符串将启用文件打印。

这可能会改变 outputFormat 的值。如果文件名以 ".pdf" 后缀结尾，则生成 PDF。如果文件名没有 ".pdf" 后缀，则使用的输出格式是使用 setOutputFormat 设置的格式。

QPrinter 使用 Qt 的跨平台 PDF 打印引擎。如果您可以原生生成此格式，例如 macOS 可以从其打印引擎生成 PDF，请将输出格式设置为 NativeFormat。

另请参阅outputFileName() 和 setOutputFormat。

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

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

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

如果 format 是 NativeFormat，则 printerName 将设置为默认打印机。如果没有配置有效的打印机，则不会进行更改。如果您希望使用特定的 printerName 设置 NativeFormat，请使用 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为空（这意味着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

返回打印机所支持的分辨率列表（一个包含每英寸点的整数的列表）。

对于所有直接打印到PDF的X11，此函数将始终返回一个只包含PDF分辨率的单项列表，即72（72 dpi – 但请参阅PrinterMode）。

布尔型 QPrinter::supportsMultipleCopies() const

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

在大多数系统中，此函数将返回 true。然而，在X11系统中，如果不支持CUPS，此函数将返回 false。这意味着应用程序必须通过多次打印同一份文件来处理副本数量。

另请参阅setCopyCount() 和 copyCount。

整数 QPrinter::toPage() const

返回要打印的页面范围中的最后一页的页码（“到页”设置）。文档中的页面按照惯例编号，第一页为第1页。

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

程序员负责读取此设置并根据相应的打印。

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