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