PDFLib - More OO interface to pdflib_pl.pm
use PDFLib; my $pdf = PDFLib->new("foo.pdf");
A cleaner API than pdflib_pl.pm, which is a very low-level (non-OO) interface.
Construct a new PDF object. No parameters required.
Parameters are passed as name/value pairs (i.e. a hash):
A filename to save the PDF to. If not supplied the PDF will be generated in memory.
The papersize can either be an array ref of [x, y], or can be a string containing one of the below listed paper sizes. This defaults to "a4".
The creator of the document.
The author of the document
The title of the document
The orientation of the pages. This defaults to "portrait".
Example:
my $pdf = PDFLib->new(creator => "My PDF Program", author => "Me", title => "Business Report");
Let PDFLib know you are finished processing this PDF. This method should not normally need to be called, as it is called automatically for you.
Only call this if you are manually calling finish() also. It deletes the used memory for this PDF.
If (and only if) you didn't supply a filename in the call to new(), then get_buffer will return to you the PDF as a string. Very useful for generating PDFs on the fly for a web server.
A getter and setter method for the PDF's filename. Pass in a filename as a string to set a new filename. returns the old filename.
A getter and setter method for the PDF info fields (such as Title, Creator, Author, etc). A key is required. If you pass in a value it will set the new value. Returns the old value.
A getter and setter for the current paper size. An optional value that can be an array ref of [x, y], or a string from the list of paper sizes below, will set the current paper size. Returns the old/current paper size.
A getter and setter for the current page orientation. All this really does is swap the x and y values in the paper size if orientation == "landscape". Returns the current/old orientation.
Start a new page. If a page has already been started, this will call end_page() automatically for you.
Options are passed in as name/value pairs, and are passed to PDFLib::Page->new() below.
End the current page. It should not normally be necessary to call this.
Set the current font being used. The parameters allowed are:
The font face to use. Best to choose from one of the 14 builtin fonts:
Courier Courier-Bold Courier-BoldOblique Courier-Oblique Helvetica Helvetica-Bold Helvetica-BoldOblique Helvetica-Oblique Symbol Times-Roman Times-Bold Times-BoldItalic Times-Italic ZapfDingbats
The font size in points. This defaults to 12.0
One of "host" (default), "builtin", "winansi", "ebcdic", or "macroman".
See the pdflib documentation for more details.
If set to a true value, this will embed the font in the PDF file. This can be useful if using fonts outside of the 14 listed above, but extra font metrics information is required and you will need to read the pdflib documentation for more information.
Sets the current text output position.
Returns the current text output position as a list (x, y).
Prints the text passed as a parameter to the current page (and creates a new page if there is no current page) at the current output position.
Note: this will not wrap, and text can and will fall off the edge of your page.
Prints text at the given X and Y coordinates.
This is perhaps the most interesting output method as it allows you to define a bounding box to put the text into, and PDFLib will wrap the text for you.
The parameters you can pass are:
One of "left", "right", "center", "justify" or "fulljustify".
This parameter allows you to output invisible text. Useful for testing whether the text will fit into your bounding box.
The X and Y positions (bottom left hand corner) of your bounding box.
The width and height of your bounding box.
Returns zero, or the number of characters from your text that would not fit into the box.
Print the text at the current output position, with a carriage return at the end.
There are many values that you can retrieve from pdflib, all are covered in the extensive documentation. This method is a wrapper for that.
PDFLib also allows you to set values. This method does just that. Note that not all values that you can "get" allow you to also "set" that value. Read the pdflib documentation for more information on values you can set.
This is very similar to get_value above. No, I don't know why pdflib makes this distinction, before you ask :-)
Same again. See the pdflib docs for which options are available.
Load an image. Parameters available are:
One of "png", "gif", "jpeg", or "tiff". Unfortunately PDFLib does not do filetype sniffing, yet.
The name of the image file to open.
See the pdflib documentation for PDF_open_image for more details.
This returns a PDFLib::Image object.
Add an image to the current page (or creates a new page if necessary).
Options are passed as name/value pairs. Available options are:
The PDFLib::Image object, returned from load_image() above.
The x coordinate
The y coordinate
The scaling of the image. Note that only full scaling is possible, not separate X and Y scaling. This defaults to 1.0.
Adds a bookmark to the PDF file (normally displayed in a tree view on the left hand side of the pages in Adobe acrobat reader). Takes the following parameters:
The text of the bookmark
The parent bookmark for generating hierarchies. This should be a value returned from a previous call to add_bookmark, e.g.
my $root_bm = $pdf->add_bookmark(text => "My Root Bookmark"); $pdf->add_bookmark(text => "Child Bookmark", parent_of => $root_bm);
Whether this bookmark is expanded by default when the PDF is first opened.
Turns a square area of the page into a web link. Takes the following parameters:
X and Y coordinates of the lower left hand side of the box, and width and height of the box.
The actual link. Must start with one of "http:", "https:", "ftp:", or "mailto:".
The border in question here is a border around a link. Style must be one of "solid" or "dashed". Note that links have a border around them by default, so you need to unset that with:
$pdf->set_border_style("solid", 0);
Unless you want all your links to have ugly boxes around them.
The following methods are available on the object returned from load_image above.
Return the image's width in points.
Return the image's height in points.
The following paper sizes are available. Units are in "points". Any of these can be rotated by providing an orientation of "landscape". Alternate paper sizes can be used by passing an array ref of [x, y] to anything requiring a papersize, but that generally shouldn't be necessary.
2380 x 3368
1684 x 2380
1190 x 1684
842 x 1190
595 x 842
421 x 595
297 x 421
501 x 709
612 x 792
612 x 1008
1224 x 792
792 x 1224
612 x 450
Lots more of the pdflib API needs to be added and tested here. Notably the support for other types of attachments, and support for all of the graphics primatives.
AxKit.com Ltd,
Matt Sergeant, matt@axkit.com
This is free software. You may distribute it under the same terms as Perl itself.
To install PDFLib, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDFLib
CPAN shell
perl -MCPAN -e shell install PDFLib
For more information on module installation, please visit the detailed CPAN module installation guide.