]>
Commit | Line | Data |
---|---|---|
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 |