interface/print.h

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