NAME

PDFLib - More OO interface to pdflib_pl.pm

SYNOPSIS

  use PDFLib;
  my $pdf = PDFLib->new("foo.pdf");

DESCRIPTION

A cleaner API than pdflib_pl.pm, which is a very low-level (non-OO) interface.

PDFLib API

new(...)

Construct a new PDF object. No parameters required.

Parameters are passed as name/value pairs (i.e. a hash):

filename: A filename to save the PDF to. If not supplied the PDF will be generated in memory.
papersize: 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".
creator: The creator of the document.
author: The author of the document
title: The title of the document
orientation: The orientation of the pages. This defaults to "portrait".

Example:

  my $pdf = PDFLib->new(creator => "My PDF Program",
        author => "Me",
        title => "Business Report");

finish

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.

delete

Only call this if you are manually calling finish() also. It deletes the used memory for this PDF.

get_buffer

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.

filename(...)

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.

info(key => value)

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.

orientation(...)

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_page(...)

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_page

End the current page. It should not normally be necessary to call this, however you may need it if you wish to load an image after you have called start_page (images must be loaded when no pages are open)

set_font(...)

Set the current font being used. The parameters allowed are:

face

The font face to use. Best to choose from one of the builtin fonts:

  Courier
  Helvetica
  Symbol
  Times
  ZapfDingbats

size

The font size in points. This defaults to the current font size, or 10.0 point.

bold

Set to true to get a bold font - only supported for the builtin fonts listed above.

italic

Set to true to get an italicised font - only supported for the builtin fonts listed above.

encoding

One of "host" (default), "builtin", "winansi", "ebcdic", or "macroman".

See the pdflib documentation for more details.

embed

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.

string_width(text => $text)

Returns the width of the text in the current font face and size.

Alternatively pass in the following options:

face: The font face to use.
size: Text size in the current user coordinates.
bold: Use a bold font (works only for Courier, Helvetica and Times)
italic: Use an italic font (works only for Courier, Helvetica and Times)
encoding: See set_font above.
embed: See set_font above.

set_text_pos(x, y)

Sets the current text output position.

get_text_pos

Returns the current text output position as a list (x, y).

print($text)

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.

print_at($text, x => $x, y => $y)

Prints text at the given X and Y coordinates.

print_boxed($text, ...)

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 only problem with it is that you cannot change the font while printing into this kind of bounding box. Better to use "new_bounding_box" below.

The parameters you can pass are:

mode: One of "left", "right", "center", "justify" or "fulljustify".
blind: This parameter allows you to output invisible text. Useful for testing whether the text will fit into your bounding box.
x and y: The X and Y positions (bottom left hand corner) of your bounding box.
w and h: 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_line($text)

Print the text at the current output position, with a carriage return at the end.

get_value($key, [$modifier])

There are many values that you can retrieve from pdflib, all are covered in the extensive documentation. This method is a wrapper for that.

set_value($key => $value)

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.

get_parameter($param, [$modifier])

This is very similar to get_value above. No, I don't know why pdflib makes this distinction, before you ask :-)

set_parameter($param => $value)

Same again. See the pdflib docs for which options are available.

new_bounding_box(%params)

Creates a new BoundingBox (see below) that you can print into.

Example:

  my $bb = $pdf->new_bounding_box(
        x => 30, y => 800, w => 300, h => 800
    );
  $bb->print($long_text);
  $bb->finish; # MUST call this!

Valid parameters are:

x and y (required): The x and y coordinates of the start of the bounding box.
w and h (required): The width and height of the bounding box.
align (default = 'left'): The alignment of the text in the bounding box. Can be "centre", or "center" (for the Americans), or "right" or "left".
wrap (default = 1): Whether or not to automatically wrap the text. At the moment this will automatically wrap at whitespace only. It will not do any fancy hyphenation or justification. If you turn wrapping off, you are expected to do your own wrapping using either newlines, or print_line.

load_image(...)

Load an image. Parameters available are:

filetype: One of "png", "gif", "jpeg", or "tiff". Unfortunately PDFLib does not do filetype sniffing, yet.
filename: The name of the image file to open.
stringparam and intparam: See the pdflib documentation for PDF_open_image for more details.

This returns a PDFLib::Image object.

add_image(...)

Add an image to the current page (or creates a new page if necessary).

Options are passed as name/value pairs. Available options are:

img: The PDFLib::Image object, returned from load_image() above.
x: The x coordinate
y: The y coordinate
scale: The scaling of the image. This defaults to 1.0.
scale_x: Horizontal scaling.
scale_y: Vertical scaling.
w: The width.
h: The height.
Either specify scale or (scale_x and scale_y), or (w and h) or none.
dpi: The desired image DPI. If left out, uses the image's true DPI value, if available. Please Note: This is different than before, where all images were treated as having 72dpi. If your legacy application needs this behaviour and cannot easily be modified, set "$PDFLib::DPI = 72;".

add_bookmark(...)

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:

text

The text of the bookmark

parent_of

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");
  my $next_bm = $pdf->add_bookmark(text => "Child Bookmark",
                                   parent_of => $root_bm);

open

Whether this bookmark is expanded in the tree view by default when the PDF is first opened.

add_link(...)

Turns a square area of the page into a web link. Takes the following parameters:

x, y, w, h: X and Y coordinates of the lower left hand side of the box, and width and height of the box.
link: The actual link. Must start with one of "http:", "https:", "ftp:", or "mailto:".

set_border_style($style, $width)

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

Note: This will not help broken linux clients like xpdf and gv (or other viewers based on ghostscript) which display a border around links anyway, sadly.

Graphics Functions

Doing graphics in PDFLib is fairly easy, though there are some gotchas to watch out for. For example, using line_to() does not draw the line immediately - to finalize the line you have to call stroke(). This is because PDFLib allows you to instead call fill(), in case you wish to draw some funny shape and fill it in. Here's a quick example of drawing a line:

  $pdf->start_page;

  $pdf->move_to(20, 20);
  $pdf->line_to(400, 400);
  $pdf->stroke;

Which draws a line from the bottom left to the middle of the page.

All graphics calls must be accompanied by a call to either one of stroke, close_path_stroke, fill, fill_stroke, close_path_fill_stroke, clip, or end_path. (note this means you can have 1 or 4 or 36 graphics calls, and a single call to one of the above, but beware of the results).

set_dash(LIST)

Set the current dash pattern. The list should be an alternating black/white length. For example:

  $pdf->set_dash(3,1,4,2);

The dash is reset at the beginning of each new page.

set_flat($flatness)

Sets the flatness of lines.

Flatness describes the maximum distance (in device pixels) between the path and an approximation constructed from straight line segments.

(I don't really know what that means, explanations would be welcome!)

set_line_join

Sets the shape of the corners of paths that are stroked.

Pass in a single option, one of: "miter", "round", or "bevel".

Think of them like this:

 miter: \
         \
          >
         /
        /

 round: \
         \
          )
         /
        /

 bevel: \
         \
          |
         /
        /

set_line_cap

Sets the shape at the end of a path with respect to stroking.

Pass in a single option, one of: "butt_end", "round_end", or "square_end".

Think of them like this:

  butt_end   ----|

  round_end  ----)

  square_end ----] (protrudes line_width/2 beyond end point)

set_miter_limit($limit)

Sets the miter limit. See the pdflib manual for more information

set_line_width($width)

Set the current line width. $width is in units of the current user coordinate system.

reset_graphics

Resets all the graphics options to their defaults.

save_graphics_state

Save the current graphics state. Must be balanced by a restore_graphics_state().

save/restore graphics states can be nested, though at the moment it is up to you to ensure they balance on a page. This may be changed for some Perl magic in the future though.

restore_graphics_state

Restore the last saved graphics state.

move_to($x, $y)

Set the current point.

line_to($x, $y)

Draw a line from the current point to the coordinates specified.

bezier

Draw a bezier curve from the current point to (x3, y3), using the points (x1, y1) and (x2, y2) as control points. Parameters are passed as a hash:

  $pdf->bezier(
      x1 => 20, y1 => 20,
      x2 => 40, y1 => 0,
      x3 => 20, y1 => 60,
  );

circle

Draw a circle using parameters x, y and r (radius).

arc

Draw an arc. Parameters are:

x, y: The coordinates of the centre of the circular arc segment
r: The radius of the arc.
alpha, beta: The start and end angles of the arc.

rect

Draw a rectangle. Parameters are passed as a hash, and are simply x, y, w, h.

close_path

Close the current path.

This draws a line from the current point to the starting point of the subpath.

stroke

Draws the current path as line.

You must call this (or one of the path ending functions) or no line will be drawn.

close_path_stroke

Closes the path and strokes it.

fill

Fills the current path using the currently selected colour.

fill_stroke

Fills the current path and strokes it.

close_path_fill_stroke

Closes the current path, fills it, and strokes it.

clip

Uses the current path as a clipping region. Often useful in conjunction with save/restore_graphics_state.

end_path

Ends the path without doing anything.

Changing the Coordinate System

PDFLib allows you to alter the coordinate system in various ways while you are working. This is affected by save/restore_graphics_state, so it's always useful to wrap these methods around a save/restore block.

The most useful thing this allows you to do is draw shapes not listed above, like ellipses, parallelograms, etc.

coord_translate ($x, $y)

Translate the coordinate system by x, y

coord_scale ($xscale, $yscale)

Scale the coordinate system.

coord_rotate ($degrees)

Rotate the coordinate system the given number of degrees (0 - 360)

coord_skew ($xshear, $yshear)

Skew (or shear) the coordinate system by the number of degrees given in the X and Y directions.

coord_set_matrix (%params)

Set the current transformation matrix. This is heavy stuff - use the other functions instead unless you know what you're doing.

Params are a hash containing a, b, c, d, e and f entries.

coord_concat_matrix (%params)

Concatenate to the current transformation matrix.

Params are the same as coord_set_matrix.

Colour Functions

set_colour/set_color

This function allows you to set the current colour.

The color can be specified in a number of ways, but always as a hash parameter somehow. It is easiest to show using examples:

  # 40% grayscale.
  $pdf->set_color(gray => 0.4);

  $pdf->set_color(rgb => [$r, $g, $b]);

  $pdf->set_color(cmyk => [$c, $m, $y, $k]);

  # see make_spot_color below
  $pdf->set_color(spot => { handle => $h, tint => 0.3 });

  # see make_pattern below
  $pdf->set_color(pattern => $pattern);

You can also pass in a type parameter to set either the "stroke" or the "fill" colour, or "both". The default is "both":

  $pdf->set_color(type => 'stroke', gray => 0.5);

make_spot_color/make_spot_colour

Makes a named spot colour using the name passed as a parameter.

Useful for saving away the current colour to restore it later.

begin_patter

Starts a pattern. Parameters are passed as a hash of width, height, xstep, ystep, and painttype. See the pdflib manual for more details.

end_pattern

Finishes the current pattern.

PDFLib::Page

%Size

You can access the built-in page sizes directly via the %PDFLib::Page::Size hash. For example:

  my @a4 = @{ $PDFLib::Page::Size{a4} };

Which gives you a width and a height in the array. This can be useful for making sure you don't overstep the bounds of a page when drawing. See "Default Paper Sizes" below for the available sizes.

PDFLib::Image API

The following methods are available on the object returned from "$pdf-"load_image()> above.

width

Return the image's width in points.

height

Return the image's height in points.

PDFLib::BoundingBox

BoundingBox is a bounded printing API. You create a bounding box, then print into it, and it wraps and/or ensures you don't print outside of that box.

For details of bounding boxes, see "new_bounding_box" above.

When you are finished with a bounding box, you must call finish() on it so that it can clean up.

Also note that if you create subsequent bounding boxes one after the other, a font change on the bounding box will have effect on the next bounding box - it's transparently passed through to the page level. This is probably desirable (see the output of t/06bounding.t in the distribution for example).

print($text)

Returns the characters it could not fit into the bounding box, which is useful if you are doing multiple bounding boxes or pages.

Default Paper Sizes

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.

a0: 2380 x 3368
a1: 1684 x 2380
a2: 1190 x 1684
a3: 842 x 1190
a4: 595 x 842
a5: 421 x 595
a6: 297 x 421
b5: 501 x 709
letter: 612 x 792
legal: 612 x 1008
ledger: 1224 x 792
11x17: 792 x 1224
slides: 612 x 450

TODO

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.

AUTHOR

AxKit.com Ltd,

Matt Sergeant, matt@axkit.com

LICENSE

This is free software. You may distribute it under the same terms as Perl itself.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 516:: You forgot a '=back' before '=head2'