QPrinter Class Reference
[QtGui module]

Detailed Description

The QPrinter class is a paint device that paints on a printer.

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 Mac OS X, QPrinter uses the built-in printer drivers. On X11, QPrinter uses the Common Unix Printing System (CUPS) or the standard Unix lpr utility to send PostScript or 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.
• setNumCopies() 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 Printing with Qt.

Member Type Documentation

     QPrinter printer;
     printer.setOutputFormat(QPrinter::PdfFormat);
     printer.setOutputFileName("/foobar/nonwritable.pdf");
     QPainter painter;
     if (! painter.begin(&printer)) { // failed to open file
         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();