Use UTF16 for text data object on Mac. Fixes #10902
[wxWidgets.git] / docs / doxygen / overviews / printing.h
CommitLineData
15b6757b 1/////////////////////////////////////////////////////////////////////////////
2cd3cc94 2// Name: printing.h
15b6757b
FM
3// Purpose: topic overview
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
880efa2a 9/**
36c9828f 10
b1b95a65 11@page overview_printing Printing Framework Overview
2cd3cc94
BP
12
13Classes:
14@li wxPrintout
15@li wxPrinter
16@li wxPrintPreview
17@li wxPrinterDC
18@li wxPostScriptDC
19@li wxPrintDialog
20@li wxPrintData
21@li wxPrintDialogData
22@li wxPageSetupDialog
23@li wxPageSetupDialogData
24
30738aae
FM
25
26@li @ref overview_printing_printout
27@li @ref overview_printing_printer
28@li @ref overview_printing_printpreview
29@li @ref overview_printing_printerdc
30@li @ref overview_printing_postscriptdc
31@li @ref overview_printing_printdialog
32@li @ref overview_printing_printdata
33@li @ref overview_printing_printdialogdata
34@li @ref overview_printing_pagesetupdialog
35@li @ref overview_printing_pagesetupdialogdata
36
37
38<hr>
39
40
2cd3cc94
BP
41The printing framework relies on the application to provide classes whose
42member functions can respond to particular requests, such as 'print this page'
43or 'does this page exist in the document?'. This method allows wxWidgets to
44take over the housekeeping duties of turning preview pages, calling the print
45dialog box, creating the printer device context, and so on: the application can
46concentrate on the rendering of the information onto a device context.
47
48In most cases, the only class you will need to derive from is wxPrintout; all
49others will be used as-is.
50
51A brief description of each class's role and how they work together follows.
52
53For the special case of printing under Unix, where various different printing
54backends have to be offered, please have a look at @ref overview_unixprinting.
55
56
57@section overview_printing_printout wxPrintout
58
59A document's printing ability is represented in an application by a derived
60wxPrintout class. This class prints a page on request, and can be passed to the
61Print function of a wxPrinter object to actually print the document, or can be
62passed to a wxPrintPreview object to initiate previewing. The following code
63(from the printing sample) shows how easy it is to initiate printing,
64previewing and the print setup dialog, once the wxPrintout functionality has
65been defined. Notice the use of MyPrintout for both printing and previewing.
66All the preview user interface functionality is taken care of by wxWidgets. For
67more details on how MyPrintout is defined, please look at the printout sample
68code.
69
70@code
71case WXPRINT_PRINT:
72{
73 wxPrinter printer;
74 MyPrintout printout("My printout");
75 printer.Print(this, &printout, true);
76 break;
77}
78case WXPRINT_PREVIEW:
79{
80 // Pass two printout objects: for preview, and possible printing.
81 wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout);
82 wxPreviewFrame *frame = new wxPreviewFrame(preview, this,
83 "Demo Print Preview",
84 wxPoint(100, 100),
85 wxSize(600, 650));
86 frame->Centre(wxBOTH);
87 frame->Initialize();
88 frame->Show(true);
89 break;
90}
91@endcode
92
93wxPrintout assembles the printed page and (using your subclass's overrides)
94writes requested pages to a wxDC that is passed to it. This wxDC could be a
95wxMemoryDC (for displaying the preview image on-screen), a wxPrinterDC (for
96printing under MSW and Mac), or a wxPostScriptDC (for printing under GTK or
97generating PostScript output).
98
99The @ref overview_docview "document/view framework" creates a default
3ed3a1c8 100wxPrintout object for every view, calling wxView::OnDraw() to achieve a
2cd3cc94
BP
101prepackaged print/preview facility.
102
103If your window classes have a Draw(wxDC *dc) routine to do screen rendering,
104your wxPrintout subclass will typically call those routines to create portions
105of the image on your printout. Your wxPrintout subclass can also make its own
106calls to its wxDC to draw headers, footers, page numbers, etc.
107
108The scaling of the drawn image typically differs from the screen to the preview
109and printed images. This class provides a set of routines named
110FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
111used to set the user scale and origin of the wxPrintout's DC so that your class
112can easily map your image to the printout withough getting into the details of
113screen and printer PPI and scaling. See the printing sample for examples of how
114these routines are used.
115
116
117@section overview_printing_printer wxPrinter
118
119Class wxPrinter encapsulates the platform-dependent print function with a common
120interface. In most cases, you will not need to derive a class from wxPrinter;
121simply create a wxPrinter object in your Print function as in the example above.
122
123
124@section overview_printing_printpreview wxPrintPreview
125
126Class wxPrintPreview manages the print preview process. Among other things, it
127constructs the wxDCs that get passed to your wxPrintout subclass for printing
128and manages the display of multiple pages, a zoomable preview image, and so
129forth. In most cases you will use this class as-is, but you can create your own
130subclass, for example, to change the layout or contents of the preview window.
131
132
133@section overview_printing_printerdc wxPrinterDC
134
135Class wxPrinterDC is the wxDC that represents the actual printed page under MSW
136and Mac. During printing, an object of this class will be passed to your derived
137wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the
138paper orientation and the resolution of the printer.
139
140There are two important rectangles in printing: the <em>page rectangle</em>
141defines the printable area seen by the application, and under MSW and Mac, it
142is the printable area specified by the printer. (For PostScript printing, the
143page rectangle is the entire page.) The inherited function
3ed3a1c8 144wxDC::GetSize() returns the page size in device pixels. The
2cd3cc94
BP
145point (0,0) on the wxPrinterDC represents the top left corner of the page
146rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h)
147are the values returned by GetSize.
148
149The <em>paper rectangle</em>, on the other hand, represents the entire paper
150area including the non-printable border. Thus, the coordinates of the top left
151corner of the paper rectangle will have small negative values, while the width
152and height will be somewhat larger than that of the page rectangle. The
3ed3a1c8 153wxPrinterDC-specific function wxPrinterDC::GetPaperRect() returns the paper
2cd3cc94
BP
154rectangle of the given wxPrinterDC.
155
156
157@section overview_printing_postscriptdc wxPostScriptDC
158
159Class wxPostScriptDC is the wxDC that represents the actual printed page under
160GTK and other PostScript printing. During printing, an object of this class
161will be passed to your derived wxPrintout object to draw upon. The size of the
162wxPostScriptDC will depend upon the wxPrintData used to construct it.
163
164Unlike a wxPrinterDC, there is no distinction between the page rectangle and
165the paper rectangle in a wxPostScriptDC; both rectangles are taken to represent
166the entire sheet of paper.
167
168
169@section overview_printing_printdialog wxPrintDialog
170
171Class wxPrintDialog puts up the standard print dialog, which allows you to
172select the page range for printing (as well as many other print settings, which
173may vary from platform to platform). You provide an object of type
174wxPrintDialogData to the wxPrintDialog at construction, which is used to
175populate the dialog.
176
177
178@section overview_printing_printdata wxPrintData
36c9828f 179
2cd3cc94
BP
180Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to
181initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data
182member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially,
183wxPrintData contains those bits of information from the two dialogs necessary
184to configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.).
185You might wish to create a global instance of this object to provide
186call-to-call persistence to your application's print settings.
187
188
189@section overview_printing_printdialogdata wxPrintDialogData
190
191Class wxPrintDialogData contains the settings entered by the user in the print
192dialog. It contains such things as page range, number of copies, and so forth.
193In most cases, you won't need to access this information; the framework takes
194care of asking your wxPrintout derived object for the pages requested by the
195user.
196
197
198@section overview_printing_pagesetupdialog wxPageSetupDialog
199
200Class wxPageSetupDialog puts up the standard page setup dialog, which allows
201you to specify the orientation, paper size, and related settings. You provide
202it with a wxPageSetupDialogData object at intialization, which is used to
203populate the dialog; when the dialog is dismissed, this object contains the
204settings chosen by the user, including orientation and/or page margins.
205
206Note that on Macintosh, the native page setup dialog does not contain entries
207that allow you to change the page margins. You can use the Mac-specific class
208wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a
209wxPageSetupDialogData object in its constructor) to provide this capability;
210see the printing sample for an example.
211
212
213@section overview_printing_pagesetupdialogdata wxPageSetupDialogData
214
215Class wxPageSetupDialogData contains settings affecting the page size (paper
216size), orientation, margins, and so forth. Note that not all platforms populate
217all fields; for example, the MSW page setup dialog lets you set the page
218margins while the Mac setup dialog does not.
219
220You will typically create a global instance of each of a wxPrintData and
221wxPageSetupDialogData at program initiation, which will contain the default
222settings provided by the system. Each time the user calls up either the
223wxPrintDialog or the wxPageSetupDialog, you pass these data structures to
224initialize the dialog values and to be updated by the dialog. The framework
225then queries these data structures to get information like the printed page
226range (from the wxPrintDialogData) or the paper size and/or page orientation
227(from the wxPageSetupDialogData).
228
229*/
36c9828f 230