interface/print.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        print.h
   3 // Purpose:     documentation for wxPreviewControlBar class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxPreviewControlBar
  11     @wxheader{print.h}
  12
  13     This is the default implementation of the preview control bar, a panel
  14     with buttons and a zoom control. You can derive a new class from this and
  15     override some or all member functions to change the behaviour and appearance;
  16     or you can leave it as it is.
  17
  18     @library{wxbase}
  19     @category{printing}
  20
  21     @seealso
  22     wxPreviewFrame, wxPreviewCanvas, wxPrintPreview
  23 */
  24 class wxPreviewControlBar : public wxPanel
  25 {
  26 public:
  27     /**
  28         Destructor.
  29     */
  30     ~wxPreviewControlBar();
  31
  32     /**
  33         Creates buttons, according to value of the button style flags.
  34     */
  35     void CreateButtons();
  36
  37     /**
  38         Gets the print preview object associated with the control bar.
  39     */
  40     wxPrintPreview * GetPrintPreview();
  41
  42     /**
  43         Gets the current zoom setting in percent.
  44     */
  45     int GetZoomControl();
  46
  47     /**
  48         Sets the zoom control.
  49     */
  50     void SetZoomControl(int percent);
  51
  52     /**
  53         Constructor.
  54
  55         The buttons parameter may be a combination of the following, using the bitwise
  56         'or' operator.
  57
  58         wxPREVIEW_PRINT
  59
  60
  61         Create a print button.
  62
  63         wxPREVIEW_NEXT
  64
  65
  66         Create a next page button.
  67
  68         wxPREVIEW_PREVIOUS
  69
  70
  71         Create a previous page button.
  72
  73         wxPREVIEW_ZOOM
  74
  75
  76         Create a zoom control.
  77
  78         wxPREVIEW_DEFAULT
  79
  80
  81         Equivalent to a combination of wxPREVIEW_PREVIOUS, wxPREVIEW_NEXT and
  82         wxPREVIEW_ZOOM.
  83     */
  84     wxPreviewControlBar(wxPrintPreview* preview, long buttons,
  85                         wxWindow* parent,
  86                         const wxPoint& pos = wxDefaultPosition,
  87                         const wxSize& size = wxDefaultSize,
  88                         long style = 0,
  89                         const wxString& name = "panel");
  90 };
  91
  92
  93 /**
  94     @class wxPreviewCanvas
  95     @wxheader{print.h}
  96
  97     A preview canvas is the default canvas used by the print preview
  98     system to display the preview.
  99
 100     @library{wxbase}
 101     @category{printing}
 102
 103     @seealso
 104     wxPreviewFrame, wxPreviewControlBar, wxPrintPreview
 105 */
 106 class wxPreviewCanvas : public wxScrolledWindow
 107 {
 108 public:
 109     /**
 110         Constructor.
 111     */
 112     wxPreviewCanvas(wxPrintPreview* preview, wxWindow* parent,
 113                     const wxPoint& pos = wxDefaultPosition,
 114                     const wxSize& size = wxDefaultSize,
 115                     long style = 0,
 116                     const wxString& name = "canvas");
 117
 118     /**
 119         Destructor.
 120     */
 121     ~wxPreviewCanvas();
 122
 123     /**
 124         Calls wxPrintPreview::PaintPage to refresh the canvas.
 125     */
 126     void OnPaint(wxPaintEvent& event);
 127 };
 128
 129
 130 /**
 131     @class wxPreviewFrame
 132     @wxheader{print.h}
 133
 134     This class provides the default method of managing the print preview interface.
 135     Member functions may be overridden to replace functionality, or the
 136     class may be used without derivation.
 137
 138     @library{wxbase}
 139     @category{printing}
 140
 141     @seealso
 142     wxPreviewCanvas, wxPreviewControlBar, wxPrintPreview
 143 */
 144 class wxPreviewFrame : public wxFrame
 145 {
 146 public:
 147     /**
 148         Constructor. Pass a print preview object plus other normal frame arguments.
 149         The print preview object will be destroyed by the frame when it closes.
 150     */
 151     wxPreviewFrame(wxPrintPreview* preview, wxWindow* parent,
 152                    const wxString& title,
 153                    const wxPoint& pos = wxDefaultPosition,
 154                    const wxSize& size size = wxDefaultSize,
 155                    long style = wxDEFAULT_FRAME_STYLE,
 156                    const wxString& name = "frame");
 157
 158     /**
 159         Destructor.
 160     */
 161     ~wxPreviewFrame();
 162
 163     /**
 164         Creates a wxPreviewCanvas. Override this function to allow
 165         a user-defined preview canvas object to be created.
 166     */
 167     void CreateCanvas();
 168
 169     /**
 170         Creates a wxPreviewControlBar. Override this function to allow
 171         a user-defined preview control bar object to be created.
 172     */
 173     void CreateControlBar();
 174
 175     /**
 176         Creates the preview canvas and control bar, and calls
 177         wxWindow::MakeModal(@true) to disable other top-level windows
 178         in the application.
 179
 180         This function should be called by the application prior to
 181         showing the frame.
 182     */
 183     void Initialize();
 184
 185     /**
 186         Enables the other frames in the application, and deletes the print preview
 187         object, implicitly deleting any printout objects associated with the print
 188         preview object.
 189     */
 190     void OnCloseWindow(wxCloseEvent& event);
 191 };
 192
 193
 194 /**
 195     @class wxPrintPreview
 196     @wxheader{print.h}
 197
 198     Objects of this class manage the print preview process. The object is passed
 199     a wxPrintout object, and the wxPrintPreview object itself is passed to
 200     a wxPreviewFrame object. Previewing is started by initializing and showing
 201     the preview frame. Unlike wxPrinter::Print, flow of control returns to the
 202     application
 203     immediately after the frame is shown.
 204
 205     @library{wxbase}
 206     @category{printing}
 207
 208     @seealso
 209     @ref overview_printingoverview "Printing framework overview", wxPrinterDC,
 210     wxPrintDialog, wxPrintout, wxPrinter, wxPreviewCanvas, wxPreviewControlBar, wxPreviewFrame.
 211 */
 212 class wxPrintPreview : public wxObject
 213 {
 214 public:
 215     /**
 216         Constructor. Pass a printout object, an optional printout object to be
 217         used for actual printing, and the address of an optional
 218         block of printer data, which will be copied to the print preview object's
 219         print data.
 220
 221         If @e printoutForPrinting is non-@NULL, a @b Print... button will be placed on
 222         the
 223         preview frame so that the user can print directly from the preview interface.
 224
 225         Do not explicitly delete the printout objects once this destructor has been
 226         called, since they will be deleted in the wxPrintPreview constructor.
 227         The same does not apply to the @e data argument.
 228
 229         Test the Ok member to check whether the wxPrintPreview object was created
 230         correctly.
 231         Ok could return @false if there was a problem initializing the printer device
 232         context
 233         (current printer not set, for example).
 234     */
 235     wxPrintPreview(wxPrintout* printout,
 236                    wxPrintout* printoutForPrinting,
 237                    wxPrintData* data=@NULL);
 238
 239     /**
 240         Destructor. Deletes both print preview objects, so do not destroy these objects
 241         in your application.
 242     */
 243     ~wxPrinter();
 244
 245     /**
 246         Gets the preview window used for displaying the print preview image.
 247     */
 248     wxPreviewCanvas* GetCanvas();
 249
 250     /**
 251         Gets the page currently being previewed.
 252     */
 253     int GetCurrentPage();
 254
 255     /**
 256         Gets the frame used for displaying the print preview canvas
 257         and control bar.
 258     */
 259     wxFrame * GetFrame();
 260
 261     /**
 262         Returns the maximum page number.
 263     */
 264     int GetMaxPage();
 265
 266     /**
 267         Returns the minimum page number.
 268     */
 269     int GetMinPage();
 270
 271     /**
 272         Gets the preview printout object associated with the wxPrintPreview object.
 273     */
 274     wxPrintout * GetPrintout();
 275
 276     /**
 277         Gets the printout object to be used for printing from within the preview
 278         interface,
 279         or @NULL if none exists.
 280     */
 281     wxPrintout * GetPrintoutForPrinting();
 282
 283     /**
 284         Returns @true if the wxPrintPreview is valid, @false otherwise. It could return
 285         @false if there was a
 286         problem initializing the printer device context (current printer not set, for
 287         example).
 288     */
 289 #define bool Ok()     /* implementation is private */
 290
 291     /**
 292         This refreshes the preview window with the preview image.
 293         It must be called from the preview window's OnPaint member.
 294
 295         The implementation simply blits the preview bitmap onto
 296         the canvas, creating a new preview bitmap if none exists.
 297     */
 298     bool PaintPage(wxPreviewCanvas * canvas, wxDC dc);
 299
 300     /**
 301         Invokes the print process using the second wxPrintout object
 302         supplied in the wxPrintPreview constructor.
 303         Will normally be called by the @b Print... panel item on the
 304         preview frame's control bar.
 305
 306         Returns @false in case of error -- call
 307         wxPrinter::GetLastError to get detailed
 308         information about the kind of the error.
 309     */
 310     bool Print(bool prompt);
 311
 312     /**
 313         Renders a page into a wxMemoryDC. Used internally by wxPrintPreview.
 314     */
 315     bool RenderPage(int pageNum);
 316
 317     /**
 318         Sets the window to be used for displaying the print preview image.
 319     */
 320     void SetCanvas(wxPreviewCanvas* window);
 321
 322     /**
 323         Sets the current page to be previewed.
 324     */
 325     void SetCurrentPage(int pageNum);
 326
 327     /**
 328         Sets the frame to be used for displaying the print preview canvas
 329         and control bar.
 330     */
 331     void SetFrame(wxFrame * frame);
 332
 333     /**
 334         Associates a printout object with the wxPrintPreview object.
 335     */
 336     void SetPrintout(wxPrintout * printout);
 337
 338     /**
 339         Sets the percentage preview zoom, and refreshes the preview canvas
 340         accordingly.
 341     */
 342     void SetZoom(int percent);
 343 };
 344
 345
 346 /**
 347     @class wxPrinter
 348     @wxheader{print.h}
 349
 350     This class represents the Windows or PostScript printer, and is the vehicle
 351     through
 352     which printing may be launched by an application. Printing can also
 353     be achieved through using of lower functions and classes, but
 354     this and associated classes provide a more convenient and general
 355     method of printing.
 356
 357     @library{wxbase}
 358     @category{printing}
 359
 360     @seealso
 361     @ref overview_printingoverview "Printing framework overview", wxPrinterDC,
 362     wxPrintDialog, wxPrintout, wxPrintPreview.
 363 */
 364 class wxPrinter : public wxObject
 365 {
 366 public:
 367     /**
 368         Constructor. Pass an optional pointer to a block of print
 369         dialog data, which will be copied to the printer object's local data.
 370
 371         @sa wxPrintDialogData, wxPrintData
 372     */
 373     wxPrinter(wxPrintDialogData* data = @NULL);
 374
 375     /**
 376         Creates the default printing abort window, with a cancel button.
 377     */
 378     void CreateAbortWindow(wxWindow* parent, wxPrintout* printout);
 379
 380     /**
 381         Returns @true if the user has aborted the print job.
 382     */
 383     bool GetAbort();
 384
 385     /**
 386         Return last error. Valid after calling Print(),
 387         PrintDialog() or
 388         wxPrintPreview::Print. These functions
 389         set last error to @b wxPRINTER_NO_ERROR if no error happened.
 390
 391         Returned value is one of the following:
 392
 393
 394         @b wxPRINTER_NO_ERROR
 395
 396
 397         No error happened.
 398
 399         @b wxPRINTER_CANCELLED
 400
 401
 402         The user cancelled printing.
 403
 404         @b wxPRINTER_ERROR
 405
 406
 407         There was an error during printing.
 408     */
 409     static wxPrinterError GetLastError();
 410
 411     /**
 412         Returns the @ref overview_wxprintdata "print data" associated with the printer
 413         object.
 414     */
 415     wxPrintDialogData GetPrintDialogData();
 416
 417     /**
 418         Starts the printing process. Provide a parent window, a user-defined wxPrintout
 419         object which controls
 420         the printing of a document, and whether the print dialog should be invoked
 421         first.
 422
 423         Print could return @false if there was a problem initializing the printer device
 424         context
 425         (current printer not set, for example) or the user cancelled printing. Call
 426         GetLastError() to get detailed
 427         information about the kind of the error.
 428     */
 429     bool Print(wxWindow * parent, wxPrintout * printout,
 430                bool prompt=@true);
 431
 432     /**
 433         Invokes the print dialog. If successful (the user did not press Cancel
 434         and no error occurred), a suitable device context will be returned
 435         (otherwise @NULL is returned -- call
 436         GetLastError() to get detailed
 437         information about the kind of the error).
 438
 439         The application must delete this device context to avoid a memory leak.
 440     */
 441     wxDC* PrintDialog(wxWindow * parent);
 442
 443     /**
 444         Default error-reporting function.
 445     */
 446     void ReportError(wxWindow * parent, wxPrintout * printout,
 447                      const wxString& message);
 448
 449     /**
 450         Invokes the print setup dialog. Note that the setup dialog is obsolete from
 451         Windows 95, though retained for backward compatibility.
 452     */
 453     bool Setup(wxWindow * parent);
 454 };
 455
 456
 457 /**
 458     @class wxPrintout
 459     @wxheader{print.h}
 460
 461     This class encapsulates the functionality of printing out an application
 462     document. A new class must be derived and members overridden to respond to calls
 463     such as OnPrintPage and HasPage and to render the print image onto an associated
 464     wxDC. Instances of this class are passed to wxPrinter::Print or
 465     to a wxPrintPreview object to initiate printing or previewing.
 466
 467     Your derived wxPrintout is responsible for drawing both the preview image and
 468     the printed page. If your windows' drawing routines accept an arbitrary DC as an
 469     argument, you can re-use those routines within your wxPrintout subclass to draw
 470     the printout image. You may also add additional drawing elements within your
 471     wxPrintout subclass, like headers, footers, and/or page numbers. However, the
 472     image on the printed page will often differ from the image drawn on the screen,
 473     as will the print preview image -- not just in the presence of headers and
 474     footers, but typically in scale. A high-resolution printer presents a much
 475     larger drawing surface (i.e., a higher-resolution DC); a zoomed-out preview
 476     image presents a much smaller drawing surface (lower-resolution DC). By using
 477     the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX() within your
 478     wxPrintout subclass to set the user scale and origin of the associated DC, you
 479     can easily use a single drawing routine to draw on your application's windows,
 480     to create the print preview image, and to create the printed paper image, and
 481     achieve a common appearance to the preview image and the printed page.
 482
 483     @library{wxbase}
 484     @category{printing}
 485
 486     @seealso
 487     @ref overview_printingoverview "Printing framework overview", wxPrinterDC,
 488     wxPrintDialog, wxPageSetupDialog, wxPrinter, wxPrintPreview
 489 */
 490 class wxPrintout : public wxObject
 491 {
 492 public:
 493     /**
 494         Constructor. Pass an optional title argument - the current filename would be a
 495         good idea. This will appear in the printing list
 496         (at least in MSW)
 497     */
 498     wxPrintout(const wxString& title = "Printout");
 499
 500     /**
 501         Destructor.
 502     */
 503     ~wxPrintout();
 504
 505     /**
 506         Set the user scale and device origin of the wxDC associated with this wxPrintout
 507         so that the given image size fits entirely within the page rectangle and the
 508         origin is at the top left corner of the page rectangle. On MSW and Mac, the page
 509         rectangle is the printable area of the page. On other platforms and PostScript
 510         printing, the page rectangle is the entire paper. Use this if you want your
 511         printed image as large as possible, but with the caveat that on some platforms,
 512         portions of the image might be cut off at the edges.
 513     */
 514     void FitThisSizeToPage(const wxSize& imageSize);
 515
 516     /**
 517         Set the user scale and device origin of the wxDC associated with this wxPrintout
 518         so that the given image size fits entirely within the page margins set in the
 519         given wxPageSetupDialogData object. This function provides the greatest
 520         consistency across all platforms because it does not depend on having access to
 521         the printable area of the paper. Note that on Mac, the native wxPageSetupDialog
 522         does not let you set the page margins; you'll have to provide your own
 523         mechanism,
 524         or you can use the Mac-only class wxMacPageMarginsDialog.
 525     */
 526     void FitThisSizeToPageMargins(const wxSize& imageSize,
 527                                   const wxPageSetupDialogData& pageSetupData);
 528
 529     /**
 530         Set the user scale and device origin of the wxDC associated with this wxPrintout
 531         so that the given image size fits entirely within the paper and the origin is at
 532         the top left corner of the paper. Note that with most printers, the region
 533         around the edges of the paper are not printable so that the edges of the image
 534         could be cut off. Use this if you're managing your own page margins.
 535     */
 536     void FitThisSizeToPaper(const wxSize& imageSize);
 537
 538     /**
 539         Returns the device context associated with the printout (given to the printout
 540         at start of
 541         printing or previewing). This will be a wxPrinterDC if printing under Windows
 542         or Mac,
 543         a wxPostScriptDC if printing on other platforms, and a wxMemoryDC if previewing.
 544     */
 545 #define wxDC * GetDC()     /* implementation is private */
 546
 547     /**
 548         Return the rectangle corresponding to the page margins specified by the given
 549         wxPageSetupDialogData object in the associated wxDC's logical coordinates for
 550         the
 551         current user scale and device origin. The page margins are specified
 552         with respect to the edges of the paper on all platforms.
 553     */
 554     wxRect GetLogicalPageMarginsRect(const wxPageSetupDialogData& pageSetupData);
 555
 556     /**
 557         Return the rectangle corresponding to the page in the associated wxDC's
 558         logical coordinates for the current user scale and device origin.
 559         On MSW and Mac, this will be the printable area of the paper. On other platforms
 560         and PostScript printing, this will be the full paper rectangle.
 561     */
 562     wxRect GetLogicalPageRect();
 563
 564     /**
 565         Return the rectangle corresponding to the paper in the associated wxDC's
 566         logical coordinates for the current user scale and device origin.
 567     */
 568     wxRect GetLogicalPaperRect();
 569
 570     /**
 571         Returns the number of pixels per logical inch of the printer device context.
 572         Dividing the printer PPI by the screen PPI can give a suitable scaling factor
 573         for drawing text onto the printer. Remember to multiply this by a scaling factor
 574         to take the preview DC size into account. Or you can just use the
 575         FitThisSizeToXXX() and MapScreenSizeToXXX routines below, which do most of the
 576         scaling calculations for you.
 577     */
 578     void GetPPIPrinter(int * w, int * h);
 579
 580     /**
 581         Returns the number of pixels per logical inch of the screen device context.
 582         Dividing the printer PPI by the screen PPI can give a suitable scaling factor
 583         for drawing text onto the printer. If you are doing your own scaling, remember
 584         to multiply this by a scaling factor to take the preview DC size into account.
 585     */
 586     void GetPPIScreen(int * w, int * h);
 587
 588     /**
 589         Called by the framework to obtain information from the application about minimum
 590         and maximum page values that the user can select, and the required page range to
 591         be printed. By default this returns 1, 32000 for the page minimum and maximum
 592         values, and 1, 1 for the required page range.
 593
 594         If @e minPage is zero, the page number controls in the print dialog will be
 595         disabled.
 596     */
 597     void GetPageInfo(int * minPage, int * maxPage, int * pageFrom,
 598                      int * pageTo);
 599
 600     /**
 601         Returns the size of the printer page in millimetres.
 602     */
 603     void GetPageSizeMM(int * w, int * h);
 604
 605     /**
 606         Returns the size of the printer page in pixels, called the page rectangle.
 607         The page rectangle has a top left corner at (0,0) and a bottom right corner at
 608         (w,h). These values may not be the same as the values returned from
 609         wxDC::GetSize; if the printout is being used for
 610         previewing, a memory device context is used, which uses a bitmap size reflecting
 611         the current preview zoom. The application must take this discrepancy into
 612         account if previewing is to be supported.
 613     */
 614     void GetPageSizePixels(int * w, int * h);
 615
 616     /**
 617         Returns the rectangle that corresponds to the entire paper in pixels, called the
 618         paper rectangle. This distinction between paper rectangle and page
 619         rectangle reflects the fact that most printers cannot print all the way to the
 620         edge of the paper. The page rectangle is a rectangle whose top left corner is at
 621         (0,0) and whose width and height are given by
 622         wxDC::GetPageSizePixels. On MSW and Mac,
 623         the page rectangle gives the printable area of the paper, while the paper
 624         rectangle represents the entire paper, including non-printable borders. Thus,
 625         the rectangle returned by GetPaperRectPixels will have a top left corner whose
 626         coordinates are small negative numbers and the bottom right corner will have
 627         values somewhat larger than the width and height given by
 628         wxDC::GetPageSizePixels. On other
 629         platforms and for PostScript printing, the paper is treated as if its entire
 630         area were printable, so this function will return the same rectangle as the page
 631         rectangle.
 632     */
 633     wxRect GetPaperRectPixels();
 634
 635     /**
 636         Returns the title of the printout
 637     */
 638     wxString GetTitle();
 639
 640     /**
 641         Should be overridden to return @true if the document has this page, or @false
 642         if not. Returning @false signifies the end of the document. By default,
 643         HasPage behaves as if the document has only one page.
 644     */
 645     bool HasPage(int pageNum);
 646
 647     /**
 648         Returns @true if the printout is currently being used for previewing.
 649     */
 650     bool IsPreview();
 651
 652     /**
 653         Set the user scale and device origin of the wxDC associated with this wxPrintout
 654         so that one screen pixel maps to one device pixel on the DC. That is, the user
 655         scale is set to (1,1) and the device origin is set to (0,0). Use this if you
 656         want to do your own scaling prior to calling wxDC drawing calls, for example, if
 657         your underlying model is floating-point and you want to achieve maximum drawing
 658         precision on high-resolution printers. (Note that while the underlying drawing
 659         model of Mac OS X is floating-point, wxWidgets's drawing model scales from
 660         integer
 661         coordinates.) You can use the GetLogicalXXXRect() routines below to obtain the
 662         paper rectangle, page rectangle, or page margins rectangle to perform your own
 663         scaling.
 664     */
 665     void MapScreenSizeToDevice();
 666
 667     /**
 668         This sets the user scale of the wxDC assocated with this wxPrintout to the same
 669         scale as MapScreenSizeToPaper() but sets
 670         the logical origin to the top left corner of the page rectangle.
 671     */
 672     void MapScreenSizeToPage();
 673
 674     /**
 675         This sets the user scale of the wxDC assocated with this wxPrintout to the same
 676         scale as
 677         MapScreenSizeToPageMargins() but
 678         sets the logical origin to the top left corner of the page margins specified by
 679         the given wxPageSetupDialogData object.
 680     */
 681     void MapScreenSizeToPageMargins(const wxPageSetupDialogData& pageSetupData);
 682
 683     /**
 684         Set the user scale and device origin of the wxDC associated with this wxPrintout
 685         so that the printed page matches the screen size as closely as possible
 686         and the logical origin is in the top left corner of the paper rectangle.
 687         That is,
 688         a 100-pixel object on screen should appear at the same size on the printed
 689         page. (It
 690         will, of course, be larger or smaller in the preview image, depending on the
 691         zoom
 692         factor.) Use this if you want WYSIWYG behavior, e.g., in a text editor.
 693     */
 694     void MapScreenSizeToPaper();
 695
 696     /**
 697         Shift the device origin by an amount specified in logical coordinates.
 698     */
 699     void OffsetLogicalOrigin(wxCoord xoff, wxCoord yoff);
 700
 701     /**
 702         Called by the framework at the start of document printing. Return @false from
 703         this function cancels the print job. OnBeginDocument is called once for every
 704         copy printed.
 705
 706         The base OnBeginDocument() @e must be called (and the return value
 707         checked) from within the overridden function, since it calls wxDC::StartDoc.
 708     */
 709     bool OnBeginDocument(int startPage, int endPage);
 710
 711     /**
 712         Called by the framework at the start of printing. OnBeginPrinting is called
 713         once for every
 714         print job (regardless of how many copies are being printed).
 715     */
 716     void OnBeginPrinting();
 717
 718     /**
 719         Called by the framework at the end of document printing. OnEndDocument
 720         is called once for every copy printed.
 721
 722         The base OnEndDocument() @e must be called
 723         from within the overridden function, since it calls wxDC::EndDoc.
 724     */
 725     void OnEndDocument();
 726
 727     /**
 728         Called by the framework at the end of printing. OnEndPrinting
 729         is called once for every print job (regardless of how many copies are being
 730         printed).
 731     */
 732     void OnEndPrinting();
 733
 734     /**
 735         Called once by the framework before any other demands are made of the
 736         wxPrintout object. This gives the object an opportunity to calculate the
 737         number of pages in the document, for example.
 738     */
 739     void OnPreparePrinting();
 740
 741     /**
 742         Called by the framework when a page should be printed. Returning @false cancels
 743         the print job. The application can use GetDC() to obtain a device
 744         context to draw on.
 745     */
 746     bool OnPrintPage(int pageNum);
 747
 748     /**
 749         Set the device origin of the associated wxDC so that the current logical point
 750         becomes the new logical origin.
 751     */
 752     void SetLogicalOrigin(wxCoord x, wxCoord y);
 753 };