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