=head1 NAME
Prima::Printer - printing services
=head1 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) ?
$p-> end_doc :
$p-> abort_doc;
} else {
print "failed:$@\n";
}
=head1 DESCRIPTION
The I<Prima::Printer> class is a descendant of the I<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 I<Prima::PS::Printer> is used instead.
=head1 Usage
I<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 I<Prima::Application>. A I<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,
I<Prima::Application> creates an instance of the I<Prima::PS::Printer> class
instead, which emulates a graphic device, and can produce PostScript and
PDF output. The difference between the I<Prima::Printer> and the
I<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 C<begin_doc()> method which
switches the printer object into the painting state. If the session is finished by
the C<end_doc()> call then the document is duly delivered to the selected
printer device. The alternative finishing method, C<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 C<new_page()>
method call.
A printer object ( that means, derived from either I<Prima::Printer> or
I<Prima::PS::Printer> ) provides a mechanism that allows the selection of the
printer. The C<printers()> method returns an array of hashes, each describing a
printer device. The C<get_default_printer()> method returns the default printer
string identifier. The printer device can be selected by calling the
C<::printer> property.
The capabilities of the selected printer can be adjusted via the
C<setup_dialog()> method which invokes the system-provided ( or, in the case of
I<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 C<::size()> property
that reports the dimension of the page, the C<::resolution()> property that
reports the DPI resolution selected by the printer driver, and the list of
available fonts ( by the C<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 I<Prima::Dialog::PrintDialog> can berecommended so the user can select a printer device and adjust its setup
interactively.
=head1 API
=head2 Properties
=over
=item printer STRING
Selects the printer device specified by its STRING identifier.
Cannot select a device if a printing session is started.
=item 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
C<setup_dialog()> method.
=item 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 C<setup_dialog()> method.
=back
=head2 Methods
=over
=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 C<abort_doc()> is called, so some
information could still have been printed.
=item 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, C<$@> contains the error.
=item begin_paint
Identical to the C<begin_doc("")> call.
=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 the
C<new_page()> and C<abort_doc()> methods work. The information mode is exited
via the C<end_paint_info()> method.
=item 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.
=item end_paint
Identical to C<abort_doc()>.
=item end_paint_info
Quits the information painting mode initiated by C<begin_paint_info()>
and returns the object to the disabled painting state.
=item 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.
=item fonts NAME = '', ENCODING = ''
Returns a hash of font hashes ( see L<Prima::Drawable>, Fonts section )
describing fonts from the NAME font family with the ENCODING encoding. If the
NAME is '' or C<undef>, returns one font hash for each of the font families
that match the ENCODING string. If ENCODING is '' or C<undef>, no encoding
match is performed. If the ENCODING is not valid ( not present in the
C<font_encodings> result), it is treated as if it was '' or C<undef>.
In the special case, when both NAME and ENCODING are '' or C<undef>, each font
metric hash contains the element C<encodings>, which points to an array of the font
encodings, available for the fonts of the NAME font family.
=item new_page
Finalizes the current page and starts a new blank page.
Returns the success flag; if failed, C<$@> contains the error.
=item 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
C<Orientation>[C<Portrait|Landscape>], C<Color>[C<Color|Monochrome>],
C<Copies>[C<integer>], and
C<PaperSize>[C<AI<integer>|BI<integer>|Executive|Folio|Ledger|Legal|Letter|Tabloid>].
The other options are OS-dependent. For win32, consult Microsoft manual on the
DEVMODE structure
for Prima's own PostScript printer, consult L<Prima::PS::Printer>.
=item printers
Returns an array of hashes where each entry describes a printer device.
The hash consists of the following entries:
=over
=item name
The printer device's name
=item device
The physical device name, that the printer is connected to
=item defaultPrinter
The boolean flag, is 1 if the printer is default, is 0 otherwise.
=back
=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.
=item get_default_printer
Returns the string identifying the default printer device.
=item get_handle
Returns the system handle for the printer object.
=back
=head1 AUTHOR
Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.
=head1 SEE ALSO
L<Prima>, L<Prima::Drawable>, L<Prima::PS::Printer>