docs/latex/wx/tprint.tex

   1 \section{Printing overview}\label{printingoverview}
   2
   3 Classes: \helpref{wxPrintout}{wxprintout},
   4 \helpref{wxPrinter}{wxprinter},
   5 \helpref{wxPrintPreview}{wxprintpreview},
   6 \helpref{wxPrinterDC}{wxprinterdc},
   7 \helpref{wxPostScriptDC}{wxpostscriptdc},
   8 \helpref{wxPrintDialog}{wxprintdialog},
   9 \helpref{wxPrintData}{wxprintdata},
  10 \helpref{wxPrintDialogData}{wxprintdialogdata},
  11 \helpref{wxPageSetupDialog}{wxpagesetupdialog},
  12 \helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}
  13
  14 The printing framework relies on the application to provide classes whose member
  15 functions can respond to particular requests, such as `print this page' or `does
  16 this page exist in the document?'. This method allows wxWidgets to take over the
  17 housekeeping duties of turning preview pages, calling the print dialog box,
  18 creating the printer device context, and so on: the application can concentrate
  19 on the rendering of the information onto a device context.
  20
  21 In most cases, the only class you will need to derive from is
  22 \helpref{wxPrintout}{wxprintout}; all others will be used as-is.
  23
  24 A brief description of each class's role and how they work together follows.
  25
  26 For the special case of printing under Unix, where various different
  27 printing backends have to be offered, please have a look at the
  28 \helpref{Unix printing overview}{unixprinting}.
  29
  30 \subsection{\helpref{wxPrintout}{wxprintout}}
  31
  32 A document's printing ability is represented in an application by a derived
  33 wxPrintout class. This class prints a page on request, and can be passed to the
  34 Print function of a wxPrinter object to actually print the document, or can be
  35 passed to a wxPrintPreview object to initiate previewing. The following code
  36 (from the printing sample) shows how easy it is to initiate printing, previewing
  37 and the print setup dialog, once the wxPrintout functionality has been defined.
  38 Notice the use of MyPrintout for both printing and previewing. All the preview
  39 user interface functionality is taken care of by wxWidgets. For more details on how
  40 MyPrintout is defined, please look at the printout sample code.
  41
  42 \begin{verbatim}
  43     case WXPRINT_PRINT:
  44     {
  45       wxPrinter printer;
  46       MyPrintout printout("My printout");
  47       printer.Print(this, &printout, true);
  48       break;
  49     }
  50     case WXPRINT_PREVIEW:
  51     {
  52       // Pass two printout objects: for preview, and possible printing.
  53       wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
  54       wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", wxPoint(100, 100), wxSize(600, 650));
  55       frame->Centre(wxBOTH);
  56       frame->Initialize();
  57       frame->Show(true);
  58       break;
  59     }
  60 \end{verbatim}
  61
  62 Class \helpref{wxPrintout}{wxprintout} assembles the printed page and (using
  63 your subclass's overrides) writes requested pages to a \helpref{wxDC}{wxdc} that
  64 is passed to it. This wxDC could be a \helpref{wxMemoryDC}{wxmemorydc} (for
  65 displaying the preview image on-screen), a \helpref{wxPrinterDC}{wxprinterdc}
  66 (for printing under MSW and Mac), or a \helpref{wxPostScriptDC}{wxpostscriptdc}
  67 (for printing under GTK or generating PostScript output).
  68
  69 The \helpref{document/view framework}{docviewoverview} creates a default
  70 wxPrintout object for every view, calling wxView::OnDraw to achieve a
  71 prepackaged print/preview facility.
  72
  73 If your window classes have a Draw(wxDC *dc) routine to do screen rendering,
  74 your wxPrintout subclass will typically call those routines to create portions
  75 of the image on your printout. Your wxPrintout subclass can also make its own
  76 calls to its wxDC to draw headers, footers, page numbers, etc.
  77
  78 The scaling of the drawn image typically differs from the screen to the preview
  79 and printed images. This class provides a set of routines named
  80 FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
  81 used to set the user scale and origin of the wxPrintout's DC so that your class
  82 can easily map your image to the printout withough getting into the details of
  83 screen and printer PPI and scaling. See the printing sample for examples of how
  84 these routines are used.
  85
  86 \subsection{\helpref{wxPrinter}{wxprinter}}
  87
  88 Class wxPrinter encapsulates the platform-dependent print function with a common
  89 interface. In most cases, you will not need to derive a class from wxPrinter;
  90 simply create a wxPrinter object in your Print function as in the example above.
  91
  92 \subsection{\helpref{wxPrintPreview}{wxprintpreview}}
  93
  94 Class wxPrintPreview manages the print preview process. Among other things, it
  95 constructs the wxDCs that get passed to your wxPrintout subclass for printing
  96 and manages the display of multiple pages, a zoomable preview image, and so
  97 forth. In most cases you will use this class as-is, but you can create your own
  98 subclass, for example, to change the layout or contents of the preview window.
  99
 100
 101 \subsection{\helpref{wxPrinterDC}{wxprinterdc}}
 102
 103 Class wxPrinterDC is the wxDC that represents the actual printed page under MSW
 104 and Mac. During printing, an object of this class will be passed to your derived
 105 wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the
 106 paper orientation and the resolution of the printer.
 107
 108 There are two important rectangles in printing: the \em{page rectangle} defines
 109 the printable area seen by the application, and under MSW and Mac, it is the
 110 printable area specified by the printer. (For PostScript printing, the page
 111 rectangle is the entire page.) The inherited function
 112 \helpref{wxDC::GetSize}{wxdcgetsize} returns the page size in device pixels. The
 113 point (0,0) on the wxPrinterDC represents the top left corner of the page
 114 rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h)
 115 are the values returned by GetSize.
 116
 117 The \em{paper rectangle}, on the other hand, represents the entire paper area
 118 including the non-printable border. Thus, the coordinates of the top left corner
 119 of the paper rectangle will have small negative values, while the width and
 120 height will be somewhat larger than that of the page rectangle. The
 121 wxPrinterDC-specific function
 122 \helpref{wxPrinterDC::GetPaperRect}{wxprinterdcgetpaperrect} returns the paper
 123 rectangle of the given wxPrinterDC.
 124
 125 \subsection{\helpref{wxPostScriptDC}{wxpostscriptdc}}
 126
 127 Class wxPostScriptDC is the wxDC that represents the actual printed page under
 128 GTK and other PostScript printing. During printing, an object of this class will
 129 be passed to your derived wxPrintout object to draw upon. The size of the
 130 wxPostScriptDC will depend upon the \helpref{wxPrintData}{wxprintdata} used to
 131 construct it.
 132
 133 Unlike a wxPrinterDC, there is no distinction between the page rectangle and the
 134 paper rectangle in a wxPostScriptDC; both rectangles are taken to represent the
 135 entire sheet of paper.
 136
 137 \subsection{\helpref{wxPrintDialog}{wxprintdialog}}
 138
 139 Class wxPrintDialog puts up the standard print dialog, which allows you to
 140 select the page range for printing (as well as many other print settings, which
 141 may vary from platform to platform). You provide an object of type
 142 \helpref{wxPrintDialogData}{wxprintdialogdata} to the wxPrintDialog at
 143 construction, which is used to populate the dialog.
 144
 145 \subsection{\helpref{wxPrintData}{wxprintdata}}
 146
 147 Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to
 148 initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data
 149 member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially,
 150 wxPrintData contains those bits of information from the two dialogs necessary to
 151 configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.). You
 152 might wish to create a global instance of this object to provide call-to-call
 153 persistence to your application's print settings.
 154
 155 \subsection{\helpref{wxPrintDialogData}{wxprintdialogdata}}
 156
 157 Class wxPrintDialogData contains the settings entered by the user in the print
 158 dialog. It contains such things as page range, number of copies, and so forth.
 159 In most cases, you won't need to access this information; the framework takes
 160 care of asking your wxPrintout derived object for the pages requested by the
 161 user.
 162
 163 \subsection{\helpref{wxPageSetupDialog}{wxpagesetupdialog}}
 164
 165 Class wxPageSetupDialog puts up the standard page setup dialog, which allows you
 166 to specify the orientation, paper size, and related settings. You provide it
 167 with a wxPageSetupDialogData object at intialization, which is used to populate
 168 the dialog; when the dialog is dismissed, this object contains the settings
 169 chosen by the user, including orientation and/or page margins.
 170
 171 Note that on Macintosh, the native page setup dialog does not contain entries
 172 that allow you to change the page margins. You can use the Mac-specific class
 173 wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a
 174 wxPageSetupDialogData object in its constructor) to provide this capability; see
 175 the printing sample for an example.
 176
 177 \subsection{\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}}
 178
 179 Class wxPageSetupDialogData contains settings affecting the page size (paper
 180 size), orientation, margins, and so forth. Note that not all platforms populate
 181 all fields; for example, the MSW page setup dialog lets you set the page margins
 182 while the Mac setup dialog does not.
 183
 184 You will typically create a global instance of each of a wxPrintData and
 185 wxPageSetupDialogData at program initiation, which will contain the default
 186 settings provided by the system. Each time the user calls up either the
 187 wxPrintDialog or the wxPageSetupDialog, you pass these data structures to
 188 initialize the dialog values and to be updated by the dialog. The framework then
 189 queries these data structures to get information like the printed page range
 190 (from the wxPrintDialogData) or the paper size and/or page orientation (from the
 191 wxPageSetupDialogData).
 192
 193
 194 \section{Printing under Unix (GTK+)}\label{unixprinting}
 195
 196 Printing under Unix has always been a cause of problems as Unix
 197 does not provide a standard way to display text and graphics
 198 on screen and print it to a printer using the same application
 199 programming interface - instead, displaying on screen is done
 200 via the X11 library while printing has to be done with using
 201 PostScript commands. This was particularly difficult to handle
 202 for the case of fonts with the result that only a selected
 203 number of application could offer WYSIWYG under Unix. Equally,
 204 wxWidgets offered its own printing implementation using PostScript
 205 which never really matched the screen display.
 206
 207 Starting with version 2.8.X, the GNOME project provides printing
 208 support through the libgnomeprint and libgnomeprintui libraries
 209 by which especially the font problem is mostly solved. Beginning
 210 with version 2.5.4, the GTK+ port of wxWidgets can make use of
 211 these libraries if wxWidgets is configured accordingly and if the
 212 libraries are present. You need to configure wxWidgets with the
 213 {\it configure --with-gnomeprint} switch and your application will
 214 then search for the GNOME print libraries at runtime. If they
 215 are found, printing will be done through these, otherwise the
 216 application will fall back to the old PostScript printing code.
 217 Note that the application will not require the GNOME print libraries
 218 to be installed in order to run (there will be no dependency on
 219 these libraries).
 220
 221 In version GTK+ 2.10, support for printing has been added to GTK+
 222 itself. Beginning with version wxWidgets 2.9.X, the GTK+ port of
 223 wxWidgets can make use of this feature
 224 if wxWidgets is configured accordingly and if the GTK+ version is >= 2.10.
 225 You need to configure wxWidgets with the {\it configure --with-gtkprint}
 226 switch and your application will then search for the GTK+ print support
 227 at runtime. If it is found, printing will be done through GTK+, otherwise the
 228 application will fall back to GNOME printing support if it is available or,
 229 if it isn't, to the old PostScript printing code.
 230 Note that the application will not require a GTK+ version >= 2.10
 231 to be installed in order to run (there will be no dependency on
 232 this version).
 233