1QPrinter(3qt) QPrinter(3qt)
2
6 QPrinter - Paint device that paints on a printer
7
9 #include <qprinter.h>
10 Inherits QPaintDevice.
12 Public Members
14 enum PrinterMode { ScreenResolution, PrinterResolution, HighResolution,
15 Compatible }
16 QPrinter ( PrinterMode m = ScreenResolution )
17 ~QPrinter ()
18 enum Orientation { Portrait, Landscape }
19 enum PageSize { A4, B5, Letter, Legal, Executive, A0, A1, A2, A3, A5,
20 A6, A7, A8, A9, B0, B1, B10, B2, B3, B4, B6, B7, B8, B9, C5E,
21 Comm10E, DLE, Folio, Ledger, Tabloid, Custom, NPageSize = Custom }
22 enum PageOrder { FirstPageFirst, LastPageFirst }
23 enum ColorMode { GrayScale, Color }
24 enum PaperSource { OnlyOne, Lower, Middle, Manual, Envelope,
25 EnvelopeManual, Auto, Tractor, SmallFormat, LargeFormat,
26 LargeCapacity, Cassette, FormSource }
27 enum PrintRange { AllPages, Selection, PageRange }
28 enum PrinterOption { PrintToFile, PrintSelection, PrintPageRange }
29 QString printerName () const
30 virtual void setPrinterName ( const QString & name )
31 bool outputToFile () const
32 virtual void setOutputToFile ( bool enable )
33 QString outputFileName () const
34 virtual void setOutputFileName ( const QString & fileName )
35 QString printProgram () const
36 virtual void setPrintProgram ( const QString & printProg )
37 QString printerSelectionOption () const
38 virtual void setPrinterSelectionOption ( const QString & option )
39 QString docName () const
40 virtual void setDocName ( const QString & name )
41 QString creator () const
42 virtual void setCreator ( const QString & creator )
43 Orientation orientation () const
44 virtual void setOrientation ( Orientation orientation )
45 PageSize pageSize () const
46 virtual void setPageSize ( PageSize newPageSize )
47 void setWinPageSize ( short winPageSize )
48 short winPageSize () const
49 virtual void setPageOrder ( PageOrder newPageOrder )
50 PageOrder pageOrder () const
51 virtual void setResolution ( int dpi )
52 virtual int resolution () const
53 virtual void setColorMode ( ColorMode newColorMode )
54 ColorMode colorMode () const
55 virtual void setFullPage ( bool fp )
56 bool fullPage () const
57 QSize margins () const
58 void setMargins ( uint top, uint left, uint bottom, uint right )
59 void margins ( uint * top, uint * left, uint * bottom, uint * right )
60 const
61 int fromPage () const
62 int toPage () const
63 virtual void setFromTo ( int fromPage, int toPage )
64 int minPage () const
65 int maxPage () const
66 virtual void setMinMax ( int minPage, int maxPage )
67 int numCopies () const
68 virtual void setNumCopies ( int numCopies )
69 PrintRange printRange () const
70 void setPrintRange ( PrintRange range )
71 bool newPage ()
72 bool abort ()
73 bool aborted () const
74 bool setup ( QWidget * parent = 0 )
75 PaperSource paperSource () const
76 virtual void setPaperSource ( PaperSource source )
77 void setOptionEnabled ( PrinterOption option, bool enable )
78 bool isOptionEnabled ( PrinterOption option )
79
81 The QPrinter class is a paint device that paints on a printer.
82 On Windows it uses the built-in printer drivers. On X11 it generates
84 postscript and sends that to lpr, lp, or another print command.
85 QPrinter is used in much the same way as QWidget and QPixmap are used.
87 The big difference is that you must keep track of the pages.
88 QPrinter supports a number of settable parameters, most of which can be
90 changed by the end user when the application calls QPrinter::setup().
91 The most important parameters are:
93 setOrientation() tells QPrinter which page orientation to use
95 (virtual).
96 setPageSize() tells QPrinter what page size to expect from the printer.
98 setResolution() tells QPrinter what resolution you wish the printer to
100 provide (in dpi).
101 setFullPage() tells QPrinter whether you want to deal with the full
103 page or just with the part the printer can draw on. The default is
104 FALSE, so that by default you should be able to paint on (0,0). If TRUE
105 the origin of the coordinate system will be in the top left corner of
106 the paper and most probably the printer will not be able to paint
107 something there due to it's physical margins.
108 setNumCopies() tells QPrinter how many copies of the document it should
110 print.
111 setMinMax() tells QPrinter and QPrintDialog what the allowed range for
113 fromPage() and toPage() are.
114 Except where noted, you can only call the set functions before setup(),
116 or between QPainter::end() and setup(). (Some may take effect between
117 setup() and begin(), or between begin() and end(), but that's strictly
118 undocumented and such behaviour may differ depending on platform.)
119 There are also some settings that the user sets (through the printer
121 dialog) and that applications are expected to obey:
122 pageOrder() tells the application program whether to print first-page-
124 first or last-page-first.
125 colorMode() tells the application program whether to print in color or
127 grayscale. (If you print in color and the printer does not support
128 color, Qt will try to approximate. The document may take longer to
129 print, but the quality should not be made visibly poorer.)
130 fromPage() and toPage() indicate what pages the application program
132 should print.
133 paperSource() tells the application progam which paper source to print
135 from.
136 You can of course call these functions to establish defaults before you
138 ask the user through QPrinter::setup().
139 Once you start printing, calling newPage() is essential. You will
141 probably also need to look at the QPaintDeviceMetrics for the printer
142 (see the print function in the Application walk-through). In previous
143 versions, paint device metrics were valid only after the QPrinter has
144 been set up, i.e. after setup() has returned successfully. This is no
145 longer the case and paint device metrics can be requested safely before
146 set up.
147 If you want to abort the print job, abort() will try its best to stop
149 printing. It may cancel the entire job or just some of it.
150 If your current locale converts "," to ".", you will need to set a
152 locale (via the standard C setlocale() function) that doen't do this
153 before using QPrinter. The "C" locale works well for this.
154 The TrueType font embedding for Qt's postscript driver uses code by
156 David Chappell of Trinity College Computing Center.
157 Copyright 1995, Trinity College Computing Center. Written by David
159 Chappell.
160 Permission to use, copy, modify, and distribute this software and its
162 documentation for any purpose and without fee is hereby granted,
163 provided that the above copyright notice appear in all copies and that
164 both that copyright notice and this permission notice appear in
165 supporting documentation. This software is provided "as is" without
166 express or implied warranty.
167 TrueType font support. These functions allow PPR to generate PostScript
169 fonts from Microsoft compatible TrueType font files.
170 The functions in this file do most of the work to convert a TrueType
172 font to a type 3 PostScript font.
173 Most of the material in this file is derived from a program called"
175 ttf2ps" which L. S. Ng posted to the usenet news group"
176 comp.sources.postscript". The author did not provide a copyright notice
177 or indicate any restrictions on use.
178 Last revised 11 July 1995.
180 See also Graphics Classes and Image Processing Classes.
182 Member Type Documentation
185 This enum type is used to indicate whether QPrinter should print in
186 color or not.
187 QPrinter::Color - print in color if available, otherwise in grayscale.
189 QPrinter::GrayScale - print in grayscale, even on color printers. Might
191 be a little faster than Color. This is the default.
192
194 This enum type (not to be confused with Qt::Orientation) is used to
195 specify each page's orientation.
196 QPrinter::Portrait - the page's height is greater than its width (the
198 default).
199 QPrinter::Landscape - the page's width is greater than its height.
201 This type interacts with QPrinter::PageSize and QPrinter::setFullPage()
203 to determine the final size of the page available to the application.
204
206 This enum type is used by QPrinter to tell the application program how
207 to print.
208 QPrinter::FirstPageFirst - the lowest-numbered page should be printed
210 first.
211 QPrinter::LastPageFirst - the highest-numbered page should be printed
213 first.
214
216 This enum type specifies what paper size QPrinter should use. QPrinter
217 does not check that the paper size is available; it just uses this
218 information, together with QPrinter::Orientation and
219 QPrinter::setFullPage(), to determine the printable area (see
220 QPaintDeviceMetrics).
221 The defined sizes (with setFullPage(TRUE)) are:
223 QPrinter::A0 - 841 x 1189 mm This value is not supported on windows.
225 QPrinter::A1 - 594 x 841 mm This value is not supported on windows.
227 QPrinter::A2 - 420 x 594 mm
229 QPrinter::A3 - 297 x 420 mm
231 QPrinter::A4 - 210 x 297 mm, 8.26 x 11.7 inches
233 QPrinter::A5 - 148 x 210 mm
235 QPrinter::A6 - 105 x 148 mm
237 QPrinter::A7 - 74 x 105 mm
239 QPrinter::A8 - 52 x 74 mm
241 QPrinter::A9 - 37 x 52 mm
243 QPrinter::B0 - 1030 x 1456 mm
245 QPrinter::B1 - 728 x 1030 mm
247 QPrinter::B10 - 32 x 45 mm
249 QPrinter::B2 - 515 x 728 mm
251 QPrinter::B3 - 364 x 515 mm
253 QPrinter::B4 - 257 x 364 mm
255 QPrinter::B5 - 182 x 257 mm, 7.17 x 10.13 inches
257 QPrinter::B6 - 128 x 182 mm
259 QPrinter::B7 - 91 x 128 mm
261 QPrinter::B8 - 64 x 91 mm
263 QPrinter::B9 - 45 x 64 mm
265 QPrinter::C5E - 163 x 229 mm
267 QPrinter::Comm10E - 105 x 241 mm, US Common #10 Envelope
269 QPrinter::DLE - 110 x 220 mm
271 QPrinter::Executive - 7.5 x 10 inches, 191 x 254 mm
273 QPrinter::Folio - 210 x 330 mm
275 QPrinter::Ledger - 432 x 279 mm
277 QPrinter::Legal - 8.5 x 14 inches, 216 x 356 mm
279 QPrinter::Letter - 8.5 x 11 inches, 216 x 279 mm
281 QPrinter::Tabloid - 279 x 432 mm
283 QPrinter::Custom
285 QPrinter::NPageSize - (internal)
287 With setFullPage(FALSE) (the default), the metrics will be a bit
289 smaller; how much depends on the printer in use.
290
292 This enum type specifies what paper source QPrinter is to use. QPrinter
293 does not check that the paper source is available; it just uses this
294 information to try and set the paper source. Whether it will set the
295 paper source depends on whether the printer has that particular source.
296 Note: this is currently only implemented for Windows.
298 QPrinter::OnlyOne
300 QPrinter::Lower
302 QPrinter::Middle
304 QPrinter::Manual
306 QPrinter::Envelope
308 QPrinter::EnvelopeManual
310 QPrinter::Auto
312 QPrinter::Tractor
314 QPrinter::SmallFormat
316 QPrinter::LargeFormat
318 QPrinter::LargeCapacity
320 QPrinter::Cassette
322 QPrinter::FormSource
324
326 This enum is used to specify which print range the application should
327 use to print.
328 QPrinter::AllPages - All pages should be printed
330 QPrinter::Selection - Only the selection should be printed.
332 QPrinter::PageRange - From page, to page option.
334 See also setPrintRange() and printRange().
336
338 This enum describes the mode the printer should work in. It basically
339 presets a certain resolution and working mode.
340 QPrinter::ScreenResolution - Sets the resolution of the print device to
342 the screen resolution. This has the big advantage that the results
343 obtained when painting on the printer will match more or less exactly
344 the visible output on the screen. It is the easiest to use, as font
345 metrics on the screen and on the printer are the same. This is the
346 default value. ScreenResolution will produce a lower quality output
347 than HighResolution and should only be used for drafts.
348 QPrinter::PrinterResolution - Use the physical resolution of the
350 printer on Windows. On Unix, set the postscript resolution to 72 dpi.
351 QPrinter::HighResolution - Use printer resolution on windows, set the
353 resolution of the postscript driver to 600dpi.
354 QPrinter::Compatible - Almost the same as PrinterResolution, but keeps
356 some peculiarities of the Qt 2.x printer driver. This is useful for
357 applications ported from Qt 2.x to Qt 3.x.
358
360 This enum describes various printer options that appear in the printer
361 setup dialog. It is used to enable and disable these options in the
362 setup dialog.
363 QPrinter::PrintToFile - Describes if print to file should be enabled.
365 QPrinter::PrintSelection - Describes if printing selections should be
367 enabled.
368 QPrinter::PrintPageRange - Describes if printing page ranges (from, to)
370 should be enabled
371 See also setOptionEnabled() and isOptionEnabled().
373
376 Constructs a printer paint device with mode m.
377 See also QPrinter::PrinterMode.
379
381 Destroys the printer paint device and cleans up.
382
384 Aborts the print job. Returns TRUE if successful; otherwise returns
385 FALSE.
386 See also aborted().
388
390 Returns TRUE if the print job was aborted; otherwise returns FALSE.
391 See also abort().
393
395 Returns the current color mode. The default color mode is Color.
396 See also setColorMode().
398
400 Returns the name of the application that created the document.
401 See also setCreator().
403
405 Returns the document name.
406 See also setDocName().
408
410 Returns the from-page setting. The default value is 0.
411 If fromPage() and toPage() both return 0 this signifies 'print the
413 whole document'.
414 The programmer is responsible for reading this setting and printing
416 accordingly.
417 See also setFromTo() and toPage().
419
421 Returns TRUE if the origin of the printer's coordinate system is at the
422 corner of the sheet and FALSE if it is at the edge of the printable
423 area.
424 See setFullPage() for details and caveats.
426 See also setFullPage(), PageSize, and QPaintDeviceMetrics.
428
430 Returns TRUE if the printer option with identifier option is enabled;
431 otherwise returns FALSE.
432 See also setOptionEnabled().
434
436 Returns the width of the left margin and the height of the top margin
437 of the printer. On Unix, this is a best-effort guess, not based on
438 perfect knowledge.
439 If you have called setFullPage( TRUE ), margins().width() may be
441 treated as the smallest sane left margin you can use, and
442 margins().height() as the smallest sane top margin you can use.
443 If you have called setFullPage( FALSE ) (this is the default),
445 margins() is automatically subtracted from the pageSize() by QPrinter.
446 See also setFullPage(), QPaintDeviceMetrics, and PageSize.
448
450 ) const
451 This is an overloaded member function, provided for convenience. It
452 behaves essentially like the above function.
453 Sets top, left, bottom and right to the margins of the printer. On
455 Unix, this is a best-effort guess, not based on perfect knowledge.
456 If you have called setFullPage( TRUE ), the four values specify the
458 smallest sane margins you can use.
459 If you have called setFullPage( FALSE ) (this is the default), the
461 margins are automatically subtracted from the pageSize() by QPrinter.
462 See also setFullPage(), QPaintDeviceMetrics, and PageSize.
464
466 Returns the max-page setting. A user can't choose a higher page number
467 than maxPage() when they select a print range. The default value is 0.
468 See also minPage(), setMinMax(), and setFromTo().
470
472 Returns the min-page setting, i.e. the lowest page number a user is
473 allowed to choose. The default value is 0.
474 See also maxPage(), setMinMax(), and setFromTo().
476
478 Advances to a new page on the printer. Returns TRUE if successful;
479 otherwise returns FALSE.
480 Examples:
482
484 Returns the number of copies to be printed. The default value is 1.
485 This value will return the number of times the application is required
487 to print in order to match the number specified in the printer setup
488 dialog. This has been done since some printer drivers are not capable
489 of buffering up the copies and the application in those cases have to
490 make an explicit call to the print code for each copy.
491 See also setNumCopies().
493
495 Returns the orientation setting. The default value is
496 QPrinter::Portrait.
497 See also setOrientation().
499
501 Returns the name of the output file. There is no default file name.
502 See also setOutputFileName() and setOutputToFile().
504
506 Returns TRUE if the output should be written to a file, or FALSE if the
507 output should be sent directly to the printer. The default setting is
508 FALSE.
509 This function is currently only supported under X11 and Mac OS X.
511 See also setOutputToFile() and setOutputFileName().
513
515 Returns the current page order.
516 The default page order is FirstPageFirst.
518 Bugs and limitations:
520 This value is not kept in sync with the Windows or Mac OS X printer
522 dialogs.
523
525 Returns the printer page size. The default value is system-dependent.
526 See also setPageSize().
528
530 Returns the currently set paper source of the printer.
531 See also setPaperSource().
533
535 Returns the name of the program that sends the print output to the
536 printer.
537 The default is to return a null string; meaning that QPrinter will try
539 to be smart in a system-dependent way. On X11 only, you can set it to
540 something different to use a specific print program.
541 On Windows, this function returns the name of the printer device
543 driver.
544 See also setPrintProgram() and setPrinterSelectionOption().
546
548 Returns the PageRange of the QPrinter. After the print setup dialog has
549 been opened, this function returns the value selected by the user.
550 See also setPrintRange().
552
554 Returns the printer name. This value is initially set to the name of
555 the default printer.
556 See also setPrinterName().
558
560 Returns the printer options selection string. This is useful only if
561 the print command has been explicitly set.
562 The default value (a null string) implies that the printer should be
564 selected in a system-dependent manner.
565 Any other value implies that the given value should be used.
567 See also setPrinterSelectionOption().
569
571 Returns the current assumed resolution of the printer, as set by
572 setResolution() or by the printer subsystem.
573 See also setResolution().
575
577 Sets the printer's color mode to newColorMode, which can be either
578 Color or GrayScale (the default).
579 See also colorMode().
581
583 Sets the name of the application that created the document to creator.
584 This function is only applicable to the X11 version of Qt. If no
586 creator name is specified, the creator will be set to "Qt" followed by
587 some version number.
588 See also creator().
590
592 Sets the document name to name.
593
595 Sets the from-page and to-page settings to fromPage and toPage
596 respectively.
597 The from-page and to-page settings specify what pages to print.
599 If fromPage() and toPage() both return 0 this signifies 'print the
601 whole document'.
602 This function is useful mostly to set a default value that the user can
604 override in the print dialog when you call setup().
605 See also fromPage(), toPage(), setMinMax(), and setup().
607
609 Sets QPrinter to have the origin of the coordinate system at the top-
610 left corner of the paper if fp is TRUE, or where it thinks the top-left
611 corner of the printable area is if fp is FALSE.
612 The default is FALSE. You can (probably) print on (0,0), and
614 QPaintDeviceMetrics will report something smaller than the size
615 indicated by PageSize. (Note that QPrinter may be wrong on Unix systems
616 - it does not have perfect knowledge of the physical printer.)
617 If you set fp to TRUE, QPaintDeviceMetrics will report the exact same
619 size as indicated by PageSize, but you cannot print on all of that -
620 you must take care of the output margins yourself.
621 See also PageSize, setPageSize(), QPaintDeviceMetrics, and fullPage().
623 Examples:
625
627 Sets the printer margins to the sizes specified in top, left, bottom
628 and right.
629 This function currently only has an effect on Unix systems.
631 See also margins().
633
635 Sets the min-page and max-page settings to minPage and maxPage
636 respectively.
637 The min-page and max-page restrict the from-page and to-page settings.
639 When the printer setup dialog appears, the user cannot select a from
640 page or a to page that are outside the range specified by min and max
641 pages.
642 See also minPage(), maxPage(), setFromTo(), and setup().
644
646 Sets the number of copies to be printed to numCopies.
647 The printer driver reads this setting and prints the specified number
649 of copies.
650 See also numCopies() and setup().
652
654 Enables the printer option with the identifier option if enable is
655 TRUE, and disables option option if enable is FALSE.
656 See also isOptionEnabled().
658
660 Sets the print orientation to orientation.
661 The orientation can be either QPrinter::Portrait or
663 QPrinter::Landscape.
664 The printer driver reads this setting and prints using the specified
666 orientation. On Windows this setting won't take effect until the
667 printer dialog is shown (using QPrinter::setup()).
668 Windows only! This option can be changed while printing and will take
670 effect from the next call to newPage()
671 See also orientation().
673
675 Sets the name of the output file to fileName.
676 Setting a null or empty name (0 or "") disables output to a file, i.e.
678 calls setOutputToFile(FALSE). Setting a non-empty name enables output
679 to a file, i.e. calls setOutputToFile(TRUE).
680 This function is currently only supported under X11.
682 See also outputFileName() and setOutputToFile().
684
686 Specifies whether the output should be written to a file or sent
687 directly to the printer.
688 Will output to a file if enable is TRUE, or will output directly to the
690 printer if enable is FALSE.
691 This function is currently only supported under X11 and Mac OS X.
693 See also outputToFile() and setOutputFileName().
695
697 Sets the page order to newPageOrder.
698 The page order can be QPrinter::FirstPageFirst or
700 QPrinter::LastPageFirst. The application programmer is responsible for
701 reading the page order and printing accordingly.
702 This function is useful mostly for setting a default value that the
704 user can override in the print dialog when you call setup().
705 Bugs and limitations:
707 This value is not kept in sync with the Windows or Mac OS X printer
709 dialogs.
710
712 Sets the printer page size to newPageSize if that size is supported.
713 The result if undefined if newPageSize is not supported.
714 The default page size is system-dependent.
716 This function is useful mostly for setting a default value that the
718 user can override in the print dialog when you call setup().
719 See also pageSize(), PageSize, setFullPage(), and setResolution().
721
723 Sets the paper source setting to source.
724 Windows only! This option can be changed while printing and will take
726 effect from the next call to newPage()
727 See also paperSource().
729
731 Sets the name of the program that should do the print job to printProg.
732 On X11, this function sets the program to call with the PostScript
734 output. On other platforms, it has no effect.
735 See also printProgram().
737
739 Sets the default selected page range to be used when the print setup
740 dialog is opened to range. If the PageRange specified by range is
741 currently disabled the function does nothing.
742 See also printRange().
744
746 Sets the printer name to name.
747 The default printer will be used if no printer name is set.
749 Under X11, the PRINTER environment variable defines the default
751 printer. Under any other window system, the window system defines the
752 default printer.
753 See also printerName().
755
757 Sets the printer to use option to select the printer. option is null by
758 default (which implies that Qt should be smart enough to guess
759 correctly), but it can be set to other values to use a specific printer
760 selection option.
761 If the printer selection option is changed while the printer is active,
763 the current print job may or may not be affected.
764 See also printerSelectionOption().
766
768 Requests that the printer prints at dpi or as near to dpi as possible.
769 This setting affects the coordinate system as returned by, for example,
771 QPaintDeviceMetrics and QPainter::viewport().
772 The value depends on the PrintingMode used in the QPrinter constructor.
774 By default, the dpi value of the screen is used.
775 This function must be called before setup() to have an effect on all
777 platforms.
778 See also resolution() and setPageSize().
780
782 Windows only, using this function is not portable! Sets the windows
783 page size value that is used by the DEVMODE struct. The winPageSize
784 value must be one of the DMPAPER_ defines from wingdi.h.
785
787 Opens a printer setup dialog, with parent parent, and asks the user to
788 specify which printer they wish to use and what settings it should
789 have.
790 Returns TRUE if the user pressed "OK" to print, or FALSE if the user
792 canceled the operation.
793 Examples:
795
797 Returns the to-page setting. The default value is 0.
798 If fromPage() and toPage() both return 0 this signifies 'print the
800 whole document'.
801 The programmer is responsible for reading this setting and printing
803 accordingly.
804 See also setFromTo() and fromPage().
806
808 Returns the Windows page size value as used by the DEVMODE struct
809 (Windows only). Using this function is not portable.
810 Use pageSize() to get the PageSize, e.g. 'A4', 'Letter', etc.
812
815 http://doc.trolltech.com/qprinter.html
816 http://www.trolltech.com/faq/tech.html
817
819 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
820 license file included in the distribution for a complete license
821 statement.
822
824 Generated automatically from the source code.
825
827 If you find a bug in Qt, please report it as described in
828 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
829 help you. Thank you.
830 The definitive Qt documentation is provided in HTML format; it is
832 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
833 web browser. This man page is provided as a convenience for those users
834 who prefer man pages, although this format is not officially supported
835 by Trolltech.
836 If you find errors in this manual page, please report them to qt-
838 bugs@trolltech.com. Please include the name of the manual page
839 (qprinter.3qt) and the Qt version (3.3.8).
840Trolltech AS 2 February 2007 QPrinter(3qt)