PySide6.QtPrintSupport.QPrinter

class QPrinter

QPrinter 类是一个在打印机上绘制的绘制设备。更多…

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 未知

QPrinter.LastPaperSource

最高有效的纸张来源值，目前为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__([mode=QPrinter.PrinterMode.ScreenResolution])
Parameters:

mode – PrinterMode

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

__init__(printer[, mode=QPrinter.PrinterMode.ScreenResolution])
Parameters:

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

abort()
Return type:

布尔

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

并不总是能够中止打印任务。例如，所有数据已经发送到打印机，但打印机无法或不愿意在请求时取消任务。

collateCopies()
Return type:

布尔

如果选择了多份副本时启用了排序，则返回true。如果选择了多份副本时未启用排序，则返回false。当排序关闭时，每页的打印将在开始下一页之前重复numCopies()次。启用排序后，所有页面将在开始下一页的副本之前打印。

另请参阅

setCollateCopies()

colorMode()
Return type:

ColorMode

返回当前的颜色模式。

另请参阅

setColorMode()

copyCount()
Return type:

整数

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

creator()
Return type:

字符串

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

另请参阅

setCreator()

docName()
Return type:

字符串

返回文档名称。

duplex()
Return type:

DuplexMode

返回当前的双工模式。

另请参阅

setDuplex()

fontEmbeddingEnabled()
Return type:

布尔

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

fromPage()
Return type:

整数

返回要打印的页面范围中的第一页的编号（“起始页”设置）。文档中的页面按照第一页为第1页的惯例进行编号。

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

注意

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

另请参阅

setFromTo() toPage() pageRanges()

fullPage()
Return type:

布尔

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

详情和注意事项请参见setFullPage()。

isValid()
Return type:

布尔

警告

本节包含从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()
Return type:

字符串

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

outputFormat()
Return type:

OutputFormat

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

另请参阅

setOutputFormat()

pageOrder()
Return type:

PageOrder

返回当前页面的顺序。

默认的页面顺序是 FirstPageFirst。

另请参阅

setPageOrder()

pageRect(unit)
Parameters:

单位 – Unit

Return type:

QRectF

返回页面的矩形，单位为unit；这通常比paperRect()小，因为页面通常在边框和纸张之间有边距。

另请参阅

pageLayout()

paperRect(unit)
Parameters:

单位 – Unit

Return type:

QRectF

返回纸张的矩形，单位为unit；这通常比pageRect()大。

另请参阅

pageRect()

paperSource()
Return type:

PaperSource

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

另请参阅

setPaperSource()

pdfVersion()
Return type:

PdfVersion

返回此打印机的PDF版本。默认是PdfVersion_1_4。

另请参阅

setPdfVersion()

printEngine()
Return type:

QPrintEngine

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

printProgram()
Return type:

字符串

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

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

另请参阅

setPrintProgram() setPrinterSelectionOption()

printRange()
Return type:

PrintRange

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

另请参阅

setPrintRange()

printerName()
Return type:

字符串

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

另请参阅

setPrinterName()

printerState()
Return type:

PrinterState

返回打印机的当前状态。这可能并不总是准确的（例如，如果打印机没有能力向操作系统报告其状态）。

resolution()
Return type:

整数

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

另请参阅

setResolution()

setCollateCopies(collate)
Parameters:

collate – 布尔值

设置打印对话框出现时整理复选框的默认值。如果collate为true，它将启用setCollateCopiesEnabled()。默认值为false。此值将根据用户在打印对话框中按下的内容进行更改。

另请参阅

collateCopies()

setColorMode(newColorMode)
Parameters:

newColorMode – ColorMode

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

另请参阅

colorMode()

setCopyCount(count)
Parameters:

count – int

设置要打印的份数为count。

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

setCreator(creator)
Parameters:

创建者 – str

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

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

另请参阅

creator()

setDocName(name)
Parameters:

name – str

将文档名称设置为 name。

在X11上，文档名称例如用作QPrintDialog中的默认输出文件名。请注意，如果打印机正在打印到文件，文档名称不会影响文件名。请使用setOutputFile()函数来实现这一点。

setDuplex(duplex)
Parameters:

双工 – DuplexMode

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

另请参阅

duplex()

setEngines(printEngine, paintEngine)
Parameters:

此函数由QPrinter的子类使用，用于指定自定义的打印和绘制引擎（分别为printEngine和paintEngine）。

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

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

另请参阅

printEngine() paintEngine() setOutputFormat()

setFontEmbeddingEnabled(enable)
Parameters:

enable – 布尔值

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

另请参阅

fontEmbeddingEnabled()

setFromTo(fromPage, toPage)
Parameters:

  • fromPage – int

  • toPage – int

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

注意

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

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

setFullPage(fp)
Parameters:

fp – 布尔值

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

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

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

另请参阅

fullPage() setPageSize()

setOutputFileName(fileName)
Parameters:

fileName – str

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

设置一个空或空白的名称（0或“”）将禁用打印到文件。设置一个非空名称将启用打印到文件。

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

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

setOutputFormat(format)
Parameters:

format – OutputFormat

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

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

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

setPageOrder(pageOrder)
Parameters:

pageOrder – PageOrder

将页面顺序设置为 pageOrder。

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

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

此功能仅在X11下支持。

另请参阅

pageOrder()

setPaperSource(source)
Parameters:

来源 – PaperSource

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

仅限Windows：此选项可以在打印时更改，并从下一次调用newPage()开始生效

另请参阅

paperSource()

setPdfVersion(version)
Parameters:

版本 – PdfVersion

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

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

另请参阅

pdfVersion()

setPrintProgram(printProg)
Parameters:

printProg – 字符串

设置应该执行打印任务的程序名称为 printProg。

在X11上，此函数设置用于处理PDF输出的程序。在其他平台上，此函数无效。

另请参阅

printProgram()

setPrintRange(range)
Parameters:

范围 – PrintRange

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

另请参阅

printRange()

setPrinterName(name)
Parameters:

name – str

将打印机名称设置为 name。

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

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

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

setResolution(dpi)
Parameters:

dpi – int

请求打印机以dpi或尽可能接近dpi的精度打印。

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

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

supportedResolutions()
Return type:

整数列表

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

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

supportsMultipleCopies()
Return type:

布尔

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

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

toPage()
Return type:

整数

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

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

注意

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

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