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