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