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