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