Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pod::Prima::Printer(3)User Contributed Perl Documentatiopod::Prima::Printer(3)

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"],	and
	   "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

perl v5.24.1			  2014-09-03		pod::Prima::Printer(3)

NAME | SYNOPSIS | DESCRIPTION | Usage | API | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pod::Prima::Printer&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help