.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "pod::Prima::Printer 3" .TH pod::Prima::Printer 3 "2014-10-14" "perl v5.20.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Prima::Printer \- system printing services .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& my $printer = $::application\-> get_printer; \& print "printing to ", $printer\->printer, "...\en"; \& $p\-> options( Orientation => \*(AqLandscape\*(Aq, PaperSize => \*(AqA4\*(Aq); \& if ( $p\-> begin_doc) { \& $p\-> bar( 0, 0, 100, 100); \& print "another page...\en"; \& $p\-> new_page or die "new_page:$@"; \& $p\-> ellipse( 100, 100, 200, 200); \& (time % 1) ? # depending on the moon phase, print it or cancel out \& $p\-> end_doc : \& $p\-> abort_doc; \& } else { \& print "failed:$@\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIPrima::Printer\fR is a descendant of \fIPrima::Drawable\fR class. It provides access to the system printing services, where available. If the system provides no graphics printing, the default PostScript (tm) interface module \fIPrima::PS::Printer\fR is used instead. .SH "Usage" .IX Header "Usage" \&\fIPrima::Printer\fR objects are never created directly. During the life of a program, there exists only one instance of a printer object, created automatically by \fIPrima::Application\fR. \&\fIPrima::Printer\fR object is created only when the system provides graphic printing capabilities \- drawing and painting procedures on a graphic device. If there are no such \s-1API, \s0\fIPrima::Application\fR creates an instance of \fIPrima::PS::Printer\fR instead, which emulates a graphic device, producing PostScript output. The discretion between \fIPrima::Printer\fR and \fIPrima::PS::Printer\fR is transparent for both the user and the programmer, unless printer device specific adjustments desired. .PP A printing session is started by \f(CW\*(C`begin_doc()\*(C'\fR, which switches the object into the painting state. If finished by \f(CW\*(C`end_doc()\*(C'\fR, the document is delivered to a printer device. Alternative finishing method, \f(CW\*(C`abort_doc()\*(C'\fR, terminates the printing session with no information printed, unless the document is multi-paged and pages were sent to the printer via \f(CW\*(C`new_page()\*(C'\fR. .PP A printer object ( that means, both \fIPrima::Printer\fR and \fIPrima::PS::Printer\fR ) provides selection of the printer mechanism. \f(CW\*(C`printers()\*(C'\fR method returns array of hashes, each describing a printer device; \f(CW\*(C`get_default_printer()\*(C'\fR returns a default printer string identifier. A printer device can be selected via the \f(CW\*(C`::printer\*(C'\fR property. .PP The capabilities of the selected printer can be adjusted via \f(CW\*(C`setup_dialog()\*(C'\fR method, that invokes a system-provided ( or, in case of \fIPrima::PS::Printer\fR, toolkit-provided ) printer setup dialog, so the user can adjust settings of a printer device. It depends on the system, whether the setup changes only the instance settings, or the default behavior of a printer driver is affected for all programs. .PP Some printer capabilities can be queried by the \f(CW\*(C`::size()\*(C'\fR property, that reports the dimension of the page, the \f(CW\*(C`::resolution()\*(C'\fR property, that reports the \s-1DPI\s0 resolution selected by a printer driver and font list ( by \f(CW\*(C`fonts()\*(C'\fR method ), available for usage. .PP Typical code that prints the document looks like .PP .Vb 7 \& my $p = $::application\-> get_printer; \& if ( $p\-> begin_doc) { \& ... draw ... \& $p\-> end_doc; \& } else { \& print "failed:$@\en"; \& } .Ve .PP In addition, a standard package \fIPrima::PrintDialog\fR can be recommended so the user can select a printer device and adjust its setup interactively. .SH "API" .IX Header "API" .SS "Properties" .IX Subsection "Properties" .IP "printer \s-1STRING\s0" 4 .IX Item "printer STRING" Selects a printer device, specified by its \s-1STRING\s0 identifier. Can not select a device if a printing session is started. .IP "resolution X, Y" 4 .IX Item "resolution X, Y" A read-only property; returns a \s-1DPI\s0 horizontal and vertical resolution, currently selected for a printer device. The user can change this, if the printer device supports several resolutions, inside \f(CW\*(C`setup_dialog()\*(C'\fR. .IP "size \s-1WIDTH, HEIGHT\s0" 4 .IX Item "size WIDTH, HEIGHT" A read-only property; returns dimensions of a printer device page. The user can change this, if the printer device supports several resolutions or page formats, inside \f(CW\*(C`setup_dialog()\*(C'\fR. .SS "Methods" .IX Subsection "Methods" .IP "abort_doc" 4 .IX Item "abort_doc" Stops the printing session, returns the object to the disabled painting state. Since the document can be passed to the system spooler, parts of it could have been sent to a printing device when \f(CW\*(C`abort_doc()\*(C'\fR is called, so some information could still been printed. .ie n .IP "begin_doc \s-1DOCUMENT_NAME\s0 = """"" 4 .el .IP "begin_doc \s-1DOCUMENT_NAME\s0 = ``''" 4 .IX Item "begin_doc DOCUMENT_NAME = """"" Initiates the printing session, and triggers the object into the enabled painting state. The document is assigned \s-1DOCUMENT_NAME\s0 string identifier. .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .IP "begin_paint" 4 .IX Item "begin_paint" Identical to \f(CW\*(C`begin_doc("")\*(C'\fR call. .IP "begin_paint_info" 4 .IX Item "begin_paint_info" Triggers the object into the information painting state. In this state, all graphic functions can be accessed, but no data is printed. Neither \&\f(CW\*(C`new_page()\*(C'\fR and \f(CW\*(C`abort_doc()\*(C'\fR methods work. The information mode is exited via \f(CW\*(C`end_paint_info()\*(C'\fR method. .IP "end_doc" 4 .IX Item "end_doc" Quits the printing session and delivers the document to a printer device. Does not report eventual errors, occurred during the spooling process \- the system is expected to take care about such situations. .IP "end_paint" 4 .IX Item "end_paint" Identical to \f(CW\*(C`abort_doc()\*(C'\fR. .IP "end_paint_info" 4 .IX Item "end_paint_info" Quits the information painting mode, initiated by \f(CW\*(C`begin_paint_info()\*(C'\fR and returns the object into the disabled painting state. .IP "font_encodings" 4 .IX Item "font_encodings" Returns array of encodings, represented by strings, that are recognized by the system and available in at least one font. Each system provides different sets of encoding strings; the font encodings are not portable. .IP "fonts \s-1NAME\s0 = '', \s-1ENCODING\s0 = ''" 4 .IX Item "fonts NAME = '', ENCODING = ''" Returns hash of font hashes ( see Prima::Drawable, Fonts section ) describing fonts of \s-1NAME\s0 font family and of \s-1ENCODING.\s0 If \s-1NAME\s0 is '' or \f(CW\*(C`undef\*(C'\fR, returns one fonts hash for each of the font families that match the \s-1ENCODING\s0 string. If \s-1ENCODING\s0 is '' or \f(CW\*(C`undef\*(C'\fR, no encoding match is performed. If \s-1ENCODING\s0 is not valid ( not present in \f(CW\*(C`font_encodings\*(C'\fR result), it is treated as if it was '' or \f(CW\*(C`undef\*(C'\fR. .Sp In the special case, when both \s-1NAME\s0 and \s-1ENCODING\s0 are '' or \f(CW\*(C`undef\*(C'\fR, each font metric hash contains element \f(CW\*(C`encodings\*(C'\fR, that points to array of the font encodings, available for the fonts of \s-1NAME\s0 font family. .IP "new_page" 4 .IX Item "new_page" Finalizes the current page and starts a new blank page. .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .IP "options [ \s-1OPTION,\s0 [ \s-1VALUE,\s0 [ ... ]]]" 4 .IX Item "options [ OPTION, [ VALUE, [ ... ]]]" Queries and sets printer-specific setup options, such as orientation, paper size, etc. If called without parameters, returns list of options the printer supports. If called with one parameter, treats is as the option name and return the corresponsing value. Otherwise, treats parameters as a list of key-value pairs, and sets the printer options. Returns number of options that were successfully set. .Sp The compatibility between options and values used by different OSes is low here. The only fully compatible options are .RS 4 .ie n .IP "\- ""Orientation""[""Portrait | Landscape""]" 1 .el .IP "\- \f(CWOrientation\fR[\f(CWPortrait | Landscape\fR]" 1 .IX Item "- Orientation[Portrait | Landscape]" .PD 0 .ie n .IP "\- ""Color""[""Color | Monochrome""]" 1 .el .IP "\- \f(CWColor\fR[\f(CWColor | Monochrome\fR]" 1 .IX Item "- Color[Color | Monochrome]" .ie n .IP "\- ""Copies""[""integer""]" 1 .el .IP "\- \f(CWCopies\fR[\f(CWinteger\fR]" 1 .IX Item "- Copies[integer]" .ie n .IP "\- ""PaperSize""[""A\f(CIinteger\f(CW | B\f(CIinteger\f(CW | Executive | Folio | Ledger | Legal | Letter | Tabloid""]." 1 .el .IP "\- \f(CWPaperSize\fR[\f(CWA\f(CIinteger\f(CW | B\f(CIinteger\f(CW | Executive | Folio | Ledger | Legal | Letter | Tabloid\fR]." 1 .IX Item "- PaperSize[Ainteger | Binteger | Executive | Folio | Ledger | Legal | Letter | Tabloid]." .RE .RS 4 .PD .Sp The other options are OS-dependant. For win32, consult Microsoft manual on \&\s-1DEVMODE\s0 structure ; for Prima's own PostScript printer, consult Prima::PS::Printer. .RE .IP "printers" 4 .IX Item "printers" Returns array of hashes, where each entry describes a printer device. The hash consists of the following entries: .RS 4 .IP "name" 4 .IX Item "name" A printer device name .IP "device" 4 .IX Item "device" A physical device name, that the printer is connected to .IP "defaultPrinter" 4 .IX Item "defaultPrinter" A boolean flag, 1 if the printer is default, 0 otherwise. .RE .RS 4 .RE .IP "setup_dialog" 4 .IX Item "setup_dialog" Invokes the system-provided printer device setup dialog. In this setup, the user can adjust the capabilities of the printer, such as page setup, resolution, color, etc etc. .IP "get_default_printer" 4 .IX Item "get_default_printer" Returns a string, identifying a default printer device. .IP "get_handle" 4 .IX Item "get_handle" Returns a system handle for a printer object. .SH "AUTHOR" .IX Header "AUTHOR" Dmitry Karasik, . .SH "SEE ALSO" .IX Header "SEE ALSO" Prima, Prima::Drawable, Prima::PS::Printer