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