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