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，表示未设置 "from page "设置。

另请参阅 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.setOutputFormat(QPrinter::PdfFormat); printer.setOutputFileName("/foobar/nonwritable.pdf")；    QPainterpainter;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() 常量。

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

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 。

此函数仅适用于 X11 版本的 Qt。如果未指定创建者名称，创建者将被设置为 "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() 设置的输出格式。

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 为空（这意味着 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 ）。

bool QPrinter::supportsMultipleCopies() const

如果打印机支持在一次作业中打印多份相同文档，则返回true ；否则返回 false。

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

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

int QPrinter::toPage() const

返回要打印的页面范围（"至页 "设置）中最后一页的页码。文档中的页数按照惯例进行编号，即第一页为第 1 页。

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

程序员有责任读取该设置并进行相应的打印。

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