docs/doxygen/overviews/printing.h

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