class QPrinter#

QPrinter 类是一个打印设备，它将页面内容打印到打印机。更多...

Inheritance diagram of PySide6.QtPrintSupport.QPrinter

概要#

方法#

注意

此文档可能包含自动从C++转换为Python的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译有误，也可以通过在https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细说明#

此设备代表一系列打印输出页，其使用方式几乎与其他绘图设备（如QWidget和QPixmap）完全相同。提供了一组额外的函数来管理特定于设备的特征，例如方向和分辨率，并可在生成文档时逐步遍历页面。

当在Windows或macOS中将直接打印到打印机时，QPrinter 会使用内置的打印机驱动程序。在X11上，QPrinter 会使用通用Unix打印系统（CUPS）将PDF输出发送到打印机。作为替代，可以使用 printProgram() 函数来指定用于替代系统默认的命令或工具。

请注意，在无效的打印机上设置纸张大小和分辨率等参数的行为是未定义的。您可以在更改任何参数之前使用 isValid() 验证。

QPrinter 支持许多参数，其中大多数可以通过 print dialog 让最终用户进行更改。通常，QPrinter 会将这些功能传递给底层的 QPrintEngine 。

最重要的参数包括

  • setPageLayout() 通知 QPrinter 使用哪种页面方向以及期望打印机制提供的大小。

  • setResolution() 通知 QPrinter 希望打印机制提供的分辨率为每英寸多少点（DPI）。

  • setFullPage() 通知 QPrinter 是否要处理整页还是只处理打印机制可以绘制的那部分。

  • setCopyCount() 通知 QPrinter 应该打印多少份文档。

许多这些功能只能在实际打印开始之前调用（即在调用 QPainter::begin() 之前）。这通常是有意义的，因为例如，在打印中途无法更改副本数量。还有一些用户设置的设置（通过打印机对话框），应用程序应遵守。有关更详细的信息，请参阅 QAbstractPrintDialog 的文档。

当调用 QPainter::begin() 时，它会为操作 QPrinter 的新页面做好准备，使 QPainter 能够立即用于绘制文档的第一页。一旦绘制了第一页，就可以调用 newPage() 来请求一个新的空白页面进行绘制，或调用 QPainter::end() 来完成打印。在绘制第二页和后续所有页面之前，都会通过调用 newPage() 来进行准备。

文档中的第一页不需要在调用 newPage() 之前。只有在您需要在打印文档的起始处插入空白页时，才需要在 QPainter::begin() 之后调用 newPage() 。同样，在绘制文档的最后一页之后调用 newPage() 会导致在打印文档的末尾添加一个后续的空白页。

如果您想终止打印作业，abort() 将尽力停止打印。它可能会取消整个作业或只是部分作业。

由于 QPrinter 可以打印到任何 QPrintEngine 子类，因此可以通过继承 QPrintEngine 并重新实现其接口来扩展打印支持，以便涵盖新的打印子系统类型。

另请参阅

QPrintDialog Qt 打印支持

class PrinterMode#

此枚举描述了打印机应工作的模式。它基本上预设了一个特定的分辨率和工作模式。

常量

描述

QPrinter.ScreenResolution

将打印设备的分辨率设置为屏幕分辨率。这有一个很大的优点，即当在打印机上绘画时，得到的结果将与屏幕上的可见输出大致匹配。它是使用最简单的，因为屏幕和打印机上的字体度量是相同的。这是默认值。ScreenResolution 将生成低于 HighResolution 的输出质量，应仅用于草稿。

QPrinter.PrinterResolution

此属性已弃用。它在Unix上相当于ScreenResolution，在Windows和Mac上相当于HighResolution。由于ScreenResolution和HighResolution的区别，使用此值可能导致无法迁移的打印机代码。

QPrinter.HighResolution

在Windows上，将打印机分辨率设置为正在使用的打印机的定义分辨率。对于PDF打印，将PDF驱动程序的分辨率设置为1200 dpi。

注意

在QPrinter设备上渲染文本时，重要的是要认识到，当文本大小以点为单位指定时，其大小与设备本身指定的分辨率无关。因此，当将文本与图形结合使用时，指定字体大小为像素可能很有用，以确保它们的相对大小符合预期。

class PageOrder#

此枚举类型由QPrinter用于告诉应用程序如何打印。

常量

描述

QPrinter.FirstPageFirst

应首先打印编号最低的页面。

QPrinter.LastPageFirst

应首先打印编号最高的页面。
class ColorMode#

此枚举类型用来表示QPrinter是否应打印彩色或灰度。

常量

描述

QPrinter.Color

如果可用则打印彩色，否则打印灰度。

QPrinter.GrayScale

即使是彩色打印机，也以灰度打印。
class PaperSource#

此枚举类型指定QPrinter应使用的纸张来源。QPrinter不会检查纸张来源是否可用；它只是使用这些信息来尝试设置纸张来源。它是否会设置纸张来源取决于打印机是否有该特定来源。

警告

目前此功能仅支持Windows。

常量

描述

QPrinter.Auto

QPrinter.Cassette

QPrinter.Envelope

QPrinter.EnvelopeManual

QPrinter.FormSource

QPrinter.LargeCapacity

QPrinter.LargeFormat

QPrinter.Lower

QPrinter.MaxPageSource

已弃用，请改用LastPaperSource。

QPrinter.Middle

QPrinter.Manual

QPrinter.OnlyOne

QPrinter.Tractor

QPrinter.SmallFormat

QPrinter.Upper

QPrinter.CustomSource

Qt不认识的打印机定义的PaperSource。

QPrinter.LastPaperSource

当前最高的有效PaperSource值，目前是CustomSource。
class PrinterState#

常量

描述

QPrinter.Idle

QPrinter.Active

QPrinter.Aborted

QPrinter.Error
class OutputFormat#

OutputFormat 枚举用于描述用于打印的 QPrinter 应该使用的格式。

常量

描述

QPrinter.NativeFormat

QPrinter 将使用其运行的平台定义的方法进行打印。当直接打印到打印机时，该模式是默认模式。

QPrinter.PdfFormat

QPrinter 将生成可搜索的PDF文件作为输出。当打印到文件时，该模式是默认模式。

另请参阅

outputFormat() setOutputFormat() setOutputFileName()

class PrintRange#

用于指定打印范围选择选项。

常量

描述

QPrinter.AllPages

应该打印所有页面。

QPrinter.Selection

只打印选中内容。

QPrinter.PageRange

应打印指定的页面范围。

QPrinter.CurrentPage

只打印当前页面。

另请参阅

setPrintRange() printRange() PrintRange

class Unit#

该枚举类型用于指定页大小和纸张大小的测量单位。

常量

描述

QPrinter.Millimeter

QPrinter.Point

QPrinter.Inch

QPrinter.Pica

QPrinter.Didot

QPrinter.Cicero

QPrinter.DevicePixel

注意 Point 和 DevicePixel 之间的区别。Point 单位被定义为 1/72 英寸，而 DevicePixel 单位是分辨率相关的，并且基于打印机上的实际像素或点。

class DuplexMode#

该枚举用于指示打印是否会在每张纸的单面或双面上进行（单面或双面打印）。

常量

描述

QPrinter.DuplexNone

仅单面（单面打印）。

QPrinter.DuplexAuto

根据打印机的默认设置来决定是否使用双面打印。

QPrinter.DuplexLongSide

每张纸的两面都用于打印。在打印第二面之前，纸张会翻转到最长边缘。

QPrinter.DuplexShortSide

每张纸的两面都用于打印。在打印第二面之前，纸张会翻转到最短边缘。
__init__(printer[, mode=QPrinter.PrinterMode.ScreenResolution])#
参数：

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

__init__([mode=QPrinter.PrinterMode.ScreenResolution])
参数：

mode – PrinterMode

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

abort()#
返回类型：

bool

终止当前打印任务。如果成功终止并返回 true，则 printerState() 将返回 Aborted；否则返回 false。

并非总能终止打印任务。例如，所有数据都已发送至打印机，但打印机无法或不会在请求时取消任务。

collateCopies()#
返回类型：

bool

当选择多份副本时，如果已开启合并副本功能，则返回 true；如果关闭，则返回 false。当合并副本功能关闭时，将根据 numCopies() 值重复打印每一页，然后开始打印下一页。当开启合并副本功能时，在开始下一份副本之前，所有页面都已被打印。

另请参阅

setCollateCopies()

colorMode()#
返回类型：

颜色模式

返回当前颜色模式。

另请参阅

setColorMode()

copyCount()#
返回类型：

int

返回将被打印的副本数量。默认值为 1。

creator()#
返回类型：

str

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

另请参阅

setCreator()

docName()#
返回类型：

str

返回文档名称。

duplex()#
返回类型：

双面打印模式

返回当前双面打印模式。

另请参阅

setDuplex()

fontEmbeddingEnabled()#
返回类型：

bool

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

fromPage()#
返回类型：

int

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

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

注意

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

另请参阅

setFromTo() toPage() pageRanges()

fullPage()#
返回类型：

bool

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

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

isValid()#
返回类型：

bool

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

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

要检测其他失败情况，请检查QPainter::begin()或newPage()的输出。

printer = QPrinter()
printer.setOutputFormat(QPrinter.PdfFormat)
printer.setOutputFileName("/foobar/nonwritable.pdf")
painter = QPainter()
if not painter.begin(printer): # failed to open file
    qWarning("failed to open file, is it writable?")
    return 1

painter.drawText(10, 10, "Test")
if not printer.newPage():
    qWarning("failed in flushing page to disk, disk full?")
    return 1

painter.drawText(10, 10, "Test 2")
painter.end()

另请参阅

setPrinterName()

outputFileName()#
返回类型：

str

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

outputFormat()#
返回类型：

OutputFormat

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

另请参阅

setOutputFormat()

pageOrder()#
返回类型：

PageOrder

返回当前页面顺序。

默认页面顺序为 FirstPageFirst。

另请参阅

setPageOrder()

pageRect(arg__1)#
参数：

arg__1 – Unit

返回类型：

QRectF

以 unit 返回页面的矩形；这通常小于 paperRect()，因为页面通常在边界和纸张之间存在页边距。

另请参阅

pageLayout()

paperRect(arg__1)#
参数：

arg__1 – Unit

返回类型：

QRectF

以 unit 返回纸张的矩形；这通常大于 pageRect() .

另请参阅

pageRect()

paperSource()#
返回类型：

PaperSource

返回打印机的纸张来源。这是 Manual 或者打印机纸盒或纸盒。

另请参阅

setPaperSource()

pdfVersion()#
返回类型：

PdfVersion

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

另请参阅

setPdfVersion()

printEngine()#
返回类型：

QPrintEngine

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

printProgram()#
返回类型：

str

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

默认返回空字符串；这意味着 QPrinter 将以一种系统相关的方式尝试智能处理。仅限X11平台，您可以设置为不同的值来使用特定的打印程序。在其他平台上，此设置返回空字符串。

另请参阅

setPrintProgram() setPrinterSelectionOption()

printRange()#
返回类型：

打印范围

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

另请参阅

setPrintRange()

printerName()#
返回类型：

str

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

另请参阅

setPrinterName()

printerState()#
返回类型：

打印机状态

返回打印机的当前状态。这可能有误（例如，如果打印机无法将状态报告给操作系统）。

resolution()#
返回类型：

int

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

另请参阅

setResolution()

setCollateCopies(collate)#
参数：

collate – bool

设置打印对话框出现时折叠框的默认值。如果 collate 为 true，将启用 setCollateCopiesEnabled()。默认值为 false。此值将由用户在打印对话框中按下的键来更改。

另请参阅

collateCopies()

setColorMode(arg__1)#
参数：

arg__1 – ColorMode

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

另请参阅

colorMode()

setCopyCount(arg__1)#
参数：

arg__1 – int

将打印机的复制数量设置为 count。

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

setCreator(arg__1)#
参数：

arg__1 – str

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

此功能仅适用于 Qt 的 X11 版本。如果没有指定创建者名称，则创建者将被设置为“Qt”后跟一些版本号。

另请参阅

creator()

setDocName(arg__1)#
参数：

arg__1 – str

将文档名称设置为 name。

在 X11 中，文档名称例如在 QPrintDialog 中用作默认输出文件名。请注意，如果打印机打印到文件，则文档名称不会影响文件名。为此请使用 setOutputFile() 函数。

setDuplex(duplex)#
参数：

duplex – DuplexMode

根据 duplex 模式启用双面打印。

另请参阅

duplex()

setEngines(printEngine, paintEngine)#
参数：

此函数由 QPrinter 的子类用于指定自定义打印和绘图引擎（分别对应 printEngine 和 paintEngine）。

QPrinter 不拥有这些引擎的所有权，因此您需要自己管理这些引擎实例。

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

另请参阅

printEngine() paintEngine() setOutputFormat()

setFontEmbeddingEnabled(enable)#
参数：

enable – 布尔类型

根据 enable 启用或禁用字体嵌入。

另请参阅

fontEmbeddingEnabled()

setFromTo(fromPage, toPage)#
参数：

  • fromPage – 整数

  • toPage – 整数

设置要打印的页面范围，以包括由 from 和 to 指定的页面号，其中 from 对应于范围内的第一页，而 to 对应于最后一页。

注意

文档中的页面按惯例编号，即第一页为第 1 页。但是，如果将 from 和 to 均设置为 0，则将打印 整个文档。

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

setFullPage(arg__1)#
参数：

arg__1 – 布尔类型

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

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

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

另请参阅

fullPage() setPageSize()

setOutputFileName(arg__1)#
参数：

arg__1 – str

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

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

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

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

setOutputFormat(format)#
参数：

format – OutputFormat

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

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

如果 format 是 NativeFormat，则 printerName 将设置为默认打印机。如果没有配置有效的打印机，则不会进行任何更改。如果您想使用特定的 printerName 将 NativeFormat 设置，则请使用 setPrinterName()。

setPageOrder(arg__1)#
参数：

arg__1 – PageOrder

设置页面顺序为 pageOrder。

页面顺序可以是 FirstPageFirst 或 LastPageFirst 。应用程序负责读取页面顺序并相应地打印。

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

此功能仅在X11下受支持。

另请参阅

pageOrder()

setPaperSource(arg__1)#
参数：

arg__1 – PaperSource

将纸张来源设置设置为 source。

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

另请参阅

paperSource()

setPdfVersion(version)#
参数：

version – PdfVersion

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

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

另请参阅

pdfVersion()

setPrintProgram(arg__1)#
参数：

arg__1 – str

将执行打印作业的程序名称设置为 printProg。

在X11上，此函数将程序设置为调用PDF输出。在其他平台上，它没有作用。

另请参阅

printProgram()

setPrintRange(range)#
参数：

range – PrintRange

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

另请参阅

printRange()

setPrinterName(arg__1)#
参数：

arg__1 – str

将打印机名称设置为 name。

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

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

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

setResolution(arg__1)#
参数：

arg__1 – int

请求打印机以 dpi 或尽可能接近 dpi 的数值打印。

此设置影响由 QPainter::viewport() 等返回的坐标系。

必须在 QPainter::begin() 调用之前调用此函数，以便在所有平台上产生影响。

supportedResolutions()#
返回类型：

int 列表

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

在 X11 中，所有打印都直接输出到 PDF，此函数将始终返回只包含 PDF 分辨率的一个元素列表，即 72（72 dpi – 但请参阅 PrinterMode ）。

supportsMultipleCopies()#
返回类型：

bool

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

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

toPage()#
返回类型：

int

返回要打印的页面范围内的最后一页编号（“到页”设置）。文档中的页面根据惯例编号，即第一页是第 1 页。

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

注意

如果fromPage() 和 toPage() 都返回0，这意味着将打印“整个文档”。

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