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         @beginWxPerlOnly
 645         In wxPerl this method takes no arguments and returns a
 646         2-element list (w, h).
 647         @endWxPerlOnly
 648     */
 649     void GetPPIPrinter(int* w, int* h) const;
 650
 651     /**
 652         Returns the number of pixels per logical inch of the screen device context.
 653
 654         Dividing the printer PPI by the screen PPI can give a suitable scaling factor
 655         for drawing text onto the printer.
 656
 657         If you are doing your own scaling, remember to multiply this by a scaling
 658         factor to take the preview DC size into account.
 659
 660         @beginWxPerlOnly
 661         In wxPerl this method takes no arguments and returns a
 662         2-element list (w, h).
 663         @endWxPerlOnly
 664     */
 665     void GetPPIScreen(int* w, int* h) const;
 666
 667     /**
 668         Called by the framework to obtain information from the application about minimum
 669         and maximum page values that the user can select, and the required page range to
 670         be printed.
 671
 672         By default this returns (1, 32000) for the page minimum and maximum values, and
 673         (1, 1) for the required page range.
 674
 675         @a minPage must be greater than zero and @a maxPage must be greater
 676         than @a minPage.
 677     */
 678     virtual void GetPageInfo(int* minPage, int* maxPage, int* pageFrom,
 679                              int* pageTo);
 680
 681     /**
 682         Returns the size of the printer page in millimetres.
 683
 684         @beginWxPerlOnly
 685         In wxPerl this method takes no arguments and returns a
 686         2-element list (w, h).
 687         @endWxPerlOnly
 688     */
 689     void GetPageSizeMM(int* w, int* h) const;
 690
 691     /**
 692         Returns the size of the printer page in pixels, called the page rectangle.
 693
 694         The page rectangle has a top left corner at (0,0) and a bottom right corner at
 695         (w,h). These values may not be the same as the values returned from
 696         wxDC::GetSize(); if the printout is being used for
 697         previewing, a memory device context is used, which uses a bitmap size reflecting
 698         the current preview zoom. The application must take this discrepancy into
 699         account if previewing is to be supported.
 700     */
 701     void GetPageSizePixels(int* w, int* h) const;
 702
 703     /**
 704         Returns the rectangle that corresponds to the entire paper in pixels, called the
 705         paper rectangle.
 706
 707         This distinction between paper rectangle and page rectangle reflects the fact that
 708         most printers cannot print all the way to the edge of the paper.
 709         The page rectangle is a rectangle whose top left corner is at (0,0) and whose width
 710         and height are given by wxDC::GetPageSizePixels().
 711
 712         On MSW and Mac, the page rectangle gives the printable area of the paper, while the
 713         paper rectangle represents the entire paper, including non-printable borders.
 714         Thus, the rectangle returned by wxDC::GetPaperRectPixels() will have a top left corner
 715         whose coordinates are small negative numbers and the bottom right corner will have
 716         values somewhat larger than the width and height given by wxDC::GetPageSizePixels().
 717
 718         On other platforms and for PostScript printing, the paper is treated as if its entire
 719         area were printable, so this function will return the same rectangle as the page
 720         rectangle.
 721     */
 722     wxRect GetPaperRectPixels() const;
 723
 724     /**
 725         Returns the title of the printout.
 726
 727         @todo the python note here was wrong
 728     */
 729     virtual wxString GetTitle() const;
 730
 731     /**
 732         Should be overridden to return @true if the document has this page, or @false
 733         if not.
 734
 735         Returning @false signifies the end of the document. By default,
 736         HasPage behaves as if the document has only one page.
 737     */
 738     virtual bool HasPage(int pageNum);
 739
 740     /**
 741         Returns @true if the printout is currently being used for previewing.
 742
 743         @see GetPreview()
 744     */
 745     virtual bool IsPreview() const;
 746
 747     /**
 748         Returns the associated preview object if any.
 749
 750         If this printout object is used for previewing, returns the associated
 751         wxPrintPreview. Otherwise returns @NULL.
 752
 753         The returned pointer is not owned by the printout and must not be
 754         deleted.
 755
 756         @see IsPreview()
 757
 758         @since 2.9.1.
 759      */
 760     wxPrintPreview *GetPreview() const;
 761
 762     /**
 763         Set the user scale and device origin of the wxDC associated with this wxPrintout
 764         so that one screen pixel maps to one device pixel on the DC.
 765         That is, the user scale is set to (1,1) and the device origin is set to (0,0).
 766
 767         Use this if you want to do your own scaling prior to calling wxDC drawing calls,
 768         for example, if your underlying model is floating-point and you want to achieve
 769         maximum drawing precision on high-resolution printers.
 770
 771         You can use the GetLogicalXXXRect() routines below to obtain the paper rectangle,
 772         page rectangle, or page margins rectangle to perform your own scaling.
 773
 774         @note
 775         While the underlying drawing model of Mac OS X is floating-point,
 776         wxWidgets's drawing model scales from integer coordinates.
 777     */
 778     void MapScreenSizeToDevice();
 779
 780     /**
 781         This sets the user scale of the wxDC associated with this wxPrintout to the same
 782         scale as MapScreenSizeToPaper() but sets the logical origin to the top left corner
 783         of the page rectangle.
 784     */
 785     void MapScreenSizeToPage();
 786
 787     /**
 788         This sets the user scale of the wxDC associated with this wxPrintout to the same
 789         scale as MapScreenSizeToPageMargins() but sets the logical origin to the top left
 790         corner of the page margins specified by the given wxPageSetupDialogData object.
 791     */
 792     void MapScreenSizeToPageMargins(const wxPageSetupDialogData& pageSetupData);
 793
 794     /**
 795         Set the user scale and device origin of the wxDC associated with this wxPrintout
 796         so that the printed page matches the screen size as closely as possible
 797         and the logical origin is in the top left corner of the paper rectangle.
 798
 799         That is, a 100-pixel object on screen should appear at the same size on the
 800         printed page.
 801         (It will, of course, be larger or smaller in the preview image, depending on the
 802         zoom factor.)
 803
 804         Use this if you want WYSIWYG behaviour, e.g., in a text editor.
 805     */
 806     void MapScreenSizeToPaper();
 807
 808     /**
 809         Shift the device origin by an amount specified in logical coordinates.
 810     */
 811     void OffsetLogicalOrigin(wxCoord xoff, wxCoord yoff);
 812
 813     /**
 814         Called by the framework at the start of document printing. Return @false from
 815         this function cancels the print job.
 816
 817         OnBeginDocument() is called once for every copy printed.
 818
 819         @remarks
 820         The base OnBeginDocument() must be called (and the return value
 821         checked) from within the overridden function, since it calls wxDC::StartDoc().
 822     */
 823     virtual bool OnBeginDocument(int startPage, int endPage);
 824
 825     /**
 826         Called by the framework at the start of printing.
 827
 828         OnBeginPrinting() is called once for every print job
 829         (regardless of how many copies are being printed).
 830     */
 831     virtual void OnBeginPrinting();
 832
 833     /**
 834         Called by the framework at the end of document printing.
 835
 836         OnEndDocument() is called once for every copy printed.
 837
 838         @remarks
 839         The base OnEndDocument() must be called from within the overridden function,
 840         since it calls wxDC::EndDoc().
 841     */
 842     virtual void OnEndDocument();
 843
 844     /**
 845         Called by the framework at the end of printing.
 846
 847         OnEndPrinting is called once for every print job
 848         (regardless of how many copies are being printed).
 849     */
 850     virtual void OnEndPrinting();
 851
 852     /**
 853         Called once by the framework before any other demands are made of the
 854         wxPrintout object.
 855
 856         This gives the object an opportunity to calculate the number of pages
 857         in the document, for example.
 858     */
 859     virtual void OnPreparePrinting();
 860
 861     /**
 862         Called by the framework when a page should be printed. Returning @false cancels
 863         the print job.
 864     */
 865     virtual bool OnPrintPage(int pageNum) = 0;
 866
 867     /**
 868         Set the device origin of the associated wxDC so that the current logical point
 869         becomes the new logical origin.
 870     */
 871     void SetLogicalOrigin(wxCoord x, wxCoord y);
 872 };
 873