1wxPrintout(3) Erlang Module Definition wxPrintout(3)
2
6 wxPrintout - Functions for wxPrintout class
7
9 This class encapsulates the functionality of printing out an applica‐
10 tion document.
11 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 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 See: Overview printing, wxPrinterDC (not implemented in wx), wxPrintDi‐
37 alog, wxPageSetupDialog, wxPrinter, wxPrintPreview
38 wxWidgets docs: wxPrintout
40
42 wxPrintout() = wx:wx_object()
43
45 new(Title :: string(), OnPrintPage, Opts :: [Option]) ->
46 wxPrintout:wxPrintout()
47 Types:
49 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 Constructor.
71 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 Notice: The callbacks may not call other processes.
77 destroy(This :: wxPrintout()) -> ok
79 Destructor.
81 getDC(This) -> wxDC:wxDC()
83 Types:
85 This = wxPrintout()
87 Returns the device context associated with the printout (given
89 to the printout at start of printing or previewing).
90 The application can use getDC/1 to obtain a device context to
92 draw on.
93 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 getPageSizeMM(This) -> {W :: integer(), H :: integer()}
99 Types:
101 This = wxPrintout()
103 Returns the size of the printer page in millimetres.
105 getPageSizePixels(This) -> {W :: integer(), H :: integer()}
107 Types:
109 This = wxPrintout()
111 Returns the size of the printer page in pixels, called the page
113 rectangle.
114 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 getPaperRectPixels(This) ->
124 {X :: integer(),
125 Y :: integer(),
126 W :: integer(),
127 H :: integer()}
128 Types:
130 This = wxPrintout()
132 Returns the rectangle that corresponds to the entire paper in
134 pixels, called the paper rectangle.
135 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 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 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 getPPIPrinter(This) -> {W :: integer(), H :: integer()}
155 Types:
157 This = wxPrintout()
159 Returns the number of pixels per logical inch of the printer de‐
161 vice context.
162 Dividing the printer PPI by the screen PPI can give a suitable
164 scaling factor for drawing text onto the printer.
165 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 getPPIScreen(This) -> {W :: integer(), H :: integer()}
172 Types:
174 This = wxPrintout()
176 Returns the number of pixels per logical inch of the screen de‐
178 vice context.
179 Dividing the printer PPI by the screen PPI can give a suitable
181 scaling factor for drawing text onto the printer.
182 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 getTitle(This) -> unicode:charlist()
187 Types:
189 This = wxPrintout()
191 Returns the title of the printout.
193 isPreview(This) -> boolean()
195 Types:
197 This = wxPrintout()
199 Returns true if the printout is currently being used for pre‐
201 viewing.
202 See: GetPreview() (not implemented in wx)
204 fitThisSizeToPaper(This, ImageSize) -> ok
206 Types:
208 This = wxPrintout()
210 ImageSize = {W :: integer(), H :: integer()}
211 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 Use this if you're managing your own page margins.
218 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 fitThisSizeToPage(This, ImageSize) -> ok
224 Types:
226 This = wxPrintout()
228 ImageSize = {W :: integer(), H :: integer()}
229 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 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 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 fitThisSizeToPageMargins(This, ImageSize, PageSetupData) -> ok
244 Types:
246 This = wxPrintout()
248 ImageSize = {W :: integer(), H :: integer()}
249 PageSetupData = wxPageSetupDialogData:wxPageSetupDialogData()
250 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 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 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 mapScreenSizeToPaper(This) -> ok
265 Types:
267 This = wxPrintout()
269 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 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 Use this if you want WYSIWYG behaviour, e.g., in a text editor.
280 mapScreenSizeToPage(This) -> ok
282 Types:
284 This = wxPrintout()
286 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 mapScreenSizeToPageMargins(This, PageSetupData) -> ok
292 Types:
294 This = wxPrintout()
296 PageSetupData = wxPageSetupDialogData:wxPageSetupDialogData()
297 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 mapScreenSizeToDevice(This) -> ok
304 Types:
306 This = wxPrintout()
308 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 That is, the user scale is set to (1,1) and the device origin is
314 set to (0,0).
315 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 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 Note: While the underlying drawing model of macOS is floating-
326 point, wxWidgets's drawing model scales from integer coordi‐
327 nates.
328 getLogicalPaperRect(This) ->
330 {X :: integer(),
331 Y :: integer(),
332 W :: integer(),
333 H :: integer()}
334 Types:
336 This = wxPrintout()
338 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 getLogicalPageRect(This) ->
344 {X :: integer(),
345 Y :: integer(),
346 W :: integer(),
347 H :: integer()}
348 Types:
350 This = wxPrintout()
352 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 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 getLogicalPageMarginsRect(This, PageSetupData) ->
362 {X :: integer(),
363 Y :: integer(),
364 W :: integer(),
365 H :: integer()}
366 Types:
368 This = wxPrintout()
370 PageSetupData = wxPageSetupDialogData:wxPageSetupDialogData()
371 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 The page margins are specified with respect to the edges of the
378 paper on all platforms.
379 setLogicalOrigin(This, X, Y) -> ok
381 Types:
383 This = wxPrintout()
385 X = Y = integer()
386 Set the device origin of the associated wxDC so that the current
388 logical point becomes the new logical origin.
389 offsetLogicalOrigin(This, Xoff, Yoff) -> ok
391 Types:
393 This = wxPrintout()
395 Xoff = Yoff = integer()
396 Shift the device origin by an amount specified in logical coor‐
398 dinates.
399wxWidgets team. wx 2.3.1 wxPrintout(3)