Provided by: libprima-perl_1.28-1.2_amd64 bug

NAME

       Prima::Printer - system printing services

SYNOPSIS

          my $printer = $::application-> get_printer;
          print "printing to ", $printer->printer, "...\n";
          $p-> options( Orientation => 'Landscape', PaperSize => 'A4');
          if ( $p-> begin_doc) {
             $p-> bar( 0, 0, 100, 100);
             print "another page...\n";
             $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:$@\n";
          }

DESCRIPTION

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

Usage

       Prima::Printer objects are never created directly. During the life of a program, there
       exists only one instance of a printer object, created automatically by Prima::Application.
       Prima::Printer object is created only when the system provides graphic printing
       capabilities - drawing and painting procedures on a graphic device.  If there are no such
       API, Prima::Application creates an instance of Prima::PS::Printer instead, which emulates
       a graphic device, producing PostScript output.  The discretion between Prima::Printer and
       Prima::PS::Printer is transparent for both the user and the programmer, unless printer
       device specific adjustments desired.

       A printing session is started by "begin_doc()", which switches the object into the
       painting state. If finished by "end_doc()", the document is delivered to a printer device.
       Alternative finishing method, "abort_doc()", terminates the printing session with no
       information printed, unless the document is multi-paged and pages were sent to the printer
       via "new_page()".

       A printer object ( that means, both Prima::Printer and Prima::PS::Printer ) provides
       selection of the printer mechanism. "printers()" method returns array of hashes, each
       describing a printer device; "get_default_printer()" returns a default printer string
       identifier. A printer device can be selected via the "::printer" property.

       The capabilities of the selected printer can be adjusted via "setup_dialog()" method, that
       invokes a system-provided ( or, in case of Prima::PS::Printer, 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.

       Some printer capabilities can be queried by the "::size()" property, that reports the
       dimension of the page, the "::resolution()" property, that reports the DPI resolution
       selected by a printer driver and font list ( by "fonts()" method ), available for usage.

       Typical code that prints the document looks like

          my $p = $::application-> get_printer;
          if ( $p-> begin_doc) {
             ... draw ...
             $p-> end_doc;
          } else {
             print "failed:$@\n";
          }

       In addition, a standard package Prima::PrintDialog can be recommended so the user can
       select a printer device and adjust its setup interactively.

API

   Properties
       printer STRING
           Selects a printer device, specified by its STRING identifier.  Can not select a device
           if a printing session is started.

       resolution X, Y
           A read-only property; returns a DPI horizontal and vertical resolution, currently
           selected for a printer device. The user can change this, if the printer device
           supports several resolutions, inside "setup_dialog()".

       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 "setup_dialog()".

   Methods
       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 "abort_doc()" is called, so some information could still been
           printed.

       begin_doc DOCUMENT_NAME = ""
           Initiates the printing session, and triggers the object into the enabled painting
           state. The document is assigned DOCUMENT_NAME string identifier.

           Returns success flag; if failed, $@ contains the error.

       begin_paint
           Identical to "begin_doc("")" call.

       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 "new_page()" and
           "abort_doc()" methods work. The information mode is exited via "end_paint_info()"
           method.

       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.

       end_paint
           Identical to "abort_doc()".

       end_paint_info
           Quits the information painting mode, initiated by "begin_paint_info()" and returns the
           object into the disabled painting state.

       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.

       fonts NAME = '', ENCODING = ''
           Returns hash of font hashes ( see Prima::Drawable, Fonts section ) describing fonts of
           NAME font family and of ENCODING. If NAME is '' or "undef", returns one fonts hash for
           each of the font families that match the ENCODING string. If ENCODING is '' or
           "undef", no encoding match is performed.  If ENCODING is not valid ( not present in
           "font_encodings" result), it is treated as if it was '' or "undef".

           In the special case, when both NAME and ENCODING are '' or "undef", each font metric
           hash contains element "encodings", that points to array of the font encodings,
           available for the fonts of NAME font family.

       new_page
           Finalizes the current page and starts a new blank page.

           Returns success flag; if failed, $@ contains the error.

       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.

           The compatibility between options and values used by different OSes is low here.  The
           only fully compatible options are

           - "Orientation"["Portrait | Landscape"]
           - "Color"["Color | Monochrome"]
           - "Copies"["integer"]
           - "PaperSize"["Ainteger | Binteger | Executive | Folio | Ledger | Legal | Letter |
           Tabloid"].

           The other options are OS-dependant. For win32, consult Microsoft manual on DEVMODE
           structure <http://msdn.microsoft.com/library/en-us/gdi/prntspol_8nle.asp>; for Prima's
           own PostScript printer, consult Prima::PS::Printer.

       printers
           Returns array of hashes, where each entry describes a printer device.  The hash
           consists of the following entries:

           name
               A printer device name

           device
               A physical device name, that the printer is connected to

           defaultPrinter
               A boolean flag, 1 if the printer is default, 0 otherwise.

       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.

       get_default_printer
           Returns a string, identifying a default printer device.

       get_handle
           Returns a system handle for a printer object.

AUTHOR

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

SEE ALSO

       Prima, Prima::Drawable, Prima::PS::Printer