1pod::Prima::Printer(3)User Contributed Perl Documentationpod::Prima::Printer(3)
2
3
4

NAME

6       Prima::Printer - system printing services
7

SYNOPSIS

9          my $printer = $::application-> get_printer;
10          print "printing to ", $printer->printer, "...\n";
11          $p-> options( Orientation => 'Landscape', PaperSize => 'A4');
12          if ( $p-> begin_doc) {
13             $p-> bar( 0, 0, 100, 100);
14             print "another page...\n";
15             $p-> new_page or die "new_page:$@";
16             $p-> ellipse( 100, 100, 200, 200);
17             (time % 1) ? # depending on the moon phase, print it or cancel out
18                   $p-> end_doc :
19                   $p-> abort_doc;
20          } else {
21             print "failed:$@\n";
22          }
23

DESCRIPTION

25       Prima::Printer is a descendant of Prima::Drawable class.  It provides
26       access to the system printing services, where available. If the system
27       provides no graphics printing, the default PostScript (tm) interface
28       module Prima::PS::Printer is used instead.
29

Usage

31       Prima::Printer objects are never created directly. During the life of a
32       program, there exists only one instance of a printer object, created
33       automatically by Prima::Application.  Prima::Printer object is created
34       only when the system provides graphic printing capabilities - drawing
35       and painting procedures on a graphic device.  If there are no such API,
36       Prima::Application creates an instance of Prima::PS::Printer instead,
37       which emulates a graphic device, producing PostScript output.  The
38       discretion between Prima::Printer and Prima::PS::Printer is transparent
39       for both the user and the programmer, unless printer device specific
40       adjustments desired.
41
42       A printing session is started by "begin_doc()", which switches the
43       object into the painting state. If finished by "end_doc()", the
44       document is delivered to a printer device. Alternative finishing
45       method, "abort_doc()", terminates the printing session with no
46       information printed, unless the document is multi-paged and pages were
47       sent to the printer via "new_page()".
48
49       A printer object ( that means, both Prima::Printer and
50       Prima::PS::Printer ) provides selection of the printer mechanism.
51       "printers()" method returns array of hashes, each describing a printer
52       device; "get_default_printer()" returns a default printer string
53       identifier. A printer device can be selected via the "::printer"
54       property.
55
56       The capabilities of the selected printer can be adjusted via
57       "setup_dialog()" method, that invokes a system-provided ( or, in case
58       of Prima::PS::Printer, toolkit-provided ) printer setup dialog, so the
59       user can adjust settings of a printer device.  It depends on the
60       system, whether the setup changes only the instance settings, or the
61       default behavior of a printer driver is affected for all programs.
62
63       Some printer capabilities can be queried by the "::size()" property,
64       that reports the dimension of the page, the "::resolution()" property,
65       that reports the DPI resolution selected by a printer driver and font
66       list ( by "fonts()" method ), available for usage.
67
68       Typical code that prints the document looks like
69
70          my $p = $::application-> get_printer;
71          if ( $p-> begin_doc) {
72             ... draw ...
73             $p-> end_doc;
74          } else {
75             print "failed:$@\n";
76          }
77
78       In addition, a standard package Prima::PrintDialog can be recommended
79       so the user can select a printer device and adjust its setup
80       interactively.
81

API

83   Properties
84       printer STRING
85           Selects a printer device, specified by its STRING identifier.  Can
86           not select a device if a printing session is started.
87
88       resolution X, Y
89           A read-only property; returns a DPI horizontal and vertical
90           resolution, currently selected for a printer device. The user can
91           change this, if the printer device supports several resolutions,
92           inside "setup_dialog()".
93
94       size WIDTH, HEIGHT
95           A read-only property; returns dimensions of a printer device page.
96           The user can change this, if the printer device supports several
97           resolutions or page formats, inside "setup_dialog()".
98
99   Methods
100       abort_doc
101           Stops the printing session, returns the object to the disabled
102           painting state.  Since the document can be passed to the system
103           spooler, parts of it could have been sent to a printing device when
104           "abort_doc()" is called, so some information could still been
105           printed.
106
107       begin_doc DOCUMENT_NAME = ""
108           Initiates the printing session, and triggers the object into the
109           enabled painting state. The document is assigned DOCUMENT_NAME
110           string identifier.
111
112           Returns success flag; if failed, $@ contains the error.
113
114       begin_paint
115           Identical to "begin_doc("")" call.
116
117       begin_paint_info
118           Triggers the object into the information painting state. In this
119           state, all graphic functions can be accessed, but no data is
120           printed. Neither "new_page()" and "abort_doc()" methods work. The
121           information mode is exited via "end_paint_info()" method.
122
123       end_doc
124           Quits the printing session and delivers the document to a printer
125           device.  Does not report eventual errors, occurred during the
126           spooling process - the system is expected to take care about such
127           situations.
128
129       end_paint
130           Identical to "abort_doc()".
131
132       end_paint_info
133           Quits the information painting mode, initiated by
134           "begin_paint_info()" and returns the object into the disabled
135           painting state.
136
137       font_encodings
138           Returns array of encodings, represented by strings, that are
139           recognized by the system and available in at least one font. Each
140           system provides different sets of encoding strings; the font
141           encodings are not portable.
142
143       fonts NAME = '', ENCODING = ''
144           Returns hash of font hashes ( see Prima::Drawable, Fonts section )
145           describing fonts of NAME font family and of ENCODING. If NAME is ''
146           or "undef", returns one fonts hash for each of the font families
147           that match the ENCODING string. If ENCODING is '' or "undef", no
148           encoding match is performed.  If ENCODING is not valid ( not
149           present in "font_encodings" result), it is treated as if it was ''
150           or "undef".
151
152           In the special case, when both NAME and ENCODING are '' or "undef",
153           each font metric hash contains element "encodings", that points to
154           array of the font encodings, available for the fonts of NAME font
155           family.
156
157       new_page
158           Finalizes the current page and starts a new blank page.
159
160           Returns success flag; if failed, $@ contains the error.
161
162       options [ OPTION, [ VALUE, [ ... ]]]
163           Queries and sets printer-specific setup options, such as
164           orientation, paper size, etc. If called without parameters, returns
165           list of options the printer supports.  If called with one
166           parameter, treats is as the option name and return the
167           corresponsing value. Otherwise, treats parameters as a list of key-
168           value pairs, and sets the printer options. Returns number of
169           options that were successfully set.
170
171           The compatibility between options and values used by different OSes
172           is low here.  The only fully compatible options are
173           "Orientation"["Portrait|Landscape"], "Color"["Color|Monochrome"],
174           "Copies"["integer"], and
175           "PaperSize"["Ainteger|Binteger|Executive|Folio|Ledger|Legal|Letter|Tabloid"].
176           The other options are OS-dependant. For win32, consult Microsoft
177           manual on DEVMODE structure
178           <http://msdn.microsoft.com/library/en-us/gdi/prntspol_8nle.asp>;
179           for Prima's own PostScript printer, consult Prima::PS::Printer.
180
181       printers
182           Returns array of hashes, where each entry describes a printer
183           device.  The hash consists of the following entries:
184
185           name
186               A printer device name
187
188           device
189               A physical device name, that the printer is connected to
190
191           defaultPrinter
192               A boolean flag, 1 if the printer is default, 0 otherwise.
193
194       setup_dialog
195           Invokes the system-provided printer device setup dialog.  In this
196           setup, the user can adjust the capabilities of the printer, such as
197           page setup, resolution, color, etc etc.
198
199       get_default_printer
200           Returns a string, identifying a default printer device.
201
202       get_handle
203           Returns a system handle for a printer object.
204

AUTHOR

206       Dmitry Karasik, <dmitry@karasik.eu.org>.
207

SEE ALSO

209       Prima, Prima::Drawable, Prima::PS::Printer
210
211
212
213perl v5.30.0                      2019-08-21            pod::Prima::Printer(3)
Impressum