QPrinter Class
The QPrinter class is a paint device that paints on a printer. More...
| Header: | #include <QPrinter> |
| qmake: | QT += printsupport |
| Inherits: | QPagedPaintDevice |
Note: All functions in this class are reentrant.
Public Types
| enum | ColorMode { Color, GrayScale } |
| enum | DuplexMode { DuplexNone, DuplexAuto, DuplexLongSide, DuplexShortSide } |
| enum | Orientation { Portrait, Landscape } |
| enum | OutputFormat { NativeFormat, PdfFormat } |
| enum | PageOrder { FirstPageFirst, LastPageFirst } |
| typedef | PaperSize |
| enum | PaperSource { Auto, Cassette, Envelope, EnvelopeManual, FormSource, …, LastPaperSource } |
| enum | PrintRange { AllPages, Selection, PageRange, CurrentPage } |
| enum | PrinterMode { ScreenResolution, PrinterResolution, HighResolution } |
| enum | PrinterState { Idle, Active, Aborted, Error } |
| enum | Unit { Millimeter, Point, Inch, Pica, Didot, …, DevicePixel } |
Detailed Description
This device represents a series of pages of printed output, and is used in almost exactly the same way as other paint devices such as QWidget and QPixmap. A set of additional functions are provided to manage device-specific features, such as orientation and resolution, and to step through the pages in a document as it is generated.
When printing directly to a printer on Windows or macOS, QPrinter uses the built-in printer drivers. On X11, QPrinter uses the Common Unix Printing System (CUPS) to send PDF output to the printer. As an alternative, the printProgram() function can be used to specify the command or utility to use instead of the system default.
Note that setting parameters like paper size and resolution on an invalid printer is undefined. You can use QPrinter::isValid() to verify this before changing any parameters.
QPrinter supports a number of parameters, most of which can be changed by the end user through a print dialog. In general, QPrinter passes these functions onto the underlying QPrintEngine.
The most important parameters are:
- setOrientation() tells QPrinter which page orientation to use.
- setPaperSize() tells QPrinter what paper size to expect from the printer.
- setResolution() tells QPrinter what resolution you wish the printer to provide, in dots per inch (DPI).
- setFullPage() tells QPrinter whether you want to deal with the full page or just with the part the printer can draw on.
- setCopyCount() tells QPrinter how many copies of the document it should print.
Many of these functions can only be called before the actual printing begins (i.e., before QPainter::begin() is called). This usually makes sense because, for example, it's not possible to change the number of copies when you are halfway through printing. There are also some settings that the user sets (through the printer dialog) and that applications are expected to obey. See QAbstractPrintDialog's documentation for more details.
When QPainter::begin() is called, the QPrinter it operates on is prepared for a new page, enabling the QPainter to be used immediately to paint the first page in a document. Once the first page has been painted, newPage() can be called to request a new blank page to paint on, or QPainter::end() can be called to finish printing. The second page and all following pages are prepared using a call to newPage() before they are painted.
The first page in a document does not need to be preceded by a call to newPage(). You only need to calling newPage() after QPainter::begin() if you need to insert a blank page at the beginning of a printed document. Similarly, calling newPage() after the last page in a document is painted will result in a trailing blank page appended to the end of the printed document.
If you want to abort the print job, abort() will try its best to stop printing. It may cancel the entire job or just part of it.
Since QPrinter can print to any QPrintEngine subclass, it is possible to extend printing support to cover new types of printing subsystem by subclassing QPrintEngine and reimplementing its interface.
See also QPrintDialog and Qt Print Support.
Member Type Documentation
enum QPrinter::ColorMode
This enum type is used to indicate whether QPrinter should print in color or not.
| Constant | Value | Description |
|---|---|---|
QPrinter::Color | 1 | print in color if available, otherwise in grayscale. |
QPrinter::GrayScale | 0 | print in grayscale, even on color printers. |
enum QPrinter::DuplexMode
This enum is used to indicate whether printing will occur on one or both sides of each sheet of paper (simplex or duplex printing).
| Constant | Value | Description |
|---|---|---|
QPrinter::DuplexNone | 0 | Single sided (simplex) printing only. |
QPrinter::DuplexAuto | 1 | The printer's default setting is used to determine whether duplex printing is used. |
QPrinter::DuplexLongSide | 2 | Both sides of each sheet of paper are used for printing. The paper is turned over its longest edge before the second side is printed |
QPrinter::DuplexShortSide | 3 | Both sides of each sheet of paper are used for printing. The paper is turned over its shortest edge before the second side is printed |
This enum was introduced or modified in Qt 4.4.
enum QPrinter::Orientation
This enum type (not to be confused with Orientation) is used to specify each page's orientation.
| Constant | Value | Description |
|---|---|---|
QPrinter::Portrait | 0 | the page's height is greater than its width. |
QPrinter::Landscape | 1 | the page's width is greater than its height. |
This type interacts with QPrinter::PaperSize and QPrinter::setFullPage() to determine the final size of the page available to the application.
enum QPrinter::OutputFormat
The OutputFormat enum is used to describe the format QPrinter should use for printing.
| Constant | Value | Description |
|---|---|---|
QPrinter::NativeFormat | 0 | QPrinter will print output using a method defined by the platform it is running on. This mode is the default when printing directly to a printer. |
QPrinter::PdfFormat | 1 | QPrinter will generate its output as a searchable PDF file. This mode is the default when printing to a file. |
See also outputFormat(), setOutputFormat(), and setOutputFileName().
enum QPrinter::PageOrder
This enum type is used by QPrinter to tell the application program how to print.
| Constant | Value | Description |
|---|---|---|
QPrinter::FirstPageFirst | 0 | the lowest-numbered page should be printed first. |
QPrinter::LastPageFirst | 1 | the highest-numbered page should be printed first. |
typedef QPrinter::PaperSize
typdef for the enum QPagedPaintDevice::PageSize.
This enum type specifies what paper size QPrinter should use. QPrinter does not check that the paper size is available; it just uses this information, together with QPrinter::Orientation and QPrinter::setFullPage(), to determine the printable area.
The defined sizes (with setFullPage(true)) are found in QPagedPaintDevice.
With setFullPage(false) (the default), the metrics will be a bit smaller; how much depends on the printer in use.
Due to historic reasons QPageSize::Executive is not the same as the standard Postscript and Windows Executive size, use QPageSize::ExecutiveStandard instead.
The Postscript standard size QPageSize::Folio is different to the Windows DMPAPER_FOLIO size, use the Postscript standard size QPageSize::FanFoldGermanLegal if needed.
This typedef was introduced in Qt 4.4.
enum QPrinter::PaperSource
This enum type specifies what paper source QPrinter is to use. QPrinter does not check that the paper source is available; it just uses this information to try and set the paper source. Whether it will set the paper source depends on whether the printer has that particular source.
Warning: This is currently only implemented for Windows.
| Constant | Value | Description |
|---|---|---|
QPrinter::Auto | 6 | |
QPrinter::Cassette | 11 | |
QPrinter::Envelope | 4 | |
QPrinter::EnvelopeManual | 5 | |
QPrinter::FormSource | 12 | |
QPrinter::LargeCapacity | 10 | |
QPrinter::LargeFormat | 9 | |
QPrinter::Lower | 1 | |
QPrinter::MaxPageSource | 13 | Deprecated, use LastPaperSource instead |
QPrinter::Middle | 2 | |
QPrinter::Manual | 3 | |
QPrinter::OnlyOne | 0 | |
QPrinter::Tractor | 7 | |
QPrinter::SmallFormat | 8 | |
QPrinter::Upper | OnlyOne | |
QPrinter::CustomSource | 14 | A PaperSource defined by the printer that is unknown to Qt |
QPrinter::LastPaperSource | CustomSource | The highest valid PaperSource value, currently CustomSource |
enum QPrinter::PrintRange
Used to specify the print range selection option.
| Constant | Value | Description |
|---|---|---|
QPrinter::AllPages | 0 | All pages should be printed. |
QPrinter::Selection | 1 | Only the selection should be printed. |
QPrinter::PageRange | 2 | The specified page range should be printed. |
QPrinter::CurrentPage | 3 | Only the current page should be printed. |
See also setPrintRange(), printRange(), and QAbstractPrintDialog::PrintRange.
enum QPrinter::PrinterMode
This enum describes the mode the printer should work in. It basically presets a certain resolution and working mode.
| Constant | Value | Description |
|---|---|---|
QPrinter::ScreenResolution | 0 | Sets the resolution of the print device to the screen resolution. This has the big advantage that the results obtained when painting on the printer will match more or less exactly the visible output on the screen. It is the easiest to use, as font metrics on the screen and on the printer are the same. This is the default value. ScreenResolution will produce a lower quality output than HighResolution and should only be used for drafts. |
QPrinter::PrinterResolution | 1 | This value is deprecated. It is equivalent to ScreenResolution on Unix and HighResolution on Windows and Mac. Due to the difference between ScreenResolution and HighResolution, use of this value may lead to non-portable printer code. |
QPrinter::HighResolution | 2 | On Windows, sets the printer resolution to that defined for the printer in use. For PDF printing, sets the resolution of the PDF driver to 1200 dpi. |
Note: When rendering text on a QPrinter device, it is important to realize that the size of text, when specified in points, is independent of the resolution specified for the device itself. Therefore, it may be useful to specify the font size in pixels when combining text with graphics to ensure that their relative sizes are what you expect.
enum QPrinter::PrinterState
| Constant | Value |
|---|---|
QPrinter::Idle | 0 |
QPrinter::Active | 1 |
QPrinter::Aborted | 2 |
QPrinter::Error | 3 |
enum QPrinter::Unit
This enum type is used to specify the measurement unit for page and paper sizes.
| Constant | Value |
|---|---|
QPrinter::Millimeter | 0 |
QPrinter::Point | 1 |
QPrinter::Inch | 2 |
QPrinter::Pica | 3 |
QPrinter::Didot | 4 |
QPrinter::Cicero | 5 |
QPrinter::DevicePixel | 6 |
Note the difference between Point and DevicePixel. The Point unit is defined to be 1/72th of an inch, while the DevicePixel unit is resolution dependant and is based on the actual pixels, or dots, on the printer.
This enum was introduced or modified in Qt 4.4.