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