QPrinter、QPrinterInfo、QPageLayout

QPrinter

一、描述

QPrinter 类是在打印机上绘制的绘制设备，其使用方式与其他绘图设备（如 QWidget 和 QPixmap）几乎完全相同。提供了一组附加功能来管理特定于设备的功能，例如方向、分辨率、在生成文档时逐步浏览文档中的页面。

在无效打印机上设置参数（如纸张尺寸和分辨率）是未定义的。可以在更改参数之前使用 isValid() 来验证。

QPrinter 支持许多参数，用户可以通过打印对话框更改大部分参数。许多函数只能在实际打印开始之前调用（即在调用 QPainter::begin() 之前）。

当 QPainter::begin() 被调用时，它所操作的 QPrinter 为新页面做好准备，使 QPainter 可以立即用于绘制文档的第一页。绘制完第一页后，可以调用 newPage() 来请求绘制新的空白页，或者可以调用 QPainter::end() 来完成打印。

二、类型成员

1、enum QPrinter::ColorMode：此枚举指示是否应进行彩色打印。

• Color：如果可用，则以彩色打印，否则以灰度打印。
• GrayScale：以灰度打印。

2、enum QPrinter::DuplexMode：此枚举用于指示是在每张纸的单面或双面打印。

• DuplexNone：仅单面打印。
• DuplexAuto：使用打印机的默认设置。
• DuplexLongSide：每张纸的两面都用于打印。在打印第二面之前将纸张翻转其最长边。
• DuplexShortSide：每张纸的两面都用于打印。在打印第二面之前将纸张翻转其最短边。

3、enum QPrinter::OutputFormat：此枚举用于描述打印的格式。

• NativeFormat：将使用运行平台定义的方法打印输出。
• PdfFormat：将其输出生成为 PDF 文件。

4、enum QPrinter::PageOrder：此枚举指示应用程序如何打印。

• FirstPageFirst：应首先打印最低编号的页面。
• LastPageFirst：应首先打印最高编号的页面。

5、enum QPrinter::PaperSource：此枚举指定要使用的纸张来源。QPrinter 不检查纸张来源是否可用，它只是使用这些信息来尝试设置纸张来源。是否设置纸张来源取决于打印机是否具有该特定来源。仅适用于 Windows。

• 略

6、enum QPrinter::PrintRange：此枚举用于指定打印范围选项。

• AllPages：应打印所有页面。
• Selection：只应打印选择的页面。
• PageRange：应打印指定的页面范围。
• CurrentPage：只打印当前页。

7、enum QPrinter::PrinterMode：此枚举描述了打印机工作的模式。

• ScreenResolution：将打印设备的分辨率设置为屏幕分辨率。即在打印机上绘制时获得的结果将与屏幕上的可见输出完全匹配。屏幕和打印机上的字体规格是相同的。这是默认值。 ScreenResolution 将产生比 HighResolution 更低质量的输出。
• HighResolution：在 Windows 上，将打印机分辨率设置为为正在使用的打印机定义的分辨率。对于 PDF 打印，将 PDF 驱动程序的分辨率设置为 1200 dpi。

8、enum QPrinter::PrinterState：打印状态。

• Idle：空闲
• Active：激活
• Aborted：中止
• Error：出错

9、enum QPrinter::Unit：此枚举用于指定页面和纸张尺寸的测量单位。

• Millimeter：毫米
• Point：点，定义为 1/72 英寸。
• Inch：英寸
• Pica
• Didot
• Cicero
• DevicePixel：取决于分辨率，并基于打印机上的实际像素或点。

三、成员函数

1、bool abort()

中止当前的打印运行。如果打印运行成功中止，则返回 true，并且 printerState() 将返回 Aborted；否则返回 false。

并非总是可以中止打印作业。例如，所有数据都已发送到打印机时打印机不能或不会在要求时取消作业。

2、int fromPage()

返回要打印的页面范围内第一页的编号。页面按照第一页为第 1 页的约定进行编号。

特殊值 0 则表示未设置。

如果 fromPage() 和 toPage() 都返回 0，表示将打印整个文档。

      int toPage()

返回要打印的页面范围中最后一页的编号。

特殊值 0表示未设置“到页面”设置。

如果 fromPage() 和 toPage() 都返回 0，表示将打印整个文档。

3、bool isValid()

当前选择的打印机是否是系统中的有效打印机或是纯 PDF 打印机。

    QPrinter printer;
    printer.setOutputFormat(QPrinter::PdfFormat);
    printer.setOutputFileName("/foobar/nonwritable.pdf");
    QPainter painter;
    if (! painter.begin(&printer)) 
    {
        qWarning("打开文件失败，确定文件是否可写?");
        return 1;
    }
    painter.drawText(10, 10, "Test");
    if (! printer.newPage()) 
    {
        qWarning("将页面刷新到磁盘失败，磁盘已满?");
        return 1;
    }
    painter.drawText(10, 10, "Test 2");
    painter.end();

4、bool newPage()

告诉打印机弹出当前页面并继续在新页面上打印。返回是否打印成功。

在不活动的 QPrinter 对象上调用 newPage() 总是会失败。

5、QRectF paperRect(QPrinter::Unit unit)

返回纸张的矩形。这通常比 pageRect() 大。 

6、QPrinter::PrinterState printerState()

返回打印机的当前状态。可能并不准确（有的打印机没有向操作系统报告其状态的功能）。 

7、void setCollateCopies(bool collate)

设置打印对话框出现时主动分页复选框的默认值。

    QPrinter printer;
    printer.setCollateCopies(true);
    QPrintDialog dialog(&printer, nullptr);
    if (dialog.exec())
    {
    }

8、void setCopyCount(int count)

设置要打印的份数。打印机驱动程序读取此设置并打印指定份数。设置的值不能超过打印驱动程序允许的最大值。

9、void setCreator(const QString &creator)

设置创建文档的应用程序的名称。此功能仅适用于 X11 版本的 Qt。

10、void setDocName(const QString &name)

设置文档名称。文档名称用作输出文件的默认名称。如果打印机正在打印到文件，则设置不会影响文件名。

11、void setFontEmbeddingEnabled(bool enable) 【没搞明白怎么用的】

设置是否启用字体嵌入。

12、void setFromTo(int from, int to)

设置要打印的页面范围的默认值，其中 from 对应于范围中的第一页，to 对应于最后一页。

文档中的页面按照第一页为第 1 页的约定进行编号。但是，如果 from 和 to 都设置为 0，则将打印整个文档。

13、void setFullPage(bool fp) 

如果 fp 为 true，则支持在整个页面上绘制；否则将绘制限制在设备的可打印区域。

禁用整页打印时 QPrinter 坐标系的原点与可打印区域的左上角重合。

如果启用整页打印，则 QPrinter 坐标系的原点与纸张本身的左上角重合。由于打印机的页边距，可能无法在整个物理页上打印，因此应用程序必须自己考虑页边距。

    QPrinter printer;
    QPrintDialog dialog(&printer, nullptr);
    if (dialog.exec())
    {
        printer.setFullPage(true);
        QPageLayout layout =  printer.pageLayout();
        layout.setPageSize(QPageSize(QPageSize::A4));
        layout.setMargins(QMarginsF(30,30,30,30));
        printer.setPageLayout(layout);
        QPainter painter(&printer);
        painter.drawText(QRect(0,0,500,500), tr("黄河之水天上来"));
    }

    QPrinter printer;
    QPrintDialog dialog(&printer, nullptr);
    if (dialog.exec())
    {
        printer.setFullPage(true);
        QPageLayout layout =  printer.pageLayout();
        layout.setPageSize(QPageSize(QPageSize::A4));
//        layout.setMargins(QMarginsF(30,30,30,30));
        printer.setPageLayout(layout);
        QPainter painter(&printer);
        painter.drawText(QRect(0,0,500,500), tr("黄河之水天上来"));
    }

 

    QPrinter printer;
    QPrintDialog dialog(&printer, nullptr);
    if (dialog.exec())
    {
        printer.setFullPage(false);
        QPageLayout layout =  printer.pageLayout();
        layout.setPageSize(QPageSize(QPageSize::A4));
        layout.setMargins(QMarginsF(30,30,30,30));
        printer.setPageLayout(layout);
        QPainter painter(&printer);
        painter.drawText(QRect(0,0,500,500), tr("黄河之水天上来"));
    }

 

14、void setOutputFileName(const QString &fileName)

设置输出文件的名称。

这可以改变 outputFormat() 的值。如果文件名带有“.pdf”后缀，则生成 PDF。如果文件名的后缀不是“.pdf”，则使用的输出格式是 setOutputFormat() 设置的格式。

QPrinter 默认使用 Qt 的跨平台 PDF 打印引擎。如果可以本机生成格式，例如 macOS 可以从其打印引擎生成 PDF，建议将输出格式设置回 NativeFormat。

15、void setPrintProgram(const QString &printProg)

设置应该执行打印作业的程序的名称。在 X11 上，此函数将程序设置为使用 PDF 输出调用。在其他平台上调用没有效果。

16、void setPrinterName(const QString &name)

设置打印机名称。

• 如果名称为空，则输出格式将设置为 PdfFormat。
• 如果名称不是有效的打印机，则不会进行任何更改。
• 如果名称是有效的打印机，则输出格式将设置为 NativeFormat。

17、void setResolution(int dpi)

要求打印机以 dpi 或尽可能接近 dpi 进行打印。

必须在 QPainter::begin() 之前调用才能有效。

18、bool supportsMultipleCopies()

打印机是否支持在一个作业中打印同一文档的多个副本。

19、QListPaperSource> supportedPaperSources()

返回此打印机支持的纸张尺寸。此功能仅在 Windows 中可用。

这些值可以是与 QPrinter::PaperSource 枚举中的条目匹配的值，也可以是驱动程序特定值。驱动程序特定值大于在wingdi.h 中声明的常数 DMBIN_USER。

    QPrinter printer;
    QPrintDialog dialog(&printer, nullptr);
    if (dialog.exec())
    {
        qDebug()<supportedPaperSources();//选择打印机后再输出此值
        QPainter painter(&printer);
        painter.drawText(QRect(0,0,500,500), Qt::AlignCenter | Qt::TextWordWrap, tr("黄河之水天上来"));
    }

20、QList supportedResolutions()

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

21、bool newPage()

开始一个新页面。返回是否成功。

22、bool setPageLayout(const QPageLayout &newPageLayout)

设置页面布局。应该在调用 QPainter::begin() 之前调用它，或者在调用 newPage() 以将新页面布局应用到新页面之前调用它。

返回是否设置成功。

---

QPrinterInfo

一、描述

QPrinterInfo 类提供对现有打印机信息的访问。

二、成员函数

1、【static】QStringList availablePrinterNames()

返回此系统上所有可用打印机名称的列表。

2、【static】QList<QPrinterInfo> availablePrinters()

返回此系统上所有可用打印机的 QPrinterInfo 对象列表。

3、QPrinter::ColorMode defaultColorMode()

返回此打印机的默认颜色模式。

4、QPrinter::DuplexMode defaultDuplexMode()

返回此打印机的默认双面模式。

5、QPageSize defaultPageSize()

返回此打印机的当前默认页面大小。

6、【static】QPrinterInfo defaultPrinter()

返回系统上的默认打印机。

使用前应使用 isNull() 检查返回值，以防没有默认打印机。

在某些系统上，可能有可用的打印机，但它们都没有设置为默认打印机。

7、【static】QString defaultPrinterName()

返回当前的默认打印机名称。

8、QString description()

打印机的描述。

9、bool isDefault()

此打印机当前是否为默认打印机。

10、bool isNull()

此 QPrinterInfo 对象是否包含打印机定义。

11、bool isRemote()

返回此打印机是否为远程网络打印机。

12、QString makeAndModel()

打印机的品牌和型号。

13、QPageSize maximumPhysicalPageSize()

此打印机支持的最大物理页面大小。

      QPageSize minimumPhysicalPageSize()

返回此打印机支持的最小物理页面大小。

14、【static】QPrinterInfo printerInfo(const QString &printerName)

根据名称获取打印机信息。

15、QString printerName()

返回打印机的名称。这是用于识别打印机的唯一 ID，可能不适合人类阅读。

16、QPrinter::PrinterState state()

返回此打印机的当前状态。

17、QListColorMode> supportedColorModes()

返回此打印机支持的颜色模式。

18、QListDuplexMode> supportedDuplexModes()

返回此打印机支持的双面模式列表。

19、QList<QPageSize> supportedPageSizes()

返回此打印机支持的页面尺寸列表。

20、QList supportedResolutions()

返回此打印机支持的分辨率列表。

21、bool supportsCustomPageSizes()

返回此打印机是否支持自定义页面尺寸。

---

QPageLayout

一、描述

此类描述了页面的大小、方向和边距。

二、类型成员

1、enum QPageLayout::Mode：此枚举定义页面布局模式

• StandardMode：绘制矩形包括边距，边距必须介于最小值和最大值之间。
• FullPageMode：绘制矩形不包括边距，边距可以是任意值，必须手动管理。

2、enum QPageLayout::Orientation：此枚举类型定义页面方向

• Portrait：页面大小以默认方向使用
• Landscape：页面大小旋转90度

 3、enum QPageLayout::Unit：此枚举类型用于指定页面布局和边距的度量单位。

• Millimeter：毫米
• Point：1/72 英寸
• Inch
• Pica
• Didot
• Cicero

三、部分成员函数

1、QRectF fullRect()

返回当前布局单位中的整个页面矩形。

页面矩形考虑页面大小和页面方向，但不考虑页边距。

2、QRectF fullRect(QPageLayout::Unit units)

以所需单位返回整个页面矩形。页面矩形考虑页面大小和页面方向，但不考虑页边距。

3、QRect fullRectPixels(int resolution)

返回给定分辨率下以设备像素为单位的整页矩形。

页面矩形考虑页面大小和页面方向，但不考虑页边距。

4、QRect fullRectPoints()

返回以 Postscript Points（1/72 英寸）为单位的整页矩形。

页面矩形考虑页面大小和页面方向，但不考虑页边距。

5、bool isEquivalentTo(const QPageLayout &other)

当前页面布局是否与 other 等效，即大小、边距和方向都相等。

6、bool isValid()

当前页面布局是否有效。

7、QMarginsF margins(QPageLayout::Unit units)

使用请求的单位返回页面布局的边距。

8、QMargins marginsPixels(int resolution)

返回给定分辨率的页面布局的边距（以设备像素为单位）。

9、QMargins marginsPoints()

返回以 Postscript Points（1/72 英寸）为单位的页面布局的边距。

10、QMarginsF maximumMargins()

返回将应用的最大边距。最大边距 = 页面的完整大小 - 设置的最小边距。

11、QMarginsF minimumMargins()

返回页面布局的最小边距。

12、QPageSize pageSize()

返回页面布局的页面大小。

QPageSize 始终以纵向定义。要获得将设置方向考虑在内的大小，必须使用 fullRect()。

13、QRectF paintRect()

返回当前布局单位中的可绘制矩形。可绘制矩形考虑了页面大小、方向和边距。

14、QRectF paintRect(QPageLayout::Unit units)

以所需单位返回可绘制矩形。

15、QRect paintRectPixels(int resolution)

返回给定分辨率的圆形设备像素中的可绘制矩形。

16、QRect paintRectPoints()

返回以圆角 Postscript Points（1/72 英寸）为单位的可绘制矩形。