1wxPrintout(3) Erlang Module Definition wxPrintout(3)
2
3
4
6 wxPrintout - Functions for wxPrintout class
7
9 This class encapsulates the functionality of printing out an applica‐
10 tion document.
11
12 A new class must be derived and members overridden to respond to calls
13 such as OnPrintPage() (not implemented in wx) and HasPage() (not imple‐
14 mented in wx) and to render the print image onto an associated wxDC.
15 Instances of this class are passed to wxPrinter:print/4 or to a wx‐
16 PrintPreview object to initiate printing or previewing.
17
18 Your derived wxPrintout is responsible for drawing both the preview im‐
19 age and the printed page. If your windows' drawing routines accept an
20 arbitrary DC as an argument, you can re-use those routines within your
21 wxPrintout subclass to draw the printout image. You may also add addi‐
22 tional drawing elements within your wxPrintout subclass, like headers,
23 footers, and/or page numbers. However, the image on the printed page
24 will often differ from the image drawn on the screen, as will the print
25 preview image - not just in the presence of headers and footers, but
26 typically in scale. A high-resolution printer presents a much larger
27 drawing surface (i.e., a higher-resolution DC); a zoomed-out preview
28 image presents a much smaller drawing surface (lower-resolution DC). By
29 using the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX()
30 within your wxPrintout subclass to set the user scale and origin of the
31 associated DC, you can easily use a single drawing routine to draw on
32 your application's windows, to create the print preview image, and to
33 create the printed paper image, and achieve a common appearance to the
34 preview image and the printed page.
35
36 See: Overview printing, wxPrinterDC (not implemented in wx), wxPrintDi‐
37 alog, wxPageSetupDialog, wxPrinter, wxPrintPreview
38
39 wxWidgets docs: wxPrintout
40
42 wxPrintout() = wx:wx_object()
43
45 new(Title :: string(), OnPrintPage, Opts :: [Option]) ->
46 wxPrintout:wxPrintout()
47
48 Types:
49
50 OnPrintPage =
51 fun((wxPrintout(), Page :: integer()) -> boolean())
52 Option =
53 {onPreparePrinting, fun((wxPrintout()) -> ok)} |
54 {onBeginPrinting, fun((wxPrintout()) -> ok)} |
55 {onEndPrinting, fun((wxPrintout()) -> ok)} |
56 {onBeginDocument,
57 fun((wxPrintout(),
58 StartPage :: integer(),
59 EndPage :: integer()) ->
60 boolean())} |
61 {onEndDocument, fun((wxPrintout()) -> ok)} |
62 {hasPage, fun((wxPrintout(), Page :: integer()) -> ok)} |
63 {getPageInfo,
64 fun((wxPrintout()) ->
65 {MinPage :: integer(),
66 MaxPage :: integer(),
67 PageFrom :: integer(),
68 PageTo :: integer()})}
69
70 Constructor.
71
72 Creates a wxPrintout object with a callback fun and optionally
73 other callback funs. The This argument is the wxPrintout object
74 reference to this object
75
76 Notice: The callbacks may not call other processes.
77
78 destroy(This :: wxPrintout()) -> ok
79
80 Destructor.
81
82 getDC(This) -> wxDC:wxDC()
83
84 Types:
85
86 This = wxPrintout()
87
88 Returns the device context associated with the printout (given
89 to the printout at start of printing or previewing).
90
91 The application can use getDC/1 to obtain a device context to
92 draw on.
93
94 This will be a wxPrinterDC (not implemented in wx) if printing
95 under Windows or Mac, a wxPostScriptDC if printing on other
96 platforms, and a wxMemoryDC if previewing.
97
98 getPageSizeMM(This) -> {W :: integer(), H :: integer()}
99
100 Types:
101
102 This = wxPrintout()
103
104 Returns the size of the printer page in millimetres.
105
106 getPageSizePixels(This) -> {W :: integer(), H :: integer()}
107
108 Types:
109
110 This = wxPrintout()
111
112 Returns the size of the printer page in pixels, called the page
113 rectangle.
114
115 The page rectangle has a top left corner at (0,0) and a bottom
116 right corner at (w,h). These values may not be the same as the
117 values returned from wxDC:getSize/1; if the printout is being
118 used for previewing, a memory device context is used, which uses
119 a bitmap size reflecting the current preview zoom. The applica‐
120 tion must take this discrepancy into account if previewing is to
121 be supported.
122
123 getPaperRectPixels(This) ->
124 {X :: integer(),
125 Y :: integer(),
126 W :: integer(),
127 H :: integer()}
128
129 Types:
130
131 This = wxPrintout()
132
133 Returns the rectangle that corresponds to the entire paper in
134 pixels, called the paper rectangle.
135
136 This distinction between paper rectangle and page rectangle re‐
137 flects the fact that most printers cannot print all the way to
138 the edge of the paper. The page rectangle is a rectangle whose
139 top left corner is at (0,0) and whose width and height are given
140 by wxDC::GetPageSizePixels().
141
142 On MSW and Mac, the page rectangle gives the printable area of
143 the paper, while the paper rectangle represents the entire pa‐
144 per, including non-printable borders. Thus, the rectangle re‐
145 turned by wxDC::GetPaperRectPixels() will have a top left corner
146 whose coordinates are small negative numbers and the bottom
147 right corner will have values somewhat larger than the width and
148 height given by wxDC::GetPageSizePixels().
149
150 On other platforms and for PostScript printing, the paper is
151 treated as if its entire area were printable, so this function
152 will return the same rectangle as the page rectangle.
153
154 getPPIPrinter(This) -> {W :: integer(), H :: integer()}
155
156 Types:
157
158 This = wxPrintout()
159
160 Returns the number of pixels per logical inch of the printer de‐
161 vice context.
162
163 Dividing the printer PPI by the screen PPI can give a suitable
164 scaling factor for drawing text onto the printer.
165
166 Remember to multiply this by a scaling factor to take the pre‐
167 view DC size into account. Or you can just use the FitThisSize‐
168 ToXXX() and MapScreenSizeToXXX routines below, which do most of
169 the scaling calculations for you.
170
171 getPPIScreen(This) -> {W :: integer(), H :: integer()}
172
173 Types:
174
175 This = wxPrintout()
176
177 Returns the number of pixels per logical inch of the screen de‐
178 vice context.
179
180 Dividing the printer PPI by the screen PPI can give a suitable
181 scaling factor for drawing text onto the printer.
182
183 If you are doing your own scaling, remember to multiply this by
184 a scaling factor to take the preview DC size into account.
185
186 getTitle(This) -> unicode:charlist()
187
188 Types:
189
190 This = wxPrintout()
191
192 Returns the title of the printout.
193
194 isPreview(This) -> boolean()
195
196 Types:
197
198 This = wxPrintout()
199
200 Returns true if the printout is currently being used for pre‐
201 viewing.
202
203 See: GetPreview() (not implemented in wx)
204
205 fitThisSizeToPaper(This, ImageSize) -> ok
206
207 Types:
208
209 This = wxPrintout()
210 ImageSize = {W :: integer(), H :: integer()}
211
212 Set the user scale and device origin of the wxDC associated with
213 this wxPrintout so that the given image size fits entirely
214 within the paper and the origin is at the top left corner of the
215 paper.
216
217 Use this if you're managing your own page margins.
218
219 Note: With most printers, the region around the edges of the pa‐
220 per are not printable so that the edges of the image could be
221 cut off.
222
223 fitThisSizeToPage(This, ImageSize) -> ok
224
225 Types:
226
227 This = wxPrintout()
228 ImageSize = {W :: integer(), H :: integer()}
229
230 Set the user scale and device origin of the wxDC associated with
231 this wxPrintout so that the given image size fits entirely
232 within the page rectangle and the origin is at the top left cor‐
233 ner of the page rectangle.
234
235 On MSW and Mac, the page rectangle is the printable area of the
236 page. On other platforms and PostScript printing, the page rec‐
237 tangle is the entire paper.
238
239 Use this if you want your printed image as large as possible,
240 but with the caveat that on some platforms, portions of the im‐
241 age might be cut off at the edges.
242
243 fitThisSizeToPageMargins(This, ImageSize, PageSetupData) -> ok
244
245 Types:
246
247 This = wxPrintout()
248 ImageSize = {W :: integer(), H :: integer()}
249 PageSetupData = wxPageSetupDialogData:wxPageSetupDialogData()
250
251 Set the user scale and device origin of the wxDC associated with
252 this wxPrintout so that the given image size fits entirely
253 within the page margins set in the given wxPageSetupDialogData
254 object.
255
256 This function provides the greatest consistency across all plat‐
257 forms because it does not depend on having access to the print‐
258 able area of the paper.
259
260 Remark: On Mac, the native wxPageSetupDialog does not let you
261 set the page margins; you'll have to provide your own mechanism,
262 or you can use the Mac-only class wxMacPageMarginsDialog.
263
264 mapScreenSizeToPaper(This) -> ok
265
266 Types:
267
268 This = wxPrintout()
269
270 Set the user scale and device origin of the wxDC associated with
271 this wxPrintout so that the printed page matches the screen size
272 as closely as possible and the logical origin is in the top left
273 corner of the paper rectangle.
274
275 That is, a 100-pixel object on screen should appear at the same
276 size on the printed page. (It will, of course, be larger or
277 smaller in the preview image, depending on the zoom factor.)
278
279 Use this if you want WYSIWYG behaviour, e.g., in a text editor.
280
281 mapScreenSizeToPage(This) -> ok
282
283 Types:
284
285 This = wxPrintout()
286
287 This sets the user scale of the wxDC associated with this wx‐
288 Printout to the same scale as mapScreenSizeToPaper/1 but sets
289 the logical origin to the top left corner of the page rectangle.
290
291 mapScreenSizeToPageMargins(This, PageSetupData) -> ok
292
293 Types:
294
295 This = wxPrintout()
296 PageSetupData = wxPageSetupDialogData:wxPageSetupDialogData()
297
298 This sets the user scale of the wxDC associated with this wx‐
299 Printout to the same scale as mapScreenSizeToPageMargins/2 but
300 sets the logical origin to the top left corner of the page mar‐
301 gins specified by the given wxPageSetupDialogData object.
302
303 mapScreenSizeToDevice(This) -> ok
304
305 Types:
306
307 This = wxPrintout()
308
309 Set the user scale and device origin of the wxDC associated with
310 this wxPrintout so that one screen pixel maps to one device
311 pixel on the DC.
312
313 That is, the user scale is set to (1,1) and the device origin is
314 set to (0,0).
315
316 Use this if you want to do your own scaling prior to calling
317 wxDC drawing calls, for example, if your underlying model is
318 floating-point and you want to achieve maximum drawing precision
319 on high-resolution printers.
320
321 You can use the GetLogicalXXXRect() routines below to obtain the
322 paper rectangle, page rectangle, or page margins rectangle to
323 perform your own scaling.
324
325 Note: While the underlying drawing model of macOS is floating-
326 point, wxWidgets's drawing model scales from integer coordi‐
327 nates.
328
329 getLogicalPaperRect(This) ->
330 {X :: integer(),
331 Y :: integer(),
332 W :: integer(),
333 H :: integer()}
334
335 Types:
336
337 This = wxPrintout()
338
339 Return the rectangle corresponding to the paper in the associ‐
340 ated wxDC 's logical coordinates for the current user scale and
341 device origin.
342
343 getLogicalPageRect(This) ->
344 {X :: integer(),
345 Y :: integer(),
346 W :: integer(),
347 H :: integer()}
348
349 Types:
350
351 This = wxPrintout()
352
353 Return the rectangle corresponding to the page in the associated
354 wxDC 's logical coordinates for the current user scale and de‐
355 vice origin.
356
357 On MSW and Mac, this will be the printable area of the paper. On
358 other platforms and PostScript printing, this will be the full
359 paper rectangle.
360
361 getLogicalPageMarginsRect(This, PageSetupData) ->
362 {X :: integer(),
363 Y :: integer(),
364 W :: integer(),
365 H :: integer()}
366
367 Types:
368
369 This = wxPrintout()
370 PageSetupData = wxPageSetupDialogData:wxPageSetupDialogData()
371
372 Return the rectangle corresponding to the page margins specified
373 by the given wxPageSetupDialogData object in the associated
374 wxDC's logical coordinates for the current user scale and device
375 origin.
376
377 The page margins are specified with respect to the edges of the
378 paper on all platforms.
379
380 setLogicalOrigin(This, X, Y) -> ok
381
382 Types:
383
384 This = wxPrintout()
385 X = Y = integer()
386
387 Set the device origin of the associated wxDC so that the current
388 logical point becomes the new logical origin.
389
390 offsetLogicalOrigin(This, Xoff, Yoff) -> ok
391
392 Types:
393
394 This = wxPrintout()
395 Xoff = Yoff = integer()
396
397 Shift the device origin by an amount specified in logical coor‐
398 dinates.
399
400
401
402wxWidgets team. wx 2.2.2 wxPrintout(3)