interface/wx/print.h

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