]>
git.saurik.com Git - wxWidgets.git/blob - interface/print.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPreviewControlBar
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxPreviewControlBar
13 This is the default implementation of the preview control bar, a panel
14 with buttons and a zoom control.
16 You can derive a new class from this and override some or all member functions
17 to change the behaviour and appearance; or you can leave it as it is.
22 @see wxPreviewFrame, wxPreviewCanvas, wxPrintPreview
24 class wxPreviewControlBar
: public wxPanel
31 The @a buttons parameter may be a combination of the following, using the bitwise
35 @flag{wxPREVIEW_PRINT}
36 Create a print button.
38 Create a next page button.
39 @flag{wxPREVIEW_PREVIOUS}
40 Create a previous page button.
42 Create a zoom control.
43 @flag{wxPREVIEW_DEFAULT}
44 Equivalent to a combination of @c wxPREVIEW_PREVIOUS, @c wxPREVIEW_NEXT
45 and @c wxPREVIEW_ZOOM.
48 wxPreviewControlBar(wxPrintPreview
* preview
,
51 const wxPoint
& pos
= wxDefaultPosition
,
52 const wxSize
& size
= wxDefaultSize
,
54 const wxString
& name
= "panel");
59 ~wxPreviewControlBar();
62 Creates buttons, according to value of the button style flags.
69 Gets the print preview object associated with the control bar.
71 wxPrintPreview
* GetPrintPreview();
74 Gets the current zoom setting in percent.
79 Sets the zoom control.
81 void SetZoomControl(int percent
);
88 @class wxPreviewCanvas
91 A preview canvas is the default canvas used by the print preview
92 system to display the preview.
97 @see wxPreviewFrame, wxPreviewControlBar, wxPrintPreview
99 class wxPreviewCanvas
: public wxScrolledWindow
105 wxPreviewCanvas(wxPrintPreview
* preview
, wxWindow
* parent
,
106 const wxPoint
& pos
= wxDefaultPosition
,
107 const wxSize
& size
= wxDefaultSize
,
109 const wxString
& name
= "canvas");
117 Calls wxPrintPreview::PaintPage() to refresh the canvas.
119 void OnPaint(wxPaintEvent
& event
);
125 @class wxPreviewFrame
128 This class provides the default method of managing the print preview interface.
129 Member functions may be overridden to replace functionality, or the
130 class may be used without derivation.
135 @see wxPreviewCanvas, wxPreviewControlBar, wxPrintPreview
137 class wxPreviewFrame
: public wxFrame
143 Pass a print preview object plus other normal frame arguments.
144 The print preview object will be destroyed by the frame when it closes.
146 wxPreviewFrame(wxPrintPreview
* preview
, wxWindow
* parent
,
147 const wxString
& title
,
148 const wxPoint
& pos
= wxDefaultPosition
,
149 const wxSize
& size size
= wxDefaultSize
,
150 long style
= wxDEFAULT_FRAME_STYLE
,
151 const wxString
& name
= "frame");
159 Creates a wxPreviewCanvas.
161 Override this function to allow a user-defined preview canvas object
167 Creates a wxPreviewControlBar.
169 Override this function to allow a user-defined preview control bar object
172 void CreateControlBar();
175 Creates the preview canvas and control bar, and calls wxWindow::MakeModal(@true)
176 to disable other top-level windows in the application.
178 This function should be called by the application prior to showing the frame.
183 Enables the other frames in the application, and deletes the print preview
184 object, implicitly deleting any printout objects associated with the print
187 void OnCloseWindow(wxCloseEvent
& event
);
193 @class wxPrintPreview
196 Objects of this class manage the print preview process. The object is passed
197 a wxPrintout object, and the wxPrintPreview object itself is passed to
198 a wxPreviewFrame object. Previewing is started by initializing and showing
199 the preview frame. Unlike wxPrinter::Print(), flow of control returns to the
200 application immediately after the frame is shown.
205 @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPrintout, wxPrinter,
206 wxPreviewCanvas, wxPreviewControlBar, wxPreviewFrame
208 class wxPrintPreview
: public wxObject
214 Pass a printout object, an optional printout object to be used for actual
215 printing, and the address of an optional block of printer data, which will
216 be copied to the print preview object's print data.
218 If @a printoutForPrinting is non-@NULL, a @b "Print..." button will be placed on
219 the preview frame so that the user can print directly from the preview interface.
222 Do not explicitly delete the printout objects once this destructor has been
223 called, since they will be deleted in the wxPrintPreview constructor.
224 The same does not apply to the @a data argument.
226 Use IsOk() to check whether the wxPrintPreview object was created correctly.
228 wxPrintPreview(wxPrintout
* printout
,
229 wxPrintout
* printoutForPrinting
,
230 wxPrintData
* data
= NULL
);
235 Deletes both print preview objects, so do not destroy these objects
241 Gets the preview window used for displaying the print preview image.
243 wxPreviewCanvas
* GetCanvas();
246 Gets the page currently being previewed.
248 int GetCurrentPage();
251 Gets the frame used for displaying the print preview canvas
257 Returns the maximum page number.
262 Returns the minimum page number.
267 Gets the preview printout object associated with the wxPrintPreview object.
269 wxPrintout
* GetPrintout();
272 Gets the printout object to be used for printing from within the preview
274 or @NULL if none exists.
276 wxPrintout
* GetPrintoutForPrinting();
279 Returns @true if the wxPrintPreview is valid, @false otherwise.
281 It could return @false if there was a problem initializing the printer
282 device context (current printer not set, for example).
287 This refreshes the preview window with the preview image.
288 It must be called from the preview window's OnPaint member.
290 The implementation simply blits the preview bitmap onto
291 the canvas, creating a new preview bitmap if none exists.
293 bool PaintPage(wxPreviewCanvas
* canvas
, wxDC dc
);
296 Invokes the print process using the second wxPrintout object
297 supplied in the wxPrintPreview constructor.
298 Will normally be called by the @b Print... panel item on the
299 preview frame's control bar.
301 Returns @false in case of error -- call wxPrinter::GetLastError()
302 to get detailed information about the kind of the error.
304 bool Print(bool prompt
);
307 Renders a page into a wxMemoryDC. Used internally by wxPrintPreview.
309 bool RenderPage(int pageNum
);
312 Sets the window to be used for displaying the print preview image.
314 void SetCanvas(wxPreviewCanvas
* window
);
317 Sets the current page to be previewed.
319 void SetCurrentPage(int pageNum
);
322 Sets the frame to be used for displaying the print preview canvas
325 void SetFrame(wxFrame
* frame
);
328 Associates a printout object with the wxPrintPreview object.
330 void SetPrintout(wxPrintout
* printout
);
333 Sets the percentage preview zoom, and refreshes the preview canvas accordingly.
335 void SetZoom(int percent
);
344 This class represents the Windows or PostScript printer, and is the vehicle
345 through which printing may be launched by an application.
347 Printing can also be achieved through using of lower functions and classes,
348 but this and associated classes provide a more convenient and general method
354 @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPrintout, wxPrintPreview
356 class wxPrinter
: public wxObject
362 Pass an optional pointer to a block of print dialog data, which will be
363 copied to the printer object's local data.
365 @see wxPrintDialogData, wxPrintData
367 wxPrinter(wxPrintDialogData
* data
= NULL
);
370 Creates the default printing abort window, with a cancel button.
372 void CreateAbortWindow(wxWindow
* parent
, wxPrintout
* printout
);
375 Returns @true if the user has aborted the print job.
380 Return last error. Valid after calling Print(), PrintDialog() or
381 wxPrintPreview::Print().
383 These functions set last error to @c wxPRINTER_NO_ERROR if no error happened.
385 Returned value is one of the following:
388 @row2col{wxPRINTER_NO_ERROR, No error happened.}
389 @row2col{wxPRINTER_CANCELLED, The user cancelled printing.}
390 @row2col{wxPRINTER_ERROR, There was an error during printing.}
393 static wxPrinterError
GetLastError();
396 Returns the @ref overview_printing_printdata "print data" associated with
399 wxPrintDialogData
& GetPrintDialogData();
402 Starts the printing process. Provide a parent window, a user-defined wxPrintout
403 object which controls the printing of a document, and whether the print dialog
404 should be invoked first.
406 Print() could return @false if there was a problem initializing the printer device
407 context (current printer not set, for example) or the user cancelled printing.
408 Call GetLastError() to get detailed information about the kind of the error.
410 bool Print(wxWindow
* parent
, wxPrintout
* printout
,
414 Invokes the print dialog.
416 If successful (the user did not press Cancel and no error occurred),
417 a suitable device context will be returned; otherwise @NULL is returned;
418 call GetLastError() to get detailed information about the kind of the error.
421 The application must delete this device context to avoid a memory leak.
423 wxDC
* PrintDialog(wxWindow
* parent
);
426 Default error-reporting function.
428 void ReportError(wxWindow
* parent
, wxPrintout
* printout
,
429 const wxString
& message
);
432 Invokes the print setup dialog.
435 The setup dialog is obsolete from Windows 95, though retained
436 for backward compatibility.
438 bool Setup(wxWindow
* parent
);
447 This class encapsulates the functionality of printing out an application document.
449 A new class must be derived and members overridden to respond to calls such as
450 OnPrintPage() and HasPage() and to render the print image onto an associated wxDC.
451 Instances of this class are passed to wxPrinter::Print() or
452 to a wxPrintPreview object to initiate printing or previewing.
454 Your derived wxPrintout is responsible for drawing both the preview image and
455 the printed page. If your windows' drawing routines accept an arbitrary DC as an
456 argument, you can re-use those routines within your wxPrintout subclass to draw
457 the printout image. You may also add additional drawing elements within your
458 wxPrintout subclass, like headers, footers, and/or page numbers. However, the
459 image on the printed page will often differ from the image drawn on the screen,
460 as will the print preview image -- not just in the presence of headers and
461 footers, but typically in scale. A high-resolution printer presents a much
462 larger drawing surface (i.e., a higher-resolution DC); a zoomed-out preview
463 image presents a much smaller drawing surface (lower-resolution DC). By using
464 the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX() within your
465 wxPrintout subclass to set the user scale and origin of the associated DC, you
466 can easily use a single drawing routine to draw on your application's windows,
467 to create the print preview image, and to create the printed paper image, and
468 achieve a common appearance to the preview image and the printed page.
473 @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPageSetupDialog,
474 wxPrinter, wxPrintPreview
476 class wxPrintout
: public wxObject
482 Pass an optional title argument - the current filename would be a
483 good idea. This will appear in the printing list (at least in MSW)
485 wxPrintout(const wxString
& title
= "Printout");
493 Set the user scale and device origin of the wxDC associated with this wxPrintout
494 so that the given image size fits entirely within the page rectangle and the
495 origin is at the top left corner of the page rectangle.
497 On MSW and Mac, the page rectangle is the printable area of the page.
498 On other platforms and PostScript printing, the page rectangle is the entire paper.
500 Use this if you want your printed image as large as possible, but with the caveat
501 that on some platforms, portions of the image might be cut off at the edges.
503 void FitThisSizeToPage(const wxSize
& imageSize
);
506 Set the user scale and device origin of the wxDC associated with this wxPrintout
507 so that the given image size fits entirely within the page margins set in the
508 given wxPageSetupDialogData object.
510 This function provides the greatest consistency across all platforms because it
511 does not depend on having access to the printable area of the paper.
514 On Mac, the native wxPageSetupDialog does not let you set the page margins;
515 you'll have to provide your own mechanism, or you can use the Mac-only class
516 wxMacPageMarginsDialog.
518 void FitThisSizeToPageMargins(const wxSize
& imageSize
,
519 const wxPageSetupDialogData
& pageSetupData
);
522 Set the user scale and device origin of the wxDC associated with this wxPrintout
523 so that the given image size fits entirely within the paper and the origin is at
524 the top left corner of the paper.
526 Use this if you're managing your own page margins.
529 With most printers, the region around the edges of the paper are not
530 printable so that the edges of the image could be cut off.
533 void FitThisSizeToPaper(const wxSize
& imageSize
);
536 Returns the device context associated with the printout (given to the printout
537 at start of printing or previewing).
539 The application can use GetDC() to obtain a device context to draw on.
541 This will be a wxPrinterDC if printing under Windows or Mac, a wxPostScriptDC
542 if printing on other platforms, and a wxMemoryDC if previewing.
547 Return the rectangle corresponding to the page margins specified by the given
548 wxPageSetupDialogData object in the associated wxDC's logical coordinates for
549 the current user scale and device origin.
551 The page margins are specified with respect to the edges of the paper on all
554 wxRect
GetLogicalPageMarginsRect(const wxPageSetupDialogData
& pageSetupData
);
557 Return the rectangle corresponding to the page in the associated wxDC 's
558 logical coordinates for the current user scale and device origin.
560 On MSW and Mac, this will be the printable area of the paper.
561 On other platforms and PostScript printing, this will be the full paper
564 wxRect
GetLogicalPageRect();
567 Return the rectangle corresponding to the paper in the associated wxDC 's
568 logical coordinates for the current user scale and device origin.
570 wxRect
GetLogicalPaperRect();
573 Returns the number of pixels per logical inch of the printer device context.
575 Dividing the printer PPI by the screen PPI can give a suitable scaling factor
576 for drawing text onto the printer.
578 Remember to multiply this by a scaling factor to take the preview DC size into
580 Or you can just use the FitThisSizeToXXX() and MapScreenSizeToXXX routines below,
581 which do most of the scaling calculations for you.
584 This method returns the output-only parameters as a tuple.
587 void GetPPIPrinter(int* w
, int* h
);
590 Returns the number of pixels per logical inch of the screen device context.
592 Dividing the printer PPI by the screen PPI can give a suitable scaling factor
593 for drawing text onto the printer.
595 If you are doing your own scaling, remember to multiply this by a scaling
596 factor to take the preview DC size into account.
599 This method returns the output-only parameters as a tuple.
602 void GetPPIScreen(int* w
, int* h
);
605 Called by the framework to obtain information from the application about minimum
606 and maximum page values that the user can select, and the required page range to
609 By default this returns (1, 32000) for the page minimum and maximum values, and
610 (1, 1) for the required page range.
612 @a minPage must be greater than zero and @a maxPage must be greater
616 When this method is implemented in a derived Python class, it should be designed
617 to take no parameters (other than the self reference) and to return a tuple of
621 void GetPageInfo(int* minPage
, int* maxPage
, int* pageFrom
,
625 Returns the size of the printer page in millimetres.
628 This method returns the output-only parameters as a tuple.
631 void GetPageSizeMM(int* w
, int* h
);
634 Returns the size of the printer page in pixels, called the page rectangle.
636 The page rectangle has a top left corner at (0,0) and a bottom right corner at
637 (w,h). These values may not be the same as the values returned from
638 wxDC::GetSize(); if the printout is being used for
639 previewing, a memory device context is used, which uses a bitmap size reflecting
640 the current preview zoom. The application must take this discrepancy into
641 account if previewing is to be supported.
644 This method returns the output-only parameters as a tuple.
647 void GetPageSizePixels(int* w
, int* h
);
650 Returns the rectangle that corresponds to the entire paper in pixels, called the
653 This distinction between paper rectangle and page rectangle reflects the fact that
654 most printers cannot print all the way to the edge of the paper.
655 The page rectangle is a rectangle whose top left corner is at (0,0) and whose width
656 and height are given by wxDC::GetPageSizePixels().
658 On MSW and Mac, the page rectangle gives the printable area of the paper, while the
659 paper rectangle represents the entire paper, including non-printable borders.
660 Thus, the rectangle returned by wxDC::GetPaperRectPixels() will have a top left corner
661 whose coordinates are small negative numbers and the bottom right corner will have
662 values somewhat larger than the width and height given by wxDC::GetPageSizePixels().
664 On other platforms and for PostScript printing, the paper is treated as if its entire
665 area were printable, so this function will return the same rectangle as the page
668 wxRect
GetPaperRectPixels();
671 Returns the title of the printout.
673 @todo the python note here was wrong
678 Should be overridden to return @true if the document has this page, or @false
681 Returning @false signifies the end of the document. By default,
682 HasPage behaves as if the document has only one page.
684 bool HasPage(int pageNum
);
687 Returns @true if the printout is currently being used for previewing.
692 Set the user scale and device origin of the wxDC associated with this wxPrintout
693 so that one screen pixel maps to one device pixel on the DC.
694 That is, the user scale is set to (1,1) and the device origin is set to (0,0).
696 Use this if you want to do your own scaling prior to calling wxDC drawing calls,
697 for example, if your underlying model is floating-point and you want to achieve
698 maximum drawing precision on high-resolution printers.
700 You can use the GetLogicalXXXRect() routines below to obtain the paper rectangle,
701 page rectangle, or page margins rectangle to perform your own scaling.
704 While the underlying drawing model of Mac OS X is floating-point,
705 wxWidgets's drawing model scales from integer coordinates.
707 void MapScreenSizeToDevice();
710 This sets the user scale of the wxDC assocated with this wxPrintout to the same
711 scale as MapScreenSizeToPaper() but sets the logical origin to the top left corner
712 of the page rectangle.
714 void MapScreenSizeToPage();
717 This sets the user scale of the wxDC assocated with this wxPrintout to the same
718 scale as MapScreenSizeToPageMargins() but sets the logical origin to the top left
719 corner of the page margins specified by the given wxPageSetupDialogData object.
721 void MapScreenSizeToPageMargins(const wxPageSetupDialogData
& pageSetupData
);
724 Set the user scale and device origin of the wxDC associated with this wxPrintout
725 so that the printed page matches the screen size as closely as possible
726 and the logical origin is in the top left corner of the paper rectangle.
728 That is, a 100-pixel object on screen should appear at the same size on the
730 (It will, of course, be larger or smaller in the preview image, depending on the
733 Use this if you want WYSIWYG behavior, e.g., in a text editor.
735 void MapScreenSizeToPaper();
738 Shift the device origin by an amount specified in logical coordinates.
740 void OffsetLogicalOrigin(wxCoord xoff
, wxCoord yoff
);
743 Called by the framework at the start of document printing. Return @false from
744 this function cancels the print job.
746 OnBeginDocument() is called once for every copy printed.
749 The base OnBeginDocument() must be called (and the return value
750 checked) from within the overridden function, since it calls wxDC::StartDoc().
753 If this method is overridden in a Python class then the base class version can
754 be called by using the method <tt>base_OnBeginDocument(startPage, endPage)</tt>.
757 bool OnBeginDocument(int startPage
, int endPage
);
760 Called by the framework at the start of printing.
762 OnBeginPrinting() is called once for every print job
763 (regardless of how many copies are being printed).
765 void OnBeginPrinting();
768 Called by the framework at the end of document printing.
770 OnEndDocument() is called once for every copy printed.
773 The base OnEndDocument() must be called from within the overridden function,
774 since it calls wxDC::EndDoc().
776 void OnEndDocument();
779 Called by the framework at the end of printing.
781 OnEndPrinting is called once for every print job
782 (regardless of how many copies are being printed).
784 void OnEndPrinting();
787 Called once by the framework before any other demands are made of the
790 This gives the object an opportunity to calculate the number of pages
791 in the document, for example.
793 void OnPreparePrinting();
796 Called by the framework when a page should be printed. Returning @false cancels
799 bool OnPrintPage(int pageNum
);
802 Set the device origin of the associated wxDC so that the current logical point
803 becomes the new logical origin.
805 void SetLogicalOrigin(wxCoord x
, wxCoord y
);