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