pod::Pr...:Printer(3)

okay so this is pod::Pr...:Printer(3) — the User Contributed Perl Documentation page for Prima::Printer — and bestie, it’s literally all about printing services 💅✨

🌸 NAME 🌸

Prima::Printer — printing services 🖨️💖

✨ SYNOPSIS ✨

Here’s the whole vibe in code form, bestie — copy it exactly, no cap:

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 🦋

okay so Prima::Printer is a descendant of the Prima::Drawable class — iconic lineage behavior 👑. 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 — not me trying to new one 🙈. 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, i.e. 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 🔥

here’s the actual API, bestie — every property and method is below, no skips 🫶 periodt 💅

💖 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 and 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 new_page() nor abort_doc() works. 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

okay that’s the whole page, bestie 🫶💖 — this pod::Pr...:Printer(3) page comes from perl v5.42.0, dated 2024-08-20. mwah 💋✨