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