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