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.

• file - The PDF file you want to write to. No default, parameter required
• width - The width of the PDF file. Defaults to 612, the 8 1/2 x 11 US Letter width
• height - The height of the PDF file. Defaults to 792, the 8 1/2 x 11 US Letter height
• line_height - The standard height you want to define for lines. The default is 10
• 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
• margin_top - The amount of margin space you want on the top of each page. Default is 20
• margin_right - The amount of margin space you want of the right side of each page. Default is 20
• margin_bottom - The amount of margin space you want on the bottom of each page. Default is 50
• width_right - A convenience property that contains the furthest x of the page, accounting for the margins specified
• height_bottom - A convenience property that contains the largest "y" of the page, accounting for the bottom margin
• effective_width - A convenience property that contains the width of the page, after the left and right margin have been accounted for
• effective_height - A convenience property that contains the height of the page, after the top and bottom margin have been accounted for
• header - This "CODE" reference will be called everytime a page is appended to the PDF, allowing you to specifiy a header for your pages
• 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

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

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

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:

• "x" - The x position of the link. Defaults to "x".
• "y" - The y position of the link. Defaults to "y".
• "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".
• "align" - Which alignment you want for your text. The choices are 'left', 'center', and 'right'. Defaults to 'left'.
• "font" - Specifies via font name, the font to use. This sets the current font.
• "font_size" - Specifies the font size. This sets the current font size.
• "fill_color" - Specifies the fill color. This sets the current fill color.
• "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.

• "x" - The x position of the link. Defaults to "x".
• "y" - The y position of the link. Defaults to "y".
• "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".
• "align" - Which alignment you want for your text. The choices are 'left', 'center', and 'right'. Defaults to 'left'.
• "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".
• "font" - Specifies via font name, the font to use. This sets the current font.
• "font_size" - Specifies the font size. This sets the current font size.
• "fill_color" - Specifies the fill color. This sets the current fill color.
• "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.

• "x" - The x position of the link. Defaults to "x".
• "y" - The y position of the link. Defaults to "y".
• "width" - The width of the image. Defaults to 100.
• "height" - The height of the image. Defaults to 100.
• "scale" - Amount to scale the image. Defaults to 1. (only available for PDF types)

line [, %opts]

Renders a line onto the PDF.

• "x" - The x position of the line. Defaults to "x".
• "y" - The y position of the line. Defaults to "y".
• "to_x" - The x position where to draw the line to.
• "to_y" - The y position where to draw the line to.
• "fill_color" - Specifies the fill color. This sets the current fill color. Defaults to "current_fill_color".
• "stroke_color" - Specifies the stroke color. This sets the current stroke color. Defaults to "current_stroke_color".
• "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.

• "x" - The x position of the rect. Defaults to "x".
• "y" - The y position of the rect. Defaults to "y".
• "to_x" - The x position where to draw the rect to.
• "to_y" - The y position where to draw the rect to.
• "stroke" - A value of 'on', 'true', or 'yes' will enable the stroke. Defaults to 'on'.
• "fill" - A value of 'on', 'true', or 'yes' will enable the fill. Defaults to 'off'.
• "fill_color" - Specifies the fill color. This sets the current fill color. Defaults to "current_fill_color".
• "stroke_color" - Specifies the stroke color. This sets the current stroke color. Defaults to "current_stroke_color".
• "width" - Specifies the width of the line. Defaults to 0.5.

header

footer

file

width

height

line_height

margin_left

margin_top

margin_right

margin_bottom

width_right

height_bottom

effective_width

effective_height

current_page

pdf

fonts

current_font

current_font_size

current_stroke_color

current_fill_color

x

y