1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPreviewControlBar
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxPreviewControlBar
12 This is the default implementation of the preview control bar, a panel
13 with buttons and a zoom control.
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.
21 @see wxPreviewFrame, wxPreviewCanvas, wxPrintPreview
23 class wxPreviewControlBar
: public wxPanel
30 The @a buttons parameter may be a combination of the following, using the bitwise
34 @flag{wxPREVIEW_PRINT}
35 Create a print button.
37 Create a next page button.
38 @flag{wxPREVIEW_PREVIOUS}
39 Create a previous page button.
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.
47 wxPreviewControlBar(wxPrintPreview
* preview
,
50 const wxPoint
& pos
= wxDefaultPosition
,
51 const wxSize
& size
= wxDefaultSize
,
53 const wxString
& name
= "panel");
58 virtual ~wxPreviewControlBar();
61 Creates buttons, according to value of the button style flags.
65 virtual void CreateButtons();
68 Gets the print preview object associated with the control bar.
70 virtual wxPrintPreviewBase
* GetPrintPreview() const;
73 Gets the current zoom setting in percent.
75 virtual int GetZoomControl();
78 Sets the zoom control.
80 virtual void SetZoomControl(int percent
);
87 @class wxPreviewCanvas
89 A preview canvas is the default canvas used by the print preview
90 system to display the preview.
95 @see wxPreviewFrame, wxPreviewControlBar, wxPrintPreview
97 class wxPreviewCanvas
: public wxScrolledWindow
103 wxPreviewCanvas(wxPrintPreview
* preview
, wxWindow
* parent
,
104 const wxPoint
& pos
= wxDefaultPosition
,
105 const wxSize
& size
= wxDefaultSize
,
107 const wxString
& name
= "canvas");
112 virtual ~wxPreviewCanvas();
115 Calls wxPrintPreview::PaintPage() to refresh the canvas.
117 void OnPaint(wxPaintEvent
& event
);
121 Preview frame modality kind.
123 The elements of this enum can be used with wxPreviewFrame::Initialize() to
124 indicate how should the preview frame be shown.
128 enum wxPreviewFrameModalityKind
131 Disable all the other top level windows while the preview frame is shown.
133 This is the default behaviour.
135 wxPreviewFrame_AppModal
,
138 Disable only the parent window while the preview frame is shown.
140 wxPreviewFrame_WindowModal
,
143 Show the preview frame non-modally and don't disable any other windows.
145 wxPreviewFrame_NonModal
149 @class wxPreviewFrame
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.
158 @see wxPreviewCanvas, wxPreviewControlBar, wxPrintPreview
160 class wxPreviewFrame
: public wxFrame
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.
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
);
179 virtual ~wxPreviewFrame();
182 Creates a wxPreviewCanvas.
184 Override this function to allow a user-defined preview canvas object
187 virtual void CreateCanvas();
190 Creates a wxPreviewControlBar.
192 Override this function to allow a user-defined preview control bar object
195 virtual void CreateControlBar();
198 Initializes the frame elements and prepares for showing it.
200 Calling this method is equivalent to calling InitializeWithModality()
201 with wxPreviewFrame_AppModal argument, please see its documentation for
204 Please notice that this function is virtual mostly for backwards
205 compatibility only, there is no real need to override it as it's never
206 called by wxWidgets itself.
208 virtual void Initialize();
211 Initializes the frame elements and prepares for showing it with the
214 This method creates the frame elements by calling CreateCanvas() and
215 CreateControlBar() methods (which may be overridden to customize them)
216 and prepares to show the frame according to the value of @a kind
218 - If it is wxPreviewFrame_AppModal, all the other application
219 windows will be disabled when this frame is shown. This is the same
220 behaviour as that of simple Initialize().
221 - If it is wxPreviewFrame_WindowModal, only the parent window of
222 the preview frame will be disabled when it is shown.
223 - And if it is wxPreviewFrame_NonModal, no windows at all will be
224 disabled while the preview is shown.
226 Notice that this function (or Initialize()) must be called by the
227 application prior to showing the frame but you still must call @c
228 Show(true) to actually show it afterwards.
231 The modality kind of preview frame.
235 virtual void InitializeWithModality(wxPreviewFrameModalityKind kind
);
238 Enables any disabled frames in the application, and deletes the print preview
239 object, implicitly deleting any printout objects associated with the print
242 void OnCloseWindow(wxCloseEvent
& event
);
248 @class wxPrintPreview
250 Objects of this class manage the print preview process. The object is passed
251 a wxPrintout object, and the wxPrintPreview object itself is passed to
252 a wxPreviewFrame object. Previewing is started by initializing and showing
253 the preview frame. Unlike wxPrinter::Print(), flow of control returns to the
254 application immediately after the frame is shown.
257 The preview shown is only exact on Windows. On other platforms, the wxDC
258 used for preview is different from what is used for printing and the
259 results may be significantly different, depending on how is the output
260 created. In particular, printing code relying on wxDC::GetTextExtent()
261 heavily (for example, wxHtmlEasyPrinting and other wxHTML classes do) is
262 affected. It is recommended to use native preview functionality on
263 platforms that offer it (OS X, GTK+).
268 @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPrintout, wxPrinter,
269 wxPreviewCanvas, wxPreviewControlBar, wxPreviewFrame
271 class wxPrintPreview
: public wxObject
277 Pass a printout object, an optional printout object to be used for actual
278 printing, and the address of an optional block of printer data, which will
279 be copied to the print preview object's print data.
281 If @a printoutForPrinting is non-@NULL, a @b "Print..." button will be placed on
282 the preview frame so that the user can print directly from the preview interface.
285 Do not explicitly delete the printout objects once this destructor has been
286 called, since they will be deleted in the wxPrintPreview constructor.
287 The same does not apply to the @a data argument.
289 Use IsOk() to check whether the wxPrintPreview object was created correctly.
291 wxPrintPreview(wxPrintout
* printout
,
292 wxPrintout
* printoutForPrinting
= NULL
,
293 wxPrintDialogData
* data
= NULL
);
298 Deletes both print preview objects, so do not destroy these objects
304 Gets the preview window used for displaying the print preview image.
306 virtual wxPreviewCanvas
* GetCanvas() const;
309 Gets the page currently being previewed.
311 virtual int GetCurrentPage() const;
314 Gets the frame used for displaying the print preview canvas
317 virtual wxFrame
* GetFrame() const;
320 Returns the maximum page number.
322 virtual int GetMaxPage() const;
325 Returns the minimum page number.
327 virtual int GetMinPage() const;
330 Gets the preview printout object associated with the wxPrintPreview object.
332 virtual wxPrintout
* GetPrintout() const;
335 Gets the printout object to be used for printing from within the preview
337 or @NULL if none exists.
339 virtual wxPrintout
* GetPrintoutForPrinting() const;
342 Returns @true if the wxPrintPreview is valid, @false otherwise.
344 It could return @false if there was a problem initializing the printer
345 device context (current printer not set, for example).
347 virtual bool IsOk() const;
350 This refreshes the preview window with the preview image.
351 It must be called from the preview window's OnPaint member.
353 The implementation simply blits the preview bitmap onto
354 the canvas, creating a new preview bitmap if none exists.
356 virtual bool PaintPage(wxPreviewCanvas
* canvas
, wxDC
& dc
);
359 Invokes the print process using the second wxPrintout object
360 supplied in the wxPrintPreview constructor.
361 Will normally be called by the @b Print... panel item on the
362 preview frame's control bar.
364 Returns @false in case of error -- call wxPrinter::GetLastError()
365 to get detailed information about the kind of the error.
367 virtual bool Print(bool prompt
);
370 Renders a page into a wxMemoryDC. Used internally by wxPrintPreview.
372 virtual bool RenderPage(int pageNum
);
375 Sets the window to be used for displaying the print preview image.
377 virtual void SetCanvas(wxPreviewCanvas
* window
);
380 Sets the current page to be previewed.
382 virtual bool SetCurrentPage(int pageNum
);
385 Sets the frame to be used for displaying the print preview canvas
388 virtual void SetFrame(wxFrame
* frame
);
391 Associates a printout object with the wxPrintPreview object.
393 virtual void SetPrintout(wxPrintout
* printout
);
396 Sets the percentage preview zoom, and refreshes the preview canvas accordingly.
398 virtual void SetZoom(int percent
);
406 This class represents the Windows or PostScript printer, and is the vehicle
407 through which printing may be launched by an application.
409 Printing can also be achieved through using of lower functions and classes,
410 but this and associated classes provide a more convenient and general method
416 @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPrintout, wxPrintPreview
418 class wxPrinter
: public wxObject
424 Pass an optional pointer to a block of print dialog data, which will be
425 copied to the printer object's local data.
427 @see wxPrintDialogData, wxPrintData
429 wxPrinter(wxPrintDialogData
* data
= NULL
);
432 Creates the default printing abort window, with a cancel button.
434 virtual wxWindow
* CreateAbortWindow(wxWindow
* parent
, wxPrintout
* printout
);
437 Returns @true if the user has aborted the print job.
439 bool GetAbort() const;
442 Return last error. Valid after calling Print(), PrintDialog() or
443 wxPrintPreview::Print().
445 These functions set last error to @c wxPRINTER_NO_ERROR if no error happened.
447 Returned value is one of the following:
450 @row2col{wxPRINTER_NO_ERROR, No error happened.}
451 @row2col{wxPRINTER_CANCELLED, The user cancelled printing.}
452 @row2col{wxPRINTER_ERROR, There was an error during printing.}
455 static wxPrinterError
GetLastError();
458 Returns the @ref overview_printing_printdata "print data" associated with
461 virtual wxPrintDialogData
& GetPrintDialogData() const;
464 Starts the printing process. Provide a parent window, a user-defined wxPrintout
465 object which controls the printing of a document, and whether the print dialog
466 should be invoked first.
468 Print() could return @false if there was a problem initializing the printer device
469 context (current printer not set, for example) or the user cancelled printing.
470 Call GetLastError() to get detailed information about the kind of the error.
472 virtual bool Print(wxWindow
* parent
, wxPrintout
* printout
,
476 Invokes the print dialog.
478 If successful (the user did not press Cancel and no error occurred),
479 a suitable device context will be returned; otherwise @NULL is returned;
480 call GetLastError() to get detailed information about the kind of the error.
483 The application must delete this device context to avoid a memory leak.
485 virtual wxDC
* PrintDialog(wxWindow
* parent
);
488 Default error-reporting function.
490 virtual void ReportError(wxWindow
* parent
, wxPrintout
* printout
,
491 const wxString
& message
);
494 Invokes the print setup dialog.
497 The setup dialog is obsolete from Windows 95, though retained
498 for backward compatibility.
500 virtual bool Setup(wxWindow
* parent
);
508 This class encapsulates the functionality of printing out an application document.
510 A new class must be derived and members overridden to respond to calls such as
511 OnPrintPage() and HasPage() and to render the print image onto an associated wxDC.
512 Instances of this class are passed to wxPrinter::Print() or
513 to a wxPrintPreview object to initiate printing or previewing.
515 Your derived wxPrintout is responsible for drawing both the preview image and
516 the printed page. If your windows' drawing routines accept an arbitrary DC as an
517 argument, you can re-use those routines within your wxPrintout subclass to draw
518 the printout image. You may also add additional drawing elements within your
519 wxPrintout subclass, like headers, footers, and/or page numbers. However, the
520 image on the printed page will often differ from the image drawn on the screen,
521 as will the print preview image -- not just in the presence of headers and
522 footers, but typically in scale. A high-resolution printer presents a much
523 larger drawing surface (i.e., a higher-resolution DC); a zoomed-out preview
524 image presents a much smaller drawing surface (lower-resolution DC). By using
525 the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX() within your
526 wxPrintout subclass to set the user scale and origin of the associated DC, you
527 can easily use a single drawing routine to draw on your application's windows,
528 to create the print preview image, and to create the printed paper image, and
529 achieve a common appearance to the preview image and the printed page.
534 @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPageSetupDialog,
535 wxPrinter, wxPrintPreview
537 class wxPrintout
: public wxObject
543 Pass an optional title argument - the current filename would be a
544 good idea. This will appear in the printing list (at least in MSW)
546 wxPrintout(const wxString
& title
= "Printout");
551 virtual ~wxPrintout();
554 Set the user scale and device origin of the wxDC associated with this wxPrintout
555 so that the given image size fits entirely within the page rectangle and the
556 origin is at the top left corner of the page rectangle.
558 On MSW and Mac, the page rectangle is the printable area of the page.
559 On other platforms and PostScript printing, the page rectangle is the entire paper.
561 Use this if you want your printed image as large as possible, but with the caveat
562 that on some platforms, portions of the image might be cut off at the edges.
564 void FitThisSizeToPage(const wxSize
& imageSize
);
567 Set the user scale and device origin of the wxDC associated with this wxPrintout
568 so that the given image size fits entirely within the page margins set in the
569 given wxPageSetupDialogData object.
571 This function provides the greatest consistency across all platforms because it
572 does not depend on having access to the printable area of the paper.
575 On Mac, the native wxPageSetupDialog does not let you set the page margins;
576 you'll have to provide your own mechanism, or you can use the Mac-only class
577 wxMacPageMarginsDialog.
579 void FitThisSizeToPageMargins(const wxSize
& imageSize
,
580 const wxPageSetupDialogData
& pageSetupData
);
583 Set the user scale and device origin of the wxDC associated with this wxPrintout
584 so that the given image size fits entirely within the paper and the origin is at
585 the top left corner of the paper.
587 Use this if you're managing your own page margins.
590 With most printers, the region around the edges of the paper are not
591 printable so that the edges of the image could be cut off.
594 void FitThisSizeToPaper(const wxSize
& imageSize
);
597 Returns the device context associated with the printout (given to the printout
598 at start of printing or previewing).
600 The application can use GetDC() to obtain a device context to draw on.
602 This will be a wxPrinterDC if printing under Windows or Mac, a wxPostScriptDC
603 if printing on other platforms, and a wxMemoryDC if previewing.
608 Return the rectangle corresponding to the page margins specified by the given
609 wxPageSetupDialogData object in the associated wxDC's logical coordinates for
610 the current user scale and device origin.
612 The page margins are specified with respect to the edges of the paper on all
615 wxRect
GetLogicalPageMarginsRect(const wxPageSetupDialogData
& pageSetupData
) const;
618 Return the rectangle corresponding to the page in the associated wxDC 's
619 logical coordinates for the current user scale and device origin.
621 On MSW and Mac, this will be the printable area of the paper.
622 On other platforms and PostScript printing, this will be the full paper
625 wxRect
GetLogicalPageRect() const;
628 Return the rectangle corresponding to the paper in the associated wxDC 's
629 logical coordinates for the current user scale and device origin.
631 wxRect
GetLogicalPaperRect() const;
634 Returns the number of pixels per logical inch of the printer device context.
636 Dividing the printer PPI by the screen PPI can give a suitable scaling factor
637 for drawing text onto the printer.
639 Remember to multiply this by a scaling factor to take the preview DC size into
641 Or you can just use the FitThisSizeToXXX() and MapScreenSizeToXXX routines below,
642 which do most of the scaling calculations for you.
645 In wxPerl this method takes no arguments and returns a
646 2-element list (w, h).
649 void GetPPIPrinter(int* w
, int* h
) const;
652 Returns the number of pixels per logical inch of the screen device context.
654 Dividing the printer PPI by the screen PPI can give a suitable scaling factor
655 for drawing text onto the printer.
657 If you are doing your own scaling, remember to multiply this by a scaling
658 factor to take the preview DC size into account.
661 In wxPerl this method takes no arguments and returns a
662 2-element list (w, h).
665 void GetPPIScreen(int* w
, int* h
) const;
668 Called by the framework to obtain information from the application about minimum
669 and maximum page values that the user can select, and the required page range to
672 By default this returns (1, 32000) for the page minimum and maximum values, and
673 (1, 1) for the required page range.
675 @a minPage must be greater than zero and @a maxPage must be greater
678 virtual void GetPageInfo(int* minPage
, int* maxPage
, int* pageFrom
,
682 Returns the size of the printer page in millimetres.
685 In wxPerl this method takes no arguments and returns a
686 2-element list (w, h).
689 void GetPageSizeMM(int* w
, int* h
) const;
692 Returns the size of the printer page in pixels, called the page rectangle.
694 The page rectangle has a top left corner at (0,0) and a bottom right corner at
695 (w,h). These values may not be the same as the values returned from
696 wxDC::GetSize(); if the printout is being used for
697 previewing, a memory device context is used, which uses a bitmap size reflecting
698 the current preview zoom. The application must take this discrepancy into
699 account if previewing is to be supported.
701 void GetPageSizePixels(int* w
, int* h
) const;
704 Returns the rectangle that corresponds to the entire paper in pixels, called the
707 This distinction between paper rectangle and page rectangle reflects the fact that
708 most printers cannot print all the way to the edge of the paper.
709 The page rectangle is a rectangle whose top left corner is at (0,0) and whose width
710 and height are given by wxDC::GetPageSizePixels().
712 On MSW and Mac, the page rectangle gives the printable area of the paper, while the
713 paper rectangle represents the entire paper, including non-printable borders.
714 Thus, the rectangle returned by wxDC::GetPaperRectPixels() will have a top left corner
715 whose coordinates are small negative numbers and the bottom right corner will have
716 values somewhat larger than the width and height given by wxDC::GetPageSizePixels().
718 On other platforms and for PostScript printing, the paper is treated as if its entire
719 area were printable, so this function will return the same rectangle as the page
722 wxRect
GetPaperRectPixels() const;
725 Returns the title of the printout.
727 @todo the python note here was wrong
729 virtual wxString
GetTitle() const;
732 Should be overridden to return @true if the document has this page, or @false
735 Returning @false signifies the end of the document. By default,
736 HasPage behaves as if the document has only one page.
738 virtual bool HasPage(int pageNum
);
741 Returns @true if the printout is currently being used for previewing.
745 virtual bool IsPreview() const;
748 Returns the associated preview object if any.
750 If this printout object is used for previewing, returns the associated
751 wxPrintPreview. Otherwise returns @NULL.
753 The returned pointer is not owned by the printout and must not be
760 wxPrintPreview
*GetPreview() const;
763 Set the user scale and device origin of the wxDC associated with this wxPrintout
764 so that one screen pixel maps to one device pixel on the DC.
765 That is, the user scale is set to (1,1) and the device origin is set to (0,0).
767 Use this if you want to do your own scaling prior to calling wxDC drawing calls,
768 for example, if your underlying model is floating-point and you want to achieve
769 maximum drawing precision on high-resolution printers.
771 You can use the GetLogicalXXXRect() routines below to obtain the paper rectangle,
772 page rectangle, or page margins rectangle to perform your own scaling.
775 While the underlying drawing model of Mac OS X is floating-point,
776 wxWidgets's drawing model scales from integer coordinates.
778 void MapScreenSizeToDevice();
781 This sets the user scale of the wxDC associated with this wxPrintout to the same
782 scale as MapScreenSizeToPaper() but sets the logical origin to the top left corner
783 of the page rectangle.
785 void MapScreenSizeToPage();
788 This sets the user scale of the wxDC associated with this wxPrintout to the same
789 scale as MapScreenSizeToPageMargins() but sets the logical origin to the top left
790 corner of the page margins specified by the given wxPageSetupDialogData object.
792 void MapScreenSizeToPageMargins(const wxPageSetupDialogData
& pageSetupData
);
795 Set the user scale and device origin of the wxDC associated with this wxPrintout
796 so that the printed page matches the screen size as closely as possible
797 and the logical origin is in the top left corner of the paper rectangle.
799 That is, a 100-pixel object on screen should appear at the same size on the
801 (It will, of course, be larger or smaller in the preview image, depending on the
804 Use this if you want WYSIWYG behaviour, e.g., in a text editor.
806 void MapScreenSizeToPaper();
809 Shift the device origin by an amount specified in logical coordinates.
811 void OffsetLogicalOrigin(wxCoord xoff
, wxCoord yoff
);
814 Called by the framework at the start of document printing. Return @false from
815 this function cancels the print job.
817 OnBeginDocument() is called once for every copy printed.
820 The base OnBeginDocument() must be called (and the return value
821 checked) from within the overridden function, since it calls wxDC::StartDoc().
823 virtual bool OnBeginDocument(int startPage
, int endPage
);
826 Called by the framework at the start of printing.
828 OnBeginPrinting() is called once for every print job
829 (regardless of how many copies are being printed).
831 virtual void OnBeginPrinting();
834 Called by the framework at the end of document printing.
836 OnEndDocument() is called once for every copy printed.
839 The base OnEndDocument() must be called from within the overridden function,
840 since it calls wxDC::EndDoc().
842 virtual void OnEndDocument();
845 Called by the framework at the end of printing.
847 OnEndPrinting is called once for every print job
848 (regardless of how many copies are being printed).
850 virtual void OnEndPrinting();
853 Called once by the framework before any other demands are made of the
856 This gives the object an opportunity to calculate the number of pages
857 in the document, for example.
859 virtual void OnPreparePrinting();
862 Called by the framework when a page should be printed. Returning @false cancels
865 virtual bool OnPrintPage(int pageNum
) = 0;
868 Set the device origin of the associated wxDC so that the current logical point
869 becomes the new logical origin.
871 void SetLogicalOrigin(wxCoord x
, wxCoord y
);