Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

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

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


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.

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 the PDF::API2 manpage 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 the PDF::API2 manpage 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:

This method returns the width of the text.

text text[, %opts]

Renders text onto the PDF.

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.

line [, %opts]

Renders a line onto the PDF.

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.


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 the PDF::API2 manpage 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 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

the PDF::API2 manpage

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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy