NAME

Prima::Printer - 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

The Prima::Printer class is a descendant of the 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. A Prima::Printer object is created only when the system provides the graphic printing capabilities, ie drawing and painting procedures on a printer device. If there are no such API, Prima::Application creates an instance of the Prima::PS::Printer class instead, which emulates a graphic device, and can produce PostScript and PDF output. The difference between the Prima::Printer and the Prima::PS::Printer class is almost nonexistent for both the user and the programmer unless printer device-specific adjustments are needed.

A printing session is started by calling the begin_doc() method which switches the printer object into the painting state. If the session is finished by the end_doc() call then the document is duly delivered to the selected printer device. The alternative finishing method, abort_doc(), terminates the printing session with no information printed, unless the document is multi-paged and pages are already sent to the printer via the new_page() method call.

A printer object ( that means, derived from either Prima::Printer or Prima::PS::Printer ) provides a mechanism that allows the selection of the printer. The printers() method returns an array of hashes, each describing a printer device. The get_default_printer() method returns the default printer string identifier. The printer device can be selected by calling the ::printer property.

The capabilities of the selected printer can be adjusted via the setup_dialog() method which invokes the system-provided ( or, in the case of Prima::PS::Printer, toolkit-provided ) printer setup dialog so the user can adjust the settings of the printer device. It depends on the system, whether the setup changes only the instance settings, or the default behavior of the printer driver affecting every program.

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

A typical code that prints the document looks like this:

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

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

API

Properties

printer STRING

Selects the printer device specified by its STRING identifier. Cannot select a device if a printing session is started.

resolution X, Y

A read-only property; returns the horizontal and vertical resolutions in DPI currently selected for the printer device. The user can change this setting, if the printer device supports several resolutions, inside the call of the setup_dialog() method.

size WIDTH, HEIGHT

A read-only property; returns the dimensions of the printer device page. The user can change this setting, if the printer device supports several resolutions or page formats, inside the call of the setup_dialog() method.

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 have been printed.

begin_doc DOCUMENT_NAME = ""

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

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

begin_paint

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

end_doc

Ends the printing session and delivers the document to the printer device. Does not report eventual errors that occurred during the spooling process - the system is expected to take care of 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 to the disabled painting state.

font_encodings

Returns an array of the 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 a hash of font hashes ( see Prima::Drawable, Fonts section ) describing fonts from the NAME font family with the ENCODING encoding. If the NAME is '' or undef, returns one font hash for each of the font families that match the ENCODING string. If ENCODING is '' or undef, no encoding match is performed. If the ENCODING is not valid ( not present in the 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 the element encodings, which points to an array of the font encodings, available for the fonts of the NAME font family.

new_page

Finalizes the current page and starts a new blank page.

Returns the 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 the list of options the printer supports. If called with one parameter, treats it as the option name and return the corresponding value. Otherwise, treats parameters as a list of key-value pairs, and changes the printer options. Returns the number of the options that were successfully set.

The compatibility between the options and the values used by different OSes is low. The only fully compatible options are Orientation[Portrait|Landscape], Color[Color|Monochrome], Copies[integer], and PaperSize[Ainteger|Binteger|Executive|Folio|Ledger|Legal|Letter|Tabloid]. The other options are OS-dependent. For win32, consult Microsoft manual on the DEVMODE structure https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-devmodew for Prima's own PostScript printer, consult Prima::PS::Printer.

printers

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

name

The printer device's name

device

The physical device name, that the printer is connected to

defaultPrinter

The boolean flag, is 1 if the printer is default, is 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 the string identifying the default printer device.

get_handle

Returns the system handle for the printer object.

AUTHOR

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

SEE ALSO

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