Man Linux: Main Page and Category List


       Prima::Printer - system printing services


          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";


       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.


       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"

       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


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

           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

       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.

           Identical to "begin_doc("")" call.

           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.

           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

           Identical to "abort_doc()".

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

           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

           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
           for Prima’s own PostScript printer, consult Prima::PS::Printer.

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

               A printer device name

               A physical device name, that the printer is connected to

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

           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.

           Returns a string, identifying a default printer device.

           Returns a system handle for a printer object.


       Dmitry Karasik, <>.


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