1wxPrintout(3)              Erlang Module Definition              wxPrintout(3)
2
3
4

NAME

6       wxPrintout - Functions for wxPrintout class
7

DESCRIPTION

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

DATA TYPES

42       wxPrintout() = wx:wx_object()
43

EXPORTS

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)
Impressum