docs/doxygen/overviews/printing.h

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