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

FreeBSD Manual Pages

  
 
  

home | help
PDF::API2::Simple(3)  User Contributed Perl Documentation PDF::API2::Simple(3)

NAME
       PDF::API2::Simple - Simplistic wrapper for the excellent	PDF::API2
       modules

SYNOPSIS
	   use PDF::API2::Simple;

	   my $pdf = PDF::API2::Simple->new(
					    file => 'output.pdf'
					   );

	   $pdf->add_font('VerdanaBold');
	   $pdf->add_font('Verdana');
	   $pdf->add_page();

	   $pdf->link( 'http://search.cpan.org', 'A Hyperlink',
		       x => 350,
		       y => $pdf->height - 150 );

	   for (my $i =	0; $i <	250; $i++) {
		my $text = "$i - All work and no play makes Jack a dull	boy";

		$pdf->text($text, autoflow => 'on');
	   }

	   $pdf->save();

       Take note that PDF coordinates are not quite what you're	used to. The
       coordinate, (0, 0) for instance is at the lower-left hand corner. Thus,
       x still grows to	the right, but y grows towards the top.

METHODS
   new
	    PDF::API2::Simple->new(
			'file' => 'output.txt',
			'width'	=> 612,
			'height' => 792,
			'line_height' => 10,
			'margin_left' => 20,
			'margin_top' =>	20,
			'margin_right' => 20,
			'margin_bottom'	=> 50,
			'width_right' => 0,
			'height_bottom'	=> 0,
			'effective_width' => 0,
			'effective_height' => 0,
			'header' => undef,
			'footer' => undef,
	    );

       Creates a new PDF::API2::Simple instance. A good	strategy is to create
       a new object for	each pdf file you want to create. That is, of course,
       up to you.

       o   file	- The PDF file you want	to write to. No	default, parameter
	   required

       o   width - The width of	the PDF	file. Defaults to 612, the 8 1/2 x 11
	   US Letter width

       o   height - The	height of the PDF file.	Defaults to 792, the 8 1/2 x
	   11 US Letter	height

       o   line_height - The standard height you want to define	for lines. The
	   default is 10

       o   margin_left - The amount of margin space you	want on	the left side.
	   Of course, you can specify whatever coordniates you want. Default
	   is 20

       o   margin_top -	The amount of margin space you want on the top of each
	   page. Default is 20

       o   margin_right	- The amount of	margin space you want of the right
	   side	of each	page. Default is 20

       o   margin_bottom - The amount of margin	space you want on the bottom
	   of each page. Default is 50

       o   width_right - A convenience property	that contains the furthest x
	   of the page,	accounting for the margins specified

       o   height_bottom - A convenience property that contains	the largest
	   "y" of the page, accounting for the bottom margin

       o   effective_width - A convenience property that contains the width of
	   the page, after the left and	right margin have been accounted for

       o   effective_height - A	convenience property that contains the height
	   of the page,	after the top and bottom margin	have been accounted
	   for

       o   header - This "CODE"	reference will be called everytime a page is
	   appended to the PDF,	allowing you to	specifiy a header for your
	   pages

       o   footer - This "CODE"	reference will be called everytime a page is
	   ended, allowing you to specifiy a footer for	your pages

   open
	 PDF::API2::Simple->open(
		     'open_file' => 'my_pdf.pdf',
		     'open_page' => 1,		    # Default is 1.
		     # Any other options to new.
	 );

       This method opens an existing PDF for editing. You can include any
       other arguments that are	valid for "new"	and they will be set in	the
       resulting object.

   Space Management
       The following methods help you to manage	the space on each page of your
       PDF.

       next_line_would_extend_page

       Returns a true value if the current "y" minus "line_height" would write
       past the	bottom margin.

       would_extend_page "theoretical_y"

       Returns a true value if the "theoretical_y" would write past the	bottom
       margin.

       next_line

       Reduces the current "y" by "line_height".

       add_page

       Closes the current page,	resets the "x" and "y" values to thier default
       coordinates, and	calls the header callback, if specified. This method
       may be called for in, such as if	your autoflow text wraps over a	page.

       end_page

       Closes the current page,	and calls the footer callback, if specified.
       This method is usually called for you.

   General Management
       These methods help you manage the PDF itself

       add_font	"font_name"

       This method will	add a font to be used throughout the PDF. You "MUST"
       call this at least once before laying out your PDF. "font_name" is a
       font name, such as 'Arial', or 'Verdana'. Appending 'Bold' seems	to
       make the	text bold, as in 'VerdanaBold'.	Refer to PDF::API2 for more
       details.

       You can optionally pass a font object and font size if you have loaded
       an external font.

	 my $font_obj =	$pdf->pdf->ttfont('new_font.ttf');
	 $pdf->add_font('NewFont', $font_obj, '12');

       Refer to	PDF::API2 for the various font methods,	like "ttfont",
       available.

       set_font	"font_name"[, "pt"]

       Set the current font by name, and optionally a font size.

       as_string

       An alias	for the	stringify method

       stringify

       Ends the	current	page, and returns the pdf as a string

       save ["file"]

       End the current page, and save the document to the file argument, or
       the file	specified when instaniating the	object.	If not suitable	file
       can be found to save in,	a "Carp::croak"	is emitted. Aliases for	this
       method are "saveas" and "save_as".

   Layout
       These methods modify the	actual layout of the PDF. Note that most of
       these methods set some internal state. Most often, the last "x" and "y"
       are set after the rendered object.

       Most times, underscores may be stripped and the arguments will still
       work, such as is	the difference between "fill_color", and "fillcolor".

       popup "text"[, %opts]

       Creates a 25x25 box at "opts{x}"	(or the	current	"x"), "opts{y}"	(or
       the current "y")	to represent an	annotation at that point. The user may
       then click that icon for	a full annotation.

       url

       This is an alias	for the	"link" method.

       link "url", "text"[, %opts]

       Specifies a link	to "url", having "text". %opts may contain:

       o   "x" - The x position	of the link. Defaults to "x".

       o   "y" - The y position	of the link. Defaults to "y".

       o   "limit" - The amount	to "limit" the text. This will add an ellipis
	   (...) a few characters from the end if the text length is greater
	   than	this numerical value. Defaults to 0, which is to mean "do not
	   limit".

       o   "align" - Which alignment you want for your text. The choices are
	   'left', 'center', and 'right'. Defaults to 'left'.

       o   "font" - Specifies via font name, the font to use. This sets	the
	   current font.

       o   "font_size" - Specifies the font size. This sets the	current	font
	   size.

       o   "fill_color"	- Specifies the	fill color. This sets the current fill
	   color.

       o   "stroke_color" - Specifies the stroke color.	This sets the current
	   stroke color.

       This method returns the width of	the text.

       text "text"[, %opts]

       Renders text onto the PDF.

       o   "x" - The x position	of the link. Defaults to "x".

       o   "y" - The y position	of the link. Defaults to "y".

       o   "limit" - The amount	to "limit" the text. This will add an ellipis
	   (...) a few characters from the end if the text length is greater
	   than	this numerical value. Defaults to 0, which is to mean "do not
	   limit".

       o   "align" - Which alignment you want for your text. The choices are
	   'left', 'center', and 'right'. Defaults to 'left'.

       o   "autoflow" -	Any value but 'off' will notify	this method to use
	   "autoflowing" heuristics to gracefully wrap your text over lines
	   and pages. Useful for variable length text. Note that due to
	   laziness, this option is mutually exclusive with "limit".

       o   "font" - Specifies via font name, the font to use. This sets	the
	   current font.

       o   "font_size" - Specifies the font size. This sets the	current	font
	   size.

       o   "fill_color"	- Specifies the	fill color. This sets the current fill
	   color.

       o   "stroke_color" - Specifies the stroke color.	This sets the current
	   stroke color.

       If "autoflow" was not specified,	this method returns the	width of the
       text in scalar context, the bounding box	of the text in list context.
       In autoflow mode, this method returns nothing.

       image "src"[, %opts]

       Renders an image	onto the PDF. The following image types	are supported:
       JPG, TIFF, PNM, PNG, GIF, and PDF. Note that the	module determines the
       image type by file extension.

       o   "x" - The x position	of the link. Defaults to "x".

       o   "y" - The y position	of the link. Defaults to "y".

       o   "width" - The width of the image. Defaults to 100.

       o   "height" - The height of the	image. Defaults	to 100.

       o   "scale" - Amount to scale the image.	Defaults to 1. (only available
	   for PDF types)

       line [, %opts]

       Renders a line onto the PDF.

       o   "x" - The x position	of the line. Defaults to "x".

       o   "y" - The y position	of the line. Defaults to "y".

       o   "to_x" - The	x position where to draw the line to.

       o   "to_y" - The	y position where to draw the line to.

       o   "fill_color"	- Specifies the	fill color. This sets the current fill
	   color. Defaults to "current_fill_color".

       o   "stroke_color" - Specifies the stroke color.	This sets the current
	   stroke color. Defaults to "current_stroke_color".

       o   "width" - Specifies the width of the	line. Defaults to 0.5.

       rect [, %opts]

       Renders a rectangle onto	the PDF. Rectangles are	usually	drawn
       specifying two coordinates diagonal from	each other. (5,	5) to (30, 30)
       for example, would produce a 25 x 25 square.

       o   "x" - The x position	of the rect. Defaults to "x".

       o   "y" - The y position	of the rect. Defaults to "y".

       o   "to_x" - The	x position where to draw the rect to.

       o   "to_y" - The	y position where to draw the rect to.

       o   "stroke" - A	value of 'on', 'true', or 'yes'	will enable the
	   stroke. Defaults to 'on'.

       o   "fill" - A value of 'on', 'true', or	'yes' will enable the fill.
	   Defaults to 'off'.

       o   "fill_color"	- Specifies the	fill color. This sets the current fill
	   color. Defaults to "current_fill_color".

       o   "stroke_color" - Specifies the stroke color.	This sets the current
	   stroke color. Defaults to "current_stroke_color".

       o   "width" - Specifies the width of the	line. Defaults to 0.5.

PROPERTIES
       The following properties	are read/write,	and may	be used	as $pdf->prop
       to read,	$pdf->prop('val') to set.

   header
       Gets/sets the header callback.

   footer
       Gets/sets the footer callback.

   file
       Gets/sets the file used to save the PDF.	It's recommended that you do
       not set this.

   width
       Gets/sets the width of the current page.	It's recommended that you do
       not set this.

   height
       Gets/sets the height of the current page. It's recommended that you do
       not set this.

   line_height
       Gets/sets the default line height. This is used in most space layout
       methods.

   margin_left
       Gets/sets the left margin.

   margin_top
       Gets/sets the top margin.

   margin_right
       Gets/sets the right margin.

   margin_bottom
       Gets/sets the bottom margin.

   width_right
       Gets/sets the calculated	value, "width" - "margin_right"

   height_bottom
       Gets/sets the calculated	value, "height"	- "margin_bottom"

   effective_width
       Gets/sets the calculated	value, "width" - ("margin_left"	+
       "margin_right")

   effective_height
       Gets/sets the calculated	value, "height"	- ("margin_top"	+
       "margin_bottom")

   current_page
       Gets/sets the current page object. It's hard to find a good reason to
       set this, but it	is possible to do so.

   pdf
       Gets/sets the raw PDF::API2 object. This	allows you great flexibility
       in your applications.

   fonts
       Gets/sets the array of fonts we have been storing via the "add_font"
       method.

   current_font
       Gets/sets the current font.

   current_font_size
       Gets/sets the current font size.

   current_stroke_color
       Gets/sets the current stroke color. Aliases for this method are
       "stroke_color", and "strokecolor"

   current_fill_color
       Gets/sets the current fill color. Aliases for this method are
       "fontcolor", "set_font_color", "font_color", "fillcolor", and
       "fill_color".

   x
       Gets/sets the current x position.

   y
       Gets/sets the current y position.

BUGS / FIXES
       Please mail all bug reports, fixes, improvements, and suggestions to
       bugs -at- redtreesystems	-dot- com.

PLUG AND LICENSE
       This project belongs to Red Tree	Systems, LLC -
       <http://www.redtreesystems.com>,	but is placed into the public domain
       in the hopes that it will be educational	and/or useful. Red Tree
       Systems,	LLC requests that this section be kept intact with any
       modification of this module, or derivitive work thereof.

THANKS
       Thanks to Jim Brandt for	noting that the	default	values didn't do well
       with false values.

       Thanks to Denis Evdokimov for submitting	more margin-fixing goodness.

       Thanks to Jonathan A. Marshall for fixing a long	standing margin	issue,
       and pointing out	further	documentation shortcomings.

       Thanks to Jim Brandt for	the open method, contributing code to
       add_font, and offering beer.

       Thanks to Pradeep N Menon and Alfred Reibenschuh	for pointing out
       optimizaiton issues, and	helping	to resolve them.

       Thanks to Simon Wistow for uncovering several bugs and offering up
       code.

       Thanks to Bryan Krone for pointing out our documentation	shortcomings.

SEE ALSO
       PDF::API2

       There is	an examples folder with	this dist that should help you get
       started.	You may	contact	pdfapi2simple -AT- redtreesystems _dot_	com
       for support on an individual or commercial basis.

perl v5.24.1			  2013-10-02		  PDF::API2::Simple(3)

NAME | SYNOPSIS | METHODS | PROPERTIES | BUGS / FIXES | PLUG AND LICENSE | THANKS | SEE ALSO

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

home | help