1pod::Prima::Printer(3)User Contributed Perl Documentationpod::Prima::Printer(3)
2
6 Prima::Printer - system printing services
7
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
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
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 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 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 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 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 Typical code that prints the document looks like
69 my $p = $::application-> get_printer;
71 if ( $p-> begin_doc) {
72 ... draw ...
73 $p-> end_doc;
74 } else {
75 print "failed:$@\n";
76 }
77 In addition, a standard package Prima::Dialog::PrintDialog can be
79 recommended so the user can select a printer device and adjust its
80 setup interactively.
81
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 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 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 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 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 Returns success flag; if failed, $@ contains the error.
113 begin_paint
115 Identical to "begin_doc("")" call.
116 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 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 end_paint
130 Identical to "abort_doc()".
131 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 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 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 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 new_page
158 Finalizes the current page and starts a new blank page.
159 Returns success flag; if failed, $@ contains the error.
161 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 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 printers
182 Returns array of hashes, where each entry describes a printer
183 device. The hash consists of the following entries:
184 name
186 A printer device name
187 device
189 A physical device name, that the printer is connected to
190 defaultPrinter
192 A boolean flag, 1 if the printer is default, 0 otherwise.
193 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 get_default_printer
200 Returns a string, identifying a default printer device.
201 get_handle
203 Returns a system handle for a printer object.
204
206 Dmitry Karasik, <dmitry@karasik.eu.org>.
207
209 Prima, Prima::Drawable, Prima::PS::Printer
210perl v5.32.1 2021-01-27 pod::Prima::Printer(3)