docs/doxygen/overviews/printing.h

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