1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtGui module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qprinter_p.h"
44 #include "qprintengine.h"
45 #include "qprinterinfo.h"
47 #include <qpagesetupdialog.h>
48 #include <qapplication.h>
49 #include <qfileinfo.h>
50 #if !defined(QT_NO_CUPS) && !defined(QT_NO_LIBRARY)
51 #include "private/qcups_p.h"
56 #if defined (Q_WS_WIN)
57 #include <private/qprintengine_win_p.h>
58 #elif defined (Q_WS_MAC)
59 #include <private/qprintengine_mac_p.h>
60 #elif defined (QTOPIA_PRINTENGINE)
61 #include <private/qprintengine_qws_p.h>
63 #include <private/qprintengine_ps_p.h>
66 #include <private/qt_x11_p.h>
70 #include "qprintengine_pdf_p.h"
74 #include <private/qpaintengine_preview_p.h>
76 #if defined(QT3_SUPPORT)
77 # include "qprintdialog.h"
82 #define ABORT_IF_ACTIVE(location) \
83 if (d->printEngine->printerState() == QPrinter::Active) { \
84 qWarning("%s: Cannot be changed while printer is active", location); \
88 // NB! This table needs to be in sync with QPrinter::PaperSize
89 static const float qt_paperSizes[][2] = {
92 {215.9f, 279.4f}, // Letter
93 {215.9f, 355.6f}, // Legal
94 {190.5f, 254}, // Executive
115 {105, 241}, // US Common
118 {431.8f, 279.4f}, // Ledger
119 {279.4f, 431.8f} // Tabloid
122 /// return the multiplier of converting from the unit value to postscript-points.
123 double qt_multiplierForUnit(QPrinter::Unit unit, int resolution)
126 case QPrinter::Millimeter:
127 return 2.83464566929;
128 case QPrinter::Point:
134 case QPrinter::Didot:
136 case QPrinter::Cicero:
138 case QPrinter::DevicePixel:
139 return 72.0/resolution;
144 // not static: it's needed in qpagesetupdialog_unix.cpp
145 QSizeF qt_printerPaperSize(QPrinter::Orientation orientation,
146 QPrinter::PaperSize paperSize,
151 int height_index = 1;
152 if (orientation == QPrinter::Landscape) {
156 const qreal multiplier = qt_multiplierForUnit(unit, resolution);
157 return QSizeF((qt_paperSizes[paperSize][width_index] * 72 / 25.4) / multiplier,
158 (qt_paperSizes[paperSize][height_index] * 72 / 25.4) / multiplier);
161 void QPrinterPrivate::createDefaultEngines()
163 QPrinter::OutputFormat realOutputFormat = outputFormat;
164 #if !defined (QTOPIA_PRINTENGINE)
165 #if defined (Q_OS_UNIX) && ! defined (Q_WS_MAC)
166 if(outputFormat == QPrinter::NativeFormat) {
167 realOutputFormat = QPrinter::PostScriptFormat;
172 switch (realOutputFormat) {
173 case QPrinter::NativeFormat: {
174 #if defined (Q_WS_WIN)
175 QWin32PrintEngine *winEngine = new QWin32PrintEngine(printerMode);
176 paintEngine = winEngine;
177 printEngine = winEngine;
178 #elif defined (Q_WS_MAC)
179 QMacPrintEngine *macEngine = new QMacPrintEngine(printerMode);
180 paintEngine = macEngine;
181 printEngine = macEngine;
182 #elif defined (QTOPIA_PRINTENGINE)
183 QtopiaPrintEngine *qwsEngine = new QtopiaPrintEngine(printerMode);
184 paintEngine = qwsEngine;
185 printEngine = qwsEngine;
186 #elif defined (Q_OS_UNIX)
191 case QPrinter::PdfFormat: {
192 QPdfEngine *pdfEngine = new QPdfEngine(printerMode);
193 paintEngine = pdfEngine;
194 printEngine = pdfEngine;
197 case QPrinter::PostScriptFormat: {
198 QPSPrintEngine *psEngine = new QPSPrintEngine(printerMode);
199 paintEngine = psEngine;
200 printEngine = psEngine;
204 use_default_engine = true;
205 had_default_engines = true;
208 #ifndef QT_NO_PRINTPREVIEWWIDGET
209 QList<const QPicture *> QPrinterPrivate::previewPages() const
212 return previewEngine->pages();
213 return QList<const QPicture *>();
216 void QPrinterPrivate::setPreviewMode(bool enable)
221 previewEngine = new QPreviewPaintEngine;
222 had_default_engines = use_default_engine;
223 use_default_engine = false;
224 realPrintEngine = printEngine;
225 realPaintEngine = paintEngine;
226 q->setEngines(previewEngine, previewEngine);
227 previewEngine->setProxyEngines(realPrintEngine, realPaintEngine);
229 q->setEngines(realPrintEngine, realPaintEngine);
230 use_default_engine = had_default_engines;
233 #endif // QT_NO_PRINTPREVIEWWIDGET
235 void QPrinterPrivate::addToManualSetList(QPrintEngine::PrintEnginePropertyKey key)
237 for (int c = 0; c < manualSetList.size(); ++c) {
238 if (manualSetList[c] == key) return;
240 manualSetList.append(key);
248 \brief The QPrinter class is a paint device that paints on a printer.
253 This device represents a series of pages of printed output, and is
254 used in almost exactly the same way as other paint devices such as
256 A set of additional functions are provided to manage device-specific
257 features, such as orientation and resolution, and to step through
258 the pages in a document as it is generated.
260 When printing directly to a printer on Windows or Mac OS X, QPrinter uses
261 the built-in printer drivers. On X11, QPrinter uses the
262 \l{Common Unix Printing System (CUPS)} or the standard Unix \l lpr utility
263 to send PostScript or PDF output to the printer. As an alternative,
264 the printProgram() function can be used to specify the command or utility
265 to use instead of the system default.
267 Note that setting parameters like paper size and resolution on an
268 invalid printer is undefined. You can use QPrinter::isValid() to
269 verify this before changing any parameters.
271 QPrinter supports a number of parameters, most of which can be
272 changed by the end user through a \l{QPrintDialog}{print dialog}. In
273 general, QPrinter passes these functions onto the underlying QPrintEngine.
275 The most important parameters are:
277 \i setOrientation() tells QPrinter which page orientation to use.
278 \i setPaperSize() tells QPrinter what paper size to expect from the
280 \i setResolution() tells QPrinter what resolution you wish the
281 printer to provide, in dots per inch (DPI).
282 \i setFullPage() tells QPrinter whether you want to deal with the
283 full page or just with the part the printer can draw on.
284 \i setCopyCount() tells QPrinter how many copies of the document
288 Many of these functions can only be called before the actual printing
289 begins (i.e., before QPainter::begin() is called). This usually makes
290 sense because, for example, it's not possible to change the number of
291 copies when you are halfway through printing. There are also some
292 settings that the user sets (through the printer dialog) and that
293 applications are expected to obey. See QAbstractPrintDialog's
294 documentation for more details.
296 When QPainter::begin() is called, the QPrinter it operates on is prepared for
297 a new page, enabling the QPainter to be used immediately to paint the first
298 page in a document. Once the first page has been painted, newPage() can be
299 called to request a new blank page to paint on, or QPainter::end() can be
300 called to finish printing. The second page and all following pages are
301 prepared using a call to newPage() before they are painted.
303 The first page in a document does not need to be preceded by a call to
304 newPage(). You only need to calling newPage() after QPainter::begin() if you
305 need to insert a blank page at the beginning of a printed document.
306 Similarly, calling newPage() after the last page in a document is painted will
307 result in a trailing blank page appended to the end of the printed document.
309 If you want to abort the print job, abort() will try its best to
310 stop printing. It may cancel the entire job or just part of it.
312 Since QPrinter can print to any QPrintEngine subclass, it is possible to
313 extend printing support to cover new types of printing subsystem by
314 subclassing QPrintEngine and reimplementing its interface.
316 \sa QPrintDialog, {Printing with Qt}
320 \enum QPrinter::PrinterState
329 \enum QPrinter::PrinterMode
331 This enum describes the mode the printer should work in. It
332 basically presets a certain resolution and working mode.
334 \value ScreenResolution Sets the resolution of the print device to
335 the screen resolution. This has the big advantage that the results
336 obtained when painting on the printer will match more or less
337 exactly the visible output on the screen. It is the easiest to
338 use, as font metrics on the screen and on the printer are the
339 same. This is the default value. ScreenResolution will produce a
340 lower quality output than HighResolution and should only be used
343 \value PrinterResolution This value is deprecated. Is is
344 equivalent to ScreenResolution on Unix and HighResolution on
345 Windows and Mac. Due do the difference between ScreenResolution
346 and HighResolution, use of this value may lead to non-portable
349 \value HighResolution On Windows, sets the printer resolution to that
350 defined for the printer in use. For PostScript printing, sets the
351 resolution of the PostScript driver to 1200 dpi.
353 \note When rendering text on a QPrinter device, it is important
354 to realize that the size of text, when specified in points, is
355 independent of the resolution specified for the device itself.
356 Therefore, it may be useful to specify the font size in pixels
357 when combining text with graphics to ensure that their relative
358 sizes are what you expect.
362 \enum QPrinter::Orientation
364 This enum type (not to be confused with \c Orientation) is used
365 to specify each page's orientation.
367 \value Portrait the page's height is greater than its width.
369 \value Landscape the page's width is greater than its height.
371 This type interacts with \l QPrinter::PaperSize and
372 QPrinter::setFullPage() to determine the final size of the page
373 available to the application.
378 \enum QPrinter::PrintRange
380 Used to specify the print range selection option.
382 \value AllPages All pages should be printed.
383 \value Selection Only the selection should be printed.
384 \value PageRange The specified page range should be printed.
385 \value CurrentPage Only the current page should be printed.
387 \sa QAbstractPrintDialog::PrintRange
391 \enum QPrinter::PrinterOption
394 Use QAbstractPrintDialog::PrintDialogOption instead.
397 \value PrintSelection
398 \value PrintPageRange
402 \enum QPrinter::PageSize
405 Use QPrinter::PaperSize instead.
407 \value A0 841 x 1189 mm
408 \value A1 594 x 841 mm
409 \value A2 420 x 594 mm
410 \value A3 297 x 420 mm
411 \value A4 210 x 297 mm, 8.26 x 11.69 inches
412 \value A5 148 x 210 mm
413 \value A6 105 x 148 mm
414 \value A7 74 x 105 mm
417 \value B0 1030 x 1456 mm
418 \value B1 728 x 1030 mm
419 \value B10 32 x 45 mm
420 \value B2 515 x 728 mm
421 \value B3 364 x 515 mm
422 \value B4 257 x 364 mm
423 \value B5 182 x 257 mm, 7.17 x 10.13 inches
424 \value B6 128 x 182 mm
425 \value B7 91 x 128 mm
428 \value C5E 163 x 229 mm
429 \value Comm10E 105 x 241 mm, U.S. Common 10 Envelope
430 \value DLE 110 x 220 mm
431 \value Executive 7.5 x 10 inches, 191 x 254 mm
432 \value Folio 210 x 330 mm
433 \value Ledger 432 x 279 mm
434 \value Legal 8.5 x 14 inches, 216 x 356 mm
435 \value Letter 8.5 x 11 inches, 216 x 279 mm
436 \value Tabloid 279 x 432 mm
437 \value Custom Unknown, or a user defined size.
443 \enum QPrinter::PaperSize
446 This enum type specifies what paper size QPrinter should use.
447 QPrinter does not check that the paper size is available; it just
448 uses this information, together with QPrinter::Orientation and
449 QPrinter::setFullPage(), to determine the printable area.
451 The defined sizes (with setFullPage(true)) are:
453 \value A0 841 x 1189 mm
454 \value A1 594 x 841 mm
455 \value A2 420 x 594 mm
456 \value A3 297 x 420 mm
457 \value A4 210 x 297 mm, 8.26 x 11.69 inches
458 \value A5 148 x 210 mm
459 \value A6 105 x 148 mm
460 \value A7 74 x 105 mm
463 \value B0 1000 x 1414 mm
464 \value B1 707 x 1000 mm
465 \value B2 500 x 707 mm
466 \value B3 353 x 500 mm
467 \value B4 250 x 353 mm
468 \value B5 176 x 250 mm, 6.93 x 9.84 inches
469 \value B6 125 x 176 mm
470 \value B7 88 x 125 mm
473 \value B10 31 x 44 mm
474 \value C5E 163 x 229 mm
475 \value Comm10E 105 x 241 mm, U.S. Common 10 Envelope
476 \value DLE 110 x 220 mm
477 \value Executive 7.5 x 10 inches, 190.5 x 254 mm
478 \value Folio 210 x 330 mm
479 \value Ledger 431.8 x 279.4 mm
480 \value Legal 8.5 x 14 inches, 215.9 x 355.6 mm
481 \value Letter 8.5 x 11 inches, 215.9 x 279.4 mm
482 \value Tabloid 279.4 x 431.8 mm
483 \value Custom Unknown, or a user defined size.
485 With setFullPage(false) (the default), the metrics will be a bit
486 smaller; how much depends on the printer in use.
489 \omitvalue NPaperSize
494 \enum QPrinter::PageOrder
496 This enum type is used by QPrinter to tell the application program
499 \value FirstPageFirst the lowest-numbered page should be printed
502 \value LastPageFirst the highest-numbered page should be printed
507 \enum QPrinter::ColorMode
509 This enum type is used to indicate whether QPrinter should print
512 \value Color print in color if available, otherwise in grayscale.
514 \value GrayScale print in grayscale, even on color printers.
518 \enum QPrinter::PaperSource
520 This enum type specifies what paper source QPrinter is to use.
521 QPrinter does not check that the paper source is available; it
522 just uses this information to try and set the paper source.
523 Whether it will set the paper source depends on whether the
524 printer has that particular source.
526 \warning This is currently only implemented for Windows.
531 \value EnvelopeManual
548 This enum type is used to specify the measurement unit for page and
559 Note the difference between Point and DevicePixel. The Point unit is
560 defined to be 1/72th of an inch, while the DevicePixel unit is
561 resolution dependant and is based on the actual pixels, or dots, on
567 \enum QPrinter::PrintRange
569 This enum is used to specify which print range the application
572 \value AllPages All the pages should be printed.
573 \value Selection Only the selection should be printed.
574 \value PageRange Print according to the from page and to page options.
575 \value CurrentPage Only the current page should be printed.
577 \sa setPrintRange(), printRange()
581 \enum QPrinter::PrinterOption
583 This enum describes various printer options that appear in the
584 printer setup dialog. It is used to enable and disable these
585 options in the setup dialog.
587 \value PrintToFile Describes if print to file should be enabled.
588 \value PrintSelection Describes if printing selections should be enabled.
589 \value PrintPageRange Describes if printing page ranges (from, to) should
591 \value PrintCurrentPage if Print Current Page option should be enabled
593 \sa setOptionEnabled(), isOptionEnabled()
597 Creates a new printer object with the given \a mode.
599 QPrinter::QPrinter(PrinterMode mode)
601 d_ptr(new QPrinterPrivate(this))
604 QPrinterInfo defPrn(QPrinterInfo::defaultPrinter());
605 if (!defPrn.isNull()) {
606 setPrinterName(defPrn.printerName());
607 } else if (QPrinterInfo::availablePrinters().isEmpty()
608 && d_ptr->paintEngine->type() != QPaintEngine::Windows
609 && d_ptr->paintEngine->type() != QPaintEngine::MacPrinter) {
610 setOutputFormat(QPrinter::PdfFormat);
617 Creates a new printer object with the given \a printer and \a mode.
619 QPrinter::QPrinter(const QPrinterInfo& printer, PrinterMode mode)
621 d_ptr(new QPrinterPrivate(this))
624 setPrinterName(printer.printerName());
627 void QPrinter::init(PrinterMode mode)
629 #if !defined(Q_WS_X11)
634 qFatal("QPrinter: Must construct a QApplication before a QPaintDevice");
639 d->printerMode = mode;
640 d->outputFormat = QPrinter::NativeFormat;
641 d->createDefaultEngines();
643 #ifndef QT_NO_PRINTPREVIEWWIDGET
644 d->previewEngine = 0;
646 d->realPrintEngine = 0;
647 d->realPaintEngine = 0;
649 #if !defined(QT_NO_CUPS) && !defined(QT_NO_LIBRARY)
650 if (QCUPSSupport::cupsVersion() >= 10200 && QCUPSSupport().currentPPD()) {
651 setOutputFormat(QPrinter::PdfFormat);
652 d->outputFormat = QPrinter::NativeFormat;
658 This function is used by subclasses of QPrinter to specify custom
659 print and paint engines (\a printEngine and \a paintEngine,
662 QPrinter does not take ownership of the engines, so you need to
663 manage these engine instances yourself.
665 Note that changing the engines will reset the printer state and
668 \sa printEngine() paintEngine() setOutputFormat()
672 void QPrinter::setEngines(QPrintEngine *printEngine, QPaintEngine *paintEngine)
676 if (d->use_default_engine)
677 delete d->printEngine;
679 d->printEngine = printEngine;
680 d->paintEngine = paintEngine;
681 d->use_default_engine = false;
685 Destroys the printer object and frees any allocated resources. If
686 the printer is destroyed while a print job is in progress this may
687 or may not affect the print job.
689 QPrinter::~QPrinter()
692 if (d->use_default_engine)
693 delete d->printEngine;
694 #ifndef QT_NO_PRINTPREVIEWWIDGET
695 delete d->previewEngine;
700 \enum QPrinter::OutputFormat
702 The OutputFormat enum is used to describe the format QPrinter should
705 \value NativeFormat QPrinter will print output using a method defined
706 by the platform it is running on. This mode is the default when printing
707 directly to a printer.
709 \value PdfFormat QPrinter will generate its output as a searchable PDF file.
710 This mode is the default when printing to a file.
712 \value PostScriptFormat QPrinter will generate its output as in the PostScript format.
713 (This feature was introduced in Qt 4.2.)
715 \sa outputFormat(), setOutputFormat(), setOutputFileName()
721 Sets the output format for this printer to \a format.
723 void QPrinter::setOutputFormat(OutputFormat format)
728 if (d->validPrinter && d->outputFormat == format)
730 d->outputFormat = format;
732 QPrintEngine *oldPrintEngine = d->printEngine;
733 const bool def_engine = d->use_default_engine;
736 d->createDefaultEngines();
738 if (oldPrintEngine) {
739 for (int i = 0; i < d->manualSetList.size(); ++i) {
740 QPrintEngine::PrintEnginePropertyKey key = d->manualSetList[i];
742 // PPK_NumberOfCopies need special treatmeant since it in most cases
743 // will return 1, disregarding the actual value that was set
744 if (key == QPrintEngine::PPK_NumberOfCopies)
745 prop = QVariant(copyCount());
747 prop = oldPrintEngine->property(key);
749 d->printEngine->setProperty(key, prop);
754 delete oldPrintEngine;
756 if (d->outputFormat == QPrinter::PdfFormat || d->outputFormat == QPrinter::PostScriptFormat)
757 d->validPrinter = true;
766 Returns the output format for this printer.
768 QPrinter::OutputFormat QPrinter::outputFormat() const
771 return d->outputFormat;
778 int QPrinter::devType() const
780 return QInternal::Printer;
784 Returns the printer name. This value is initially set to the name
785 of the default printer.
789 QString QPrinter::printerName() const
792 return d->printEngine->property(QPrintEngine::PPK_PrinterName).toString();
796 Sets the printer name to \a name.
798 \sa printerName(), isValid()
800 void QPrinter::setPrinterName(const QString &name)
803 ABORT_IF_ACTIVE("QPrinter::setPrinterName");
805 #if defined(Q_OS_UNIX) && !defined(QT_NO_CUPS)
806 if(d->use_default_engine
807 && d->outputFormat == QPrinter::NativeFormat) {
808 if (QCUPSSupport::cupsVersion() >= 10200
809 && QCUPSSupport::printerHasPPD(name.toLocal8Bit().constData()))
810 setOutputFormat(QPrinter::PdfFormat);
812 setOutputFormat(QPrinter::PostScriptFormat);
813 d->outputFormat = QPrinter::NativeFormat;
817 QList<QPrinterInfo> prnList = QPrinterInfo::availablePrinters();
818 if (name.isEmpty()) {
819 d->validPrinter = d->outputFormat == QPrinter::PdfFormat || d->outputFormat == QPrinter::PostScriptFormat;
821 d->validPrinter = false;
822 for (int i = 0; i < prnList.size(); ++i) {
823 if (prnList[i].printerName() == name) {
824 d->validPrinter = true;
830 d->printEngine->setProperty(QPrintEngine::PPK_PrinterName, name);
831 d->addToManualSetList(QPrintEngine::PPK_PrinterName);
838 Returns true if the printer currently selected is a valid printer
839 in the system, or a pure PDF/PostScript printer; otherwise returns false.
841 To detect other failures check the output of QPainter::begin() or QPrinter::newPage().
843 \snippet doc/src/snippets/printing-qprinter/errors.cpp 0
847 bool QPrinter::isValid() const
850 #if defined(Q_WS_X11)
855 return d->validPrinter;
860 \fn bool QPrinter::outputToFile() const
862 Returns true if the output should be written to a file, or false
863 if the output should be sent directly to the printer. The default
866 \sa setOutputToFile(), setOutputFileName()
871 \fn void QPrinter::setOutputToFile(bool enable)
873 Specifies whether the output should be written to a file or sent
874 directly to the printer.
876 Will output to a file if \a enable is true, or will output
877 directly to the printer if \a enable is false.
879 \sa outputToFile(), setOutputFileName()
884 \fn QString QPrinter::outputFileName() const
886 Returns the name of the output file. By default, this is an empty string
887 (indicating that the printer shouldn't print to file).
889 \sa QPrintEngine::PrintEnginePropertyKey
893 QString QPrinter::outputFileName() const
896 return d->printEngine->property(QPrintEngine::PPK_OutputFileName).toString();
900 Sets the name of the output file to \a fileName.
902 Setting a null or empty name (0 or "") disables printing to a file.
903 Setting a non-empty name enables printing to a file.
905 This can change the value of outputFormat(). If the file name has the
906 suffix ".ps" then PostScript is automatically selected as output format.
907 If the file name has the ".pdf" suffix PDF is generated. If the file name
908 has a suffix other than ".ps" and ".pdf", the output format used is the
909 one set with setOutputFormat().
911 QPrinter uses Qt's cross-platform PostScript or PDF print engines
912 respectively. If you can produce this format natively, for example
913 Mac OS X can generate PDF's from its print engine, set the output format
914 back to NativeFormat.
916 \sa outputFileName() setOutputToFile() setOutputFormat()
919 void QPrinter::setOutputFileName(const QString &fileName)
922 ABORT_IF_ACTIVE("QPrinter::setOutputFileName");
924 QFileInfo fi(fileName);
925 if (!fi.suffix().compare(QLatin1String("ps"), Qt::CaseInsensitive))
926 setOutputFormat(QPrinter::PostScriptFormat);
927 else if (!fi.suffix().compare(QLatin1String("pdf"), Qt::CaseInsensitive))
928 setOutputFormat(QPrinter::PdfFormat);
929 else if (fileName.isEmpty())
930 setOutputFormat(QPrinter::NativeFormat);
932 d->printEngine->setProperty(QPrintEngine::PPK_OutputFileName, fileName);
933 d->addToManualSetList(QPrintEngine::PPK_OutputFileName);
938 Returns the name of the program that sends the print output to the
941 The default is to return an empty string; meaning that QPrinter will try to
942 be smart in a system-dependent way. On X11 only, you can set it to something
943 different to use a specific print program. On the other platforms, this
944 returns an empty string.
946 \sa setPrintProgram(), setPrinterSelectionOption()
948 QString QPrinter::printProgram() const
951 return d->printEngine->property(QPrintEngine::PPK_PrinterProgram).toString();
956 Sets the name of the program that should do the print job to \a
959 On X11, this function sets the program to call with the PostScript
960 output. On other platforms, it has no effect.
964 void QPrinter::setPrintProgram(const QString &printProg)
967 ABORT_IF_ACTIVE("QPrinter::setPrintProgram");
968 d->printEngine->setProperty(QPrintEngine::PPK_PrinterProgram, printProg);
969 d->addToManualSetList(QPrintEngine::PPK_PrinterProgram);
974 Returns the document name.
976 \sa setDocName(), QPrintEngine::PrintEnginePropertyKey
978 QString QPrinter::docName() const
981 return d->printEngine->property(QPrintEngine::PPK_DocumentName).toString();
986 Sets the document name to \a name.
988 On X11, the document name is for example used as the default
989 output filename in QPrintDialog. Note that the document name does
990 not affect the file name if the printer is printing to a file.
991 Use the setOutputFile() function for this.
993 \sa docName(), QPrintEngine::PrintEnginePropertyKey
995 void QPrinter::setDocName(const QString &name)
998 ABORT_IF_ACTIVE("QPrinter::setDocName");
999 d->printEngine->setProperty(QPrintEngine::PPK_DocumentName, name);
1000 d->addToManualSetList(QPrintEngine::PPK_DocumentName);
1005 Returns the name of the application that created the document.
1009 QString QPrinter::creator() const
1011 Q_D(const QPrinter);
1012 return d->printEngine->property(QPrintEngine::PPK_Creator).toString();
1017 Sets the name of the application that created the document to \a
1020 This function is only applicable to the X11 version of Qt. If no
1021 creator name is specified, the creator will be set to "Qt"
1022 followed by some version number.
1026 void QPrinter::setCreator(const QString &creator)
1029 ABORT_IF_ACTIVE("QPrinter::setCreator");
1030 d->printEngine->setProperty(QPrintEngine::PPK_Creator, creator);
1031 d->addToManualSetList(QPrintEngine::PPK_Creator);
1036 Returns the orientation setting. This is driver-dependent, but is usually
1039 \sa setOrientation()
1041 QPrinter::Orientation QPrinter::orientation() const
1043 Q_D(const QPrinter);
1044 return QPrinter::Orientation(d->printEngine->property(QPrintEngine::PPK_Orientation).toInt());
1049 Sets the print orientation to \a orientation.
1051 The orientation can be either QPrinter::Portrait or
1052 QPrinter::Landscape.
1054 The printer driver reads this setting and prints using the
1055 specified orientation.
1057 On Windows, this option can be changed while printing and will
1058 take effect from the next call to newPage().
1060 On Mac OS X, changing the orientation during a print job has no effect.
1065 void QPrinter::setOrientation(Orientation orientation)
1068 d->printEngine->setProperty(QPrintEngine::PPK_Orientation, orientation);
1069 d->addToManualSetList(QPrintEngine::PPK_Orientation);
1075 Returns the printer paper size. The default value is driver-dependent.
1077 \sa setPaperSize() pageRect() paperRect()
1080 QPrinter::PaperSize QPrinter::paperSize() const
1082 Q_D(const QPrinter);
1083 return QPrinter::PaperSize(d->printEngine->property(QPrintEngine::PPK_PaperSize).toInt());
1089 Sets the printer paper size to \a newPaperSize if that size is
1090 supported. The result is undefined if \a newPaperSize is not
1093 The default paper size is driver-dependent.
1095 This function is useful mostly for setting a default value that
1096 the user can override in the print dialog.
1098 \sa paperSize() PaperSize setFullPage() setResolution() pageRect() paperRect()
1100 void QPrinter::setPaperSize(PaperSize newPaperSize)
1103 if (d->paintEngine->type() != QPaintEngine::Pdf)
1104 ABORT_IF_ACTIVE("QPrinter::setPaperSize");
1105 if (newPaperSize < 0 || newPaperSize >= NPaperSize) {
1106 qWarning("QPrinter::setPaperSize: Illegal paper size %d", newPaperSize);
1109 d->printEngine->setProperty(QPrintEngine::PPK_PaperSize, newPaperSize);
1110 d->addToManualSetList(QPrintEngine::PPK_PaperSize);
1111 d->hasUserSetPageSize = true;
1117 Returns the printer page size. The default value is driver-dependent.
1119 Use paperSize() instead.
1121 QPrinter::PageSize QPrinter::pageSize() const
1130 Sets the printer page size based on \a newPageSize.
1132 Use setPaperSize() instead.
1135 void QPrinter::setPageSize(PageSize newPageSize)
1137 setPaperSize(newPageSize);
1143 Sets the paper size based on \a paperSize in \a unit.
1148 void QPrinter::setPaperSize(const QSizeF &paperSize, QPrinter::Unit unit)
1151 if (d->paintEngine->type() != QPaintEngine::Pdf)
1152 ABORT_IF_ACTIVE("QPrinter::setPaperSize");
1153 const qreal multiplier = qt_multiplierForUnit(unit, resolution());
1154 QSizeF size(paperSize.width() * multiplier, paperSize.height() * multiplier);
1155 d->printEngine->setProperty(QPrintEngine::PPK_CustomPaperSize, size);
1156 d->addToManualSetList(QPrintEngine::PPK_CustomPaperSize);
1157 d->hasUserSetPageSize = true;
1163 Returns the paper size in \a unit.
1168 QSizeF QPrinter::paperSize(Unit unit) const
1170 Q_D(const QPrinter);
1171 int res = resolution();
1172 const qreal multiplier = qt_multiplierForUnit(unit, res);
1173 PaperSize paperType = paperSize();
1174 if (paperType == Custom) {
1175 QSizeF size = d->printEngine->property(QPrintEngine::PPK_CustomPaperSize).toSizeF();
1176 return QSizeF(size.width() / multiplier, size.height() / multiplier);
1179 return qt_printerPaperSize(orientation(), paperType, unit, res);
1184 Sets the page order to \a pageOrder.
1186 The page order can be QPrinter::FirstPageFirst or
1187 QPrinter::LastPageFirst. The application is responsible for
1188 reading the page order and printing accordingly.
1190 This function is mostly useful for setting a default value that
1191 the user can override in the print dialog.
1193 This function is only supported under X11.
1196 void QPrinter::setPageOrder(PageOrder pageOrder)
1199 ABORT_IF_ACTIVE("QPrinter::setPageOrder");
1200 d->printEngine->setProperty(QPrintEngine::PPK_PageOrder, pageOrder);
1201 d->addToManualSetList(QPrintEngine::PPK_PageOrder);
1206 Returns the current page order.
1208 The default page order is \c FirstPageFirst.
1211 QPrinter::PageOrder QPrinter::pageOrder() const
1213 Q_D(const QPrinter);
1214 return QPrinter::PageOrder(d->printEngine->property(QPrintEngine::PPK_PageOrder).toInt());
1219 Sets the printer's color mode to \a newColorMode, which can be
1220 either \c Color or \c GrayScale.
1225 void QPrinter::setColorMode(ColorMode newColorMode)
1228 ABORT_IF_ACTIVE("QPrinter::setColorMode");
1229 d->printEngine->setProperty(QPrintEngine::PPK_ColorMode, newColorMode);
1230 d->addToManualSetList(QPrintEngine::PPK_ColorMode);
1235 Returns the current color mode.
1239 QPrinter::ColorMode QPrinter::colorMode() const
1241 Q_D(const QPrinter);
1242 return QPrinter::ColorMode(d->printEngine->property(QPrintEngine::PPK_ColorMode).toInt());
1248 Returns the number of copies to be printed. The default value is 1.
1250 On Windows, Mac OS X and X11 systems that support CUPS, this will always
1251 return 1 as these operating systems can internally handle the number
1254 On X11, this value will return the number of times the application is
1255 required to print in order to match the number specified in the printer setup
1256 dialog. This has been done since some printer drivers are not capable of
1257 buffering up the copies and in those cases the application must make an
1258 explicit call to the print code for each copy.
1260 Use copyCount() in conjunction with supportsMultipleCopies() instead.
1262 \sa setNumCopies(), actualNumCopies()
1265 int QPrinter::numCopies() const
1267 Q_D(const QPrinter);
1268 return d->printEngine->property(QPrintEngine::PPK_NumberOfCopies).toInt();
1276 Returns the number of copies that will be printed. The default
1279 This function always returns the actual value specified in the print
1280 dialog or using setNumCopies().
1282 Use copyCount() instead.
1284 \sa setNumCopies(), numCopies()
1286 int QPrinter::actualNumCopies() const
1295 Sets the number of copies to be printed to \a numCopies.
1297 The printer driver reads this setting and prints the specified
1300 Use setCopyCount() instead.
1305 void QPrinter::setNumCopies(int numCopies)
1308 ABORT_IF_ACTIVE("QPrinter::setNumCopies");
1309 d->printEngine->setProperty(QPrintEngine::PPK_NumberOfCopies, numCopies);
1310 d->addToManualSetList(QPrintEngine::PPK_NumberOfCopies);
1316 Sets the number of copies to be printed to \a count.
1318 The printer driver reads this setting and prints the specified number of
1321 \sa copyCount(), supportsMultipleCopies()
1324 void QPrinter::setCopyCount(int count)
1327 ABORT_IF_ACTIVE("QPrinter::setCopyCount;");
1328 d->printEngine->setProperty(QPrintEngine::PPK_CopyCount, count);
1329 d->addToManualSetList(QPrintEngine::PPK_CopyCount);
1335 Returns the number of copies that will be printed. The default value is 1.
1337 \sa setCopyCount(), supportsMultipleCopies()
1340 int QPrinter::copyCount() const
1342 Q_D(const QPrinter);
1343 return d->printEngine->property(QPrintEngine::PPK_CopyCount).toInt();
1349 Returns true if the printer supports printing multiple copies of the same
1350 document in one job; otherwise false is returned.
1352 On most systems this function will return true. However, on X11 systems
1353 that do not support CUPS, this function will return false. That means the
1354 application has to handle the number of copies by printing the same
1355 document the required number of times.
1357 \sa setCopyCount(), copyCount()
1360 bool QPrinter::supportsMultipleCopies() const
1362 Q_D(const QPrinter);
1363 return d->printEngine->property(QPrintEngine::PPK_SupportsMultipleCopies).toBool();
1369 Returns true if collation is turned on when multiple copies is selected.
1370 Returns false if it is turned off when multiple copies is selected.
1371 When collating is turned off the printing of each individual page will be repeated
1372 the numCopies() amount before the next page is started. With collating turned on
1373 all pages are printed before the next copy of those pages is started.
1375 \sa setCollateCopies()
1377 bool QPrinter::collateCopies() const
1379 Q_D(const QPrinter);
1380 return d->printEngine->property(QPrintEngine::PPK_CollateCopies).toBool();
1387 Sets the default value for collation checkbox when the print
1388 dialog appears. If \a collate is true, it will enable
1389 setCollateCopiesEnabled(). The default value is false. This value
1390 will be changed by what the user presses in the print dialog.
1394 void QPrinter::setCollateCopies(bool collate)
1397 ABORT_IF_ACTIVE("QPrinter::setCollateCopies");
1398 d->printEngine->setProperty(QPrintEngine::PPK_CollateCopies, collate);
1399 d->addToManualSetList(QPrintEngine::PPK_CollateCopies);
1405 If \a fp is true, enables support for painting over the entire page;
1406 otherwise restricts painting to the printable area reported by the
1409 By default, full page printing is disabled. In this case, the origin
1410 of the QPrinter's coordinate system coincides with the top-left
1411 corner of the printable area.
1413 If full page printing is enabled, the origin of the QPrinter's
1414 coordinate system coincides with the top-left corner of the paper
1415 itself. In this case, the
1416 \l{QPaintDevice::PaintDeviceMetric}{device metrics} will report
1417 the exact same dimensions as indicated by \l{PaperSize}. It may not
1418 be possible to print on the entire physical page because of the
1419 printer's margins, so the application must account for the margins
1422 \sa fullPage(), setPaperSize(), width(), height(), {Printing with Qt}
1425 void QPrinter::setFullPage(bool fp)
1428 d->printEngine->setProperty(QPrintEngine::PPK_FullPage, fp);
1429 d->addToManualSetList(QPrintEngine::PPK_FullPage);
1434 Returns true if the origin of the printer's coordinate system is
1435 at the corner of the page and false if it is at the edge of the
1438 See setFullPage() for details and caveats.
1440 \sa setFullPage() PaperSize
1443 bool QPrinter::fullPage() const
1445 Q_D(const QPrinter);
1446 return d->printEngine->property(QPrintEngine::PPK_FullPage).toBool();
1451 Requests that the printer prints at \a dpi or as near to \a dpi as
1454 This setting affects the coordinate system as returned by, for
1455 example QPainter::viewport().
1457 This function must be called before QPainter::begin() to have an effect on
1460 \sa resolution() setPaperSize()
1463 void QPrinter::setResolution(int dpi)
1466 ABORT_IF_ACTIVE("QPrinter::setResolution");
1467 d->printEngine->setProperty(QPrintEngine::PPK_Resolution, dpi);
1468 d->addToManualSetList(QPrintEngine::PPK_Resolution);
1473 Returns the current assumed resolution of the printer, as set by
1474 setResolution() or by the printer driver.
1479 int QPrinter::resolution() const
1481 Q_D(const QPrinter);
1482 return d->printEngine->property(QPrintEngine::PPK_Resolution).toInt();
1486 Sets the paper source setting to \a source.
1488 Windows only: This option can be changed while printing and will
1489 take effect from the next call to newPage()
1494 void QPrinter::setPaperSource(PaperSource source)
1497 d->printEngine->setProperty(QPrintEngine::PPK_PaperSource, source);
1498 d->addToManualSetList(QPrintEngine::PPK_PaperSource);
1502 Returns the printer's paper source. This is \c Manual or a printer
1503 tray or paper cassette.
1505 QPrinter::PaperSource QPrinter::paperSource() const
1507 Q_D(const QPrinter);
1508 return QPrinter::PaperSource(d->printEngine->property(QPrintEngine::PPK_PaperSource).toInt());
1515 Enabled or disables font embedding depending on \a enable.
1517 Currently this option is only supported on X11.
1519 \sa fontEmbeddingEnabled()
1521 void QPrinter::setFontEmbeddingEnabled(bool enable)
1524 d->printEngine->setProperty(QPrintEngine::PPK_FontEmbedding, enable);
1525 d->addToManualSetList(QPrintEngine::PPK_FontEmbedding);
1531 Returns true if font embedding is enabled.
1533 Currently this option is only supported on X11.
1535 \sa setFontEmbeddingEnabled()
1537 bool QPrinter::fontEmbeddingEnabled() const
1539 Q_D(const QPrinter);
1540 return d->printEngine->property(QPrintEngine::PPK_FontEmbedding).toBool();
1544 \enum QPrinter::DuplexMode
1547 This enum is used to indicate whether printing will occur on one or both sides
1548 of each sheet of paper (simplex or duplex printing).
1550 \value DuplexNone Single sided (simplex) printing only.
1551 \value DuplexAuto The printer's default setting is used to determine whether
1552 duplex printing is used.
1553 \value DuplexLongSide Both sides of each sheet of paper are used for printing.
1554 The paper is turned over its longest edge before the second
1556 \value DuplexShortSide Both sides of each sheet of paper are used for printing.
1557 The paper is turned over its shortest edge before the second
1564 Enables double sided printing if \a doubleSided is true; otherwise disables it.
1566 Currently this option is only supported on X11.
1568 void QPrinter::setDoubleSidedPrinting(bool doubleSided)
1570 setDuplex(doubleSided ? DuplexAuto : DuplexNone);
1577 Returns true if double side printing is enabled.
1579 Currently this option is only supported on X11.
1581 bool QPrinter::doubleSidedPrinting() const
1583 return duplex() != DuplexNone;
1589 Enables double sided printing based on the \a duplex mode.
1591 Currently this option is only supported on X11.
1593 void QPrinter::setDuplex(DuplexMode duplex)
1596 d->printEngine->setProperty(QPrintEngine::PPK_Duplex, duplex);
1597 d->addToManualSetList(QPrintEngine::PPK_Duplex);
1603 Returns the current duplex mode.
1605 Currently this option is only supported on X11.
1607 QPrinter::DuplexMode QPrinter::duplex() const
1609 Q_D(const QPrinter);
1610 return static_cast <DuplexMode> (d->printEngine->property(QPrintEngine::PPK_Duplex).toInt());
1616 Returns the page's rectangle in \a unit; this is usually smaller
1617 than the paperRect() since the page normally has margins between
1618 its borders and the paper.
1622 QRectF QPrinter::pageRect(Unit unit) const
1624 Q_D(const QPrinter);
1625 int res = resolution();
1626 const qreal multiplier = qt_multiplierForUnit(unit, res);
1627 // the page rect is in device pixels
1628 QRect devRect(d->printEngine->property(QPrintEngine::PPK_PageRect).toRect());
1629 if (unit == DevicePixel)
1631 QRectF diRect(devRect.x()*72.0/res,
1632 devRect.y()*72.0/res,
1633 devRect.width()*72.0/res,
1634 devRect.height()*72.0/res);
1635 return QRectF(diRect.x()/multiplier, diRect.y()/multiplier,
1636 diRect.width()/multiplier, diRect.height()/multiplier);
1643 Returns the paper's rectangle in \a unit; this is usually larger
1644 than the pageRect().
1648 QRectF QPrinter::paperRect(Unit unit) const
1650 Q_D(const QPrinter);
1651 int res = resolution();
1652 const qreal multiplier = qt_multiplierForUnit(unit, resolution());
1653 // the page rect is in device pixels
1654 QRect devRect(d->printEngine->property(QPrintEngine::PPK_PaperRect).toRect());
1655 if (unit == DevicePixel)
1657 QRectF diRect(devRect.x()*72.0/res,
1658 devRect.y()*72.0/res,
1659 devRect.width()*72.0/res,
1660 devRect.height()*72.0/res);
1661 return QRectF(diRect.x()/multiplier, diRect.y()/multiplier,
1662 diRect.width()/multiplier, diRect.height()/multiplier);
1666 Returns the page's rectangle; this is usually smaller than the
1667 paperRect() since the page normally has margins between its
1668 borders and the paper.
1670 The unit of the returned rectangle is DevicePixel.
1674 QRect QPrinter::pageRect() const
1676 Q_D(const QPrinter);
1677 return d->printEngine->property(QPrintEngine::PPK_PageRect).toRect();
1681 Returns the paper's rectangle; this is usually larger than the
1684 The unit of the returned rectangle is DevicePixel.
1688 QRect QPrinter::paperRect() const
1690 Q_D(const QPrinter);
1691 return d->printEngine->property(QPrintEngine::PPK_PaperRect).toRect();
1698 This function sets the \a left, \a top, \a right and \a bottom
1699 page margins for this printer. The unit of the margins are
1700 specified with the \a unit parameter.
1702 void QPrinter::setPageMargins(qreal left, qreal top, qreal right, qreal bottom, QPrinter::Unit unit)
1705 const qreal multiplier = qt_multiplierForUnit(unit, resolution());
1706 QList<QVariant> margins;
1707 margins << (left * multiplier) << (top * multiplier)
1708 << (right * multiplier) << (bottom * multiplier);
1709 d->printEngine->setProperty(QPrintEngine::PPK_PageMargins, margins);
1710 d->addToManualSetList(QPrintEngine::PPK_PageMargins);
1711 d->hasCustomPageMargins = true;
1717 Returns the page margins for this printer in \a left, \a top, \a
1718 right, \a bottom. The unit of the returned margins are specified
1719 with the \a unit parameter.
1721 void QPrinter::getPageMargins(qreal *left, qreal *top, qreal *right, qreal *bottom, QPrinter::Unit unit) const
1723 Q_D(const QPrinter);
1724 Q_ASSERT(left && top && right && bottom);
1725 const qreal multiplier = qt_multiplierForUnit(unit, resolution());
1726 QList<QVariant> margins(d->printEngine->property(QPrintEngine::PPK_PageMargins).toList());
1727 *left = margins.at(0).toReal() / multiplier;
1728 *top = margins.at(1).toReal() / multiplier;
1729 *right = margins.at(2).toReal() / multiplier;
1730 *bottom = margins.at(3).toReal() / multiplier;
1736 Returns the metric for the given \a id.
1738 int QPrinter::metric(PaintDeviceMetric id) const
1740 Q_D(const QPrinter);
1741 return d->printEngine->metric(id);
1745 Returns the paint engine used by the printer.
1747 QPaintEngine *QPrinter::paintEngine() const
1749 Q_D(const QPrinter);
1750 return d->paintEngine;
1756 Returns the print engine used by the printer.
1758 QPrintEngine *QPrinter::printEngine() const
1760 Q_D(const QPrinter);
1761 return d->printEngine;
1764 #if defined (Q_WS_WIN)
1766 Sets the page size to be used by the printer under Windows to \a
1769 \warning This function is not portable so you may prefer to use
1770 setPaperSize() instead.
1774 void QPrinter::setWinPageSize(int pageSize)
1777 ABORT_IF_ACTIVE("QPrinter::setWinPageSize");
1778 d->printEngine->setProperty(QPrintEngine::PPK_WindowsPageSize, pageSize);
1779 d->addToManualSetList(QPrintEngine::PPK_WindowsPageSize);
1783 Returns the page size used by the printer under Windows.
1785 \warning This function is not portable so you may prefer to use
1786 paperSize() instead.
1788 \sa setWinPageSize()
1790 int QPrinter::winPageSize() const
1792 Q_D(const QPrinter);
1793 return d->printEngine->property(QPrintEngine::PPK_WindowsPageSize).toInt();
1798 Returns a list of the resolutions (a list of dots-per-inch
1799 integers) that the printer says it supports.
1801 For X11 where all printing is directly to postscript, this
1802 function will always return a one item list containing only the
1803 postscript resolution, i.e., 72 (72 dpi -- but see PrinterMode).
1805 QList<int> QPrinter::supportedResolutions() const
1807 Q_D(const QPrinter);
1808 QList<QVariant> varlist
1809 = d->printEngine->property(QPrintEngine::PPK_SupportedResolutions).toList();
1811 for (int i=0; i<varlist.size(); ++i)
1812 intlist << varlist.at(i).toInt();
1817 Tells the printer to eject the current page and to continue
1818 printing on a new page. Returns true if this was successful;
1819 otherwise returns false.
1821 Calling newPage() on an inactive QPrinter object will always
1824 bool QPrinter::newPage()
1827 if (d->printEngine->printerState() != QPrinter::Active)
1829 return d->printEngine->newPage();
1833 Aborts the current print run. Returns true if the print run was
1834 successfully aborted and printerState() will return QPrinter::Aborted; otherwise
1837 It is not always possible to abort a print job. For example,
1838 all the data has gone to the printer but the printer cannot or
1839 will not cancel the job when asked to.
1841 bool QPrinter::abort()
1844 return d->printEngine->abort();
1848 Returns the current state of the printer. This may not always be
1849 accurate (for example if the printer doesn't have the capability
1850 of reporting its state to the operating system).
1852 QPrinter::PrinterState QPrinter::printerState() const
1854 Q_D(const QPrinter);
1855 return d->printEngine->printerState();
1859 /*! \fn void QPrinter::margins(uint *top, uint *left, uint *bottom, uint *right) const
1861 Sets *\a top, *\a left, *\a bottom, *\a right to be the top,
1862 left, bottom, and right margins.
1864 This function has been superseded by paperRect() and pageRect().
1865 Use paperRect().top() - pageRect().top() for the top margin,
1866 paperRect().left() - pageRect().left() for the left margin,
1867 paperRect().bottom() - pageRect().bottom() for the bottom margin,
1868 and papaerRect().right() - pageRect().right() for the right
1874 printer->margins(0, 0, &bottomMargin, &rightMargin);
1876 int rightMargin = printer->paperRect().right() - printer->pageRect().right();
1877 int bottomMargin = printer->paperRect().bottom() - printer->pageRect().bottom();
1881 /*! \fn QSize QPrinter::margins() const
1885 Returns a QSize containing the left margin and the top margin.
1887 This function has been superseded by paperRect() and pageRect().
1888 Use paperRect().left() - pageRect().left() for the left margin,
1889 and paperRect().top() - pageRect().top() for the top margin.
1892 QSize margins = printer->margins();
1893 int leftMargin = margins.width();
1894 int topMargin = margins.height();
1896 int leftMargin = printer->paperRect().left() - printer->pageRect().left();
1897 int topMargin = printer->paperRect().top() - printer->pageRect().top();
1901 /*! \fn bool QPrinter::aborted()
1903 Use printerState() == QPrinter::Aborted instead.
1910 HDC QPrinter::getDC() const
1912 Q_D(const QPrinter);
1913 return d->printEngine->getPrinterDC();
1919 void QPrinter::releaseDC(HDC hdc) const
1921 Q_D(const QPrinter);
1922 d->printEngine->releasePrinterDC(hdc);
1926 Returns the supported paper sizes for this printer.
1928 The values will be either a value that matches an entry in the
1929 QPrinter::PaperSource enum or a driver spesific value. The driver
1930 spesific values are greater than the constant DMBIN_USER declared
1933 \warning This function is only available in windows.
1936 QList<QPrinter::PaperSource> QPrinter::supportedPaperSources() const
1938 Q_D(const QPrinter);
1939 QVariant v = d->printEngine->property(QPrintEngine::PPK_PaperSources);
1941 QList<QVariant> variant_list = v.toList();
1942 QList<QPrinter::PaperSource> int_list;
1943 for (int i=0; i<variant_list.size(); ++i)
1944 int_list << (QPrinter::PaperSource) variant_list.at(i).toInt();
1952 \fn QString QPrinter::printerSelectionOption() const
1954 Returns the printer options selection string. This is useful only
1955 if the print command has been explicitly set.
1957 The default value (an empty string) implies that the printer should
1958 be selected in a system-dependent manner.
1960 Any other value implies that the given value should be used.
1962 \warning This function is not available on Windows.
1964 \sa setPrinterSelectionOption()
1968 \fn void QPrinter::setPrinterSelectionOption(const QString &option)
1970 Sets the printer to use \a option to select the printer. \a option
1971 is null by default (which implies that Qt should be smart enough
1972 to guess correctly), but it can be set to other values to use a
1973 specific printer selection option.
1975 If the printer selection option is changed while the printer is
1976 active, the current print job may or may not be affected.
1978 \warning This function is not available on Windows.
1980 \sa printerSelectionOption()
1984 QString QPrinter::printerSelectionOption() const
1986 Q_D(const QPrinter);
1987 return d->printEngine->property(QPrintEngine::PPK_SelectionOption).toString();
1990 void QPrinter::setPrinterSelectionOption(const QString &option)
1993 d->printEngine->setProperty(QPrintEngine::PPK_SelectionOption, option);
1994 d->addToManualSetList(QPrintEngine::PPK_SelectionOption);
2000 \fn int QPrinter::fromPage() const
2002 Returns the number of the first page in a range of pages to be printed
2003 (the "from page" setting). Pages in a document are numbered according to
2004 the convention that the first page is page 1.
2006 By default, this function returns a special value of 0, meaning that
2007 the "from page" setting is unset.
2009 \note If fromPage() and toPage() both return 0, this indicates that
2010 \e{the whole document will be printed}.
2012 \sa setFromTo(), toPage()
2015 int QPrinter::fromPage() const
2017 Q_D(const QPrinter);
2024 Returns the number of the last page in a range of pages to be printed
2025 (the "to page" setting). Pages in a document are numbered according to
2026 the convention that the first page is page 1.
2028 By default, this function returns a special value of 0, meaning that
2029 the "to page" setting is unset.
2031 \note If fromPage() and toPage() both return 0, this indicates that
2032 \e{the whole document will be printed}.
2034 The programmer is responsible for reading this setting and
2035 printing accordingly.
2037 \sa setFromTo(), fromPage()
2040 int QPrinter::toPage() const
2042 Q_D(const QPrinter);
2049 Sets the range of pages to be printed to cover the pages with numbers
2050 specified by \a from and \a to, where \a from corresponds to the first
2051 page in the range and \a to corresponds to the last.
2053 \note Pages in a document are numbered according to the convention that
2054 the first page is page 1. However, if \a from and \a to are both set to 0,
2055 the \e{whole document will be printed}.
2057 This function is mostly used to set a default value that the user can
2058 override in the print dialog when you call setup().
2060 \sa fromPage(), toPage()
2063 void QPrinter::setFromTo(int from, int to)
2067 qWarning() << "QPrinter::setFromTo: 'from' must be less than or equal to 'to'";
2073 if (d->minPage == 0 && d->maxPage == 0) {
2076 d->options |= QAbstractPrintDialog::PrintPageRange;
2083 Sets the print range option in to be \a range.
2085 void QPrinter::setPrintRange( PrintRange range )
2088 d->printRange = QAbstractPrintDialog::PrintRange(range);
2094 Returns the page range of the QPrinter. After the print setup
2095 dialog has been opened, this function returns the value selected
2100 QPrinter::PrintRange QPrinter::printRange() const
2102 Q_D(const QPrinter);
2103 return PrintRange(d->printRange);
2106 #if defined(QT3_SUPPORT)
2108 void QPrinter::setOutputToFile(bool f)
2111 if (outputFileName().isEmpty())
2112 setOutputFileName(QLatin1String("untitled_printer_document"));
2114 setOutputFileName(QString());
2118 bool qt_compat_QPrinter_printSetup(QPrinter *printer, QPrinterPrivate *pd, QWidget *parent)
2121 QPrintDialog dlg(printer, parent);
2122 return dlg.exec() != 0;
2127 bool qt_compat_QPrinter_pageSetup(QPrinter *p, QWidget *parent)
2129 QPageSetupDialog psd(p, parent);
2130 return psd.exec() != 0;
2134 Executes a page setup dialog so that the user can configure the type of
2135 page used for printing. Returns true if the contents of the dialog are
2136 accepted; returns false if the dialog is canceled.
2138 bool QPrinter::pageSetup(QWidget *parent)
2140 return qt_compat_QPrinter_pageSetup(this, parent);
2144 Executes a print setup dialog so that the user can configure the printing
2145 process. Returns true if the contents of the dialog are accepted; returns
2146 false if the dialog is canceled.
2148 bool QPrinter::printSetup(QWidget *parent)
2151 return qt_compat_QPrinter_printSetup(this, d, parent);
2156 Use QPrintDialog instead.
2159 if (printer->setup(parent))
2162 QPrintDialog dialog(printer, parent);
2167 bool QPrinter::setup(QWidget *parent)
2170 return qt_compat_QPrinter_printSetup(this, d, parent)
2172 && qt_compat_QPrinter_pageSetup(this, parent);
2178 Use QPrintDialog::minPage() instead.
2180 int QPrinter::minPage() const
2182 Q_D(const QPrinter);
2187 Use QPrintDialog::maxPage() instead.
2189 int QPrinter::maxPage() const
2191 Q_D(const QPrinter);
2196 Use QPrintDialog::setMinMax() instead.
2198 void QPrinter::setMinMax( int minPage, int maxPage )
2201 Q_ASSERT_X(minPage <= maxPage, "QPrinter::setMinMax",
2202 "'min' must be less than or equal to 'max'");
2203 d->minPage = minPage;
2204 d->maxPage = maxPage;
2205 d->options |= QPrintDialog::PrintPageRange;
2209 Returns true if the printer is set up to collate copies of printed documents;
2210 otherwise returns false.
2212 Use QPrintDialog::isOptionEnabled(QPrintDialog::PrintCollateCopies)
2217 bool QPrinter::collateCopiesEnabled() const
2219 Q_D(const QPrinter);
2220 return (d->options & QPrintDialog::PrintCollateCopies);
2224 Use QPrintDialog::setOption(QPrintDialog::PrintCollateCopies)
2225 or QPrintDialog::setOptions(QPrintDialog::options()
2226 & ~QPrintDialog::PrintCollateCopies) instead, depending on \a
2229 void QPrinter::setCollateCopiesEnabled(bool enable)
2234 d->options |= QPrintDialog::PrintCollateCopies;
2236 d->options &= ~QPrintDialog::PrintCollateCopies;
2240 Use QPrintDialog instead.
2242 void QPrinter::setOptionEnabled( PrinterOption option, bool enable )
2246 d->options |= QPrintDialog::PrintDialogOption(1 << option);
2248 d->options &= ~QPrintDialog::PrintDialogOption(1 << option);
2252 Use QPrintDialog instead.
2254 bool QPrinter::isOptionEnabled( PrinterOption option ) const
2256 Q_D(const QPrinter);
2257 return (d->options & QPrintDialog::PrintDialogOption(option));
2260 #endif // QT3_SUPPORT
2268 \brief The QPrintEngine class defines an interface for how QPrinter
2269 interacts with a given printing subsystem.
2271 The common case when creating your own print engine is to derive from both
2272 QPaintEngine and QPrintEngine. Various properties of a print engine are
2273 given with property() and set with setProperty().
2279 \enum QPrintEngine::PrintEnginePropertyKey
2281 This enum is used to communicate properties between the print
2282 engine and QPrinter. A property may or may not be supported by a
2285 \value PPK_CollateCopies A boolean value indicating whether the
2286 printout should be collated or not.
2288 \value PPK_ColorMode Refers to QPrinter::ColorMode, either color or
2291 \value PPK_Creator A string describing the document's creator.
2293 \value PPK_Duplex A boolean value indicating whether both sides of
2294 the printer paper should be used for the printout.
2296 \value PPK_DocumentName A string describing the document name in
2299 \value PPK_FontEmbedding A boolean value indicating whether data for
2300 the document's fonts should be embedded in the data sent to the
2303 \value PPK_FullPage A boolean describing if the printer should be
2306 \value PPK_NumberOfCopies Obsolete. An integer specifying the number of
2307 copies. Use PPK_CopyCount instead.
2309 \value PPK_Orientation Specifies a QPrinter::Orientation value.
2311 \value PPK_OutputFileName The output file name as a string. An
2312 empty file name indicates that the printer should not print to a file.
2314 \value PPK_PageOrder Specifies a QPrinter::PageOrder value.
2316 \value PPK_PageRect A QRect specifying the page rectangle
2318 \value PPK_PageSize Obsolete. Use PPK_PaperSize instead.
2320 \value PPK_PaperRect A QRect specifying the paper rectangle.
2322 \value PPK_PaperSource Specifies a QPrinter::PaperSource value.
2324 \value PPK_PaperSources Specifies more than one QPrinter::PaperSource value.
2326 \value PPK_PaperSize Specifies a QPrinter::PaperSize value.
2328 \value PPK_PrinterName A string specifying the name of the printer.
2330 \value PPK_PrinterProgram A string specifying the name of the
2331 printer program used for printing,
2333 \value PPK_Resolution An integer describing the dots per inch for
2336 \value PPK_SelectionOption
2338 \value PPK_SupportedResolutions A list of integer QVariants
2339 describing the set of supported resolutions that the printer has.
2341 \value PPK_SuppressSystemPrintStatus Suppress the built-in dialog for showing
2342 printing progress. As of 4.1 this only has effect on Mac OS X where, by default,
2343 a status dialog is shown.
2345 \value PPK_WindowsPageSize An integer specifying a DM_PAPER entry
2348 \value PPK_CustomPaperSize A QSizeF specifying a custom paper size
2349 in the QPrinter::Point unit.
2351 \value PPK_PageMargins A QList<QVariant> containing the left, top,
2352 right and bottom margin values.
2354 \value PPK_CopyCount An integer specifying the number of copies to print.
2356 \value PPK_SupportsMultipleCopies A boolean value indicating whether or not
2357 the printer supports printing multiple copies in one job.
2359 \value PPK_CustomBase Basis for extension.
2363 \fn QPrintEngine::~QPrintEngine()
2365 Destroys the print engine.
2369 \fn void QPrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &value)
2371 Sets the print engine's property specified by \a key to the given \a value.
2377 \fn void QPrintEngine::property(PrintEnginePropertyKey key) const
2379 Returns the print engine's property specified by \a key.
2385 \fn bool QPrintEngine::newPage()
2387 Instructs the print engine to start a new page. Returns true if
2388 the printer was able to create the new page; otherwise returns false.
2392 \fn bool QPrintEngine::abort()
2394 Instructs the print engine to abort the printing process. Returns
2395 true if successful; otherwise returns false.
2399 \fn int QPrintEngine::metric(QPaintDevice::PaintDeviceMetric id) const
2401 Returns the metric for the given \a id.
2405 \fn QPrinter::PrinterState QPrintEngine::printerState() const
2407 Returns the current state of the printer being used by the print engine.
2411 \fn HDC QPrintEngine::getPrinterDC() const
2416 \fn void QPrintEngine::releasePrinterDC(HDC) const
2421 Returns the dimensions for the given paper size, \a size, in millimeters.
2423 QSizeF qt_paperSizeToQSizeF(QPrinter::PaperSize size)
2425 if (size == QPrinter::Custom) return QSizeF(0, 0);
2426 return QSizeF(qt_paperSizes[size][0], qt_paperSizes[size][1]);
2430 Returns the PaperSize type that matches \a size, where \a size
2433 Because dimensions may not always be completely accurate (for
2434 example when converting between units), a particular PaperSize
2435 will be returned if it matches within -1/+1 millimeters.
2437 QPrinter::PaperSize qSizeFTopaperSize(const QSizeF& size)
2439 for (int i = 0; i < static_cast<int>(QPrinter::NPaperSize); ++i) {
2440 if (qt_paperSizes[i][0] >= size.width() - 1 &&
2441 qt_paperSizes[i][0] <= size.width() + 1 &&
2442 qt_paperSizes[i][1] >= size.height() - 1 &&
2443 qt_paperSizes[i][1] <= size.height() + 1) {
2444 return QPrinter::PaperSize(i);
2448 return QPrinter::Custom;
2453 #endif // QT_NO_PRINTER