NAME

PDF::Create - create PDF files

SYNOPSIS

    use PDF::Create;

    my $pdf = new PDF::Create('filename'     => 'mypdf.pdf',
			      'Version'      => 1.2,
			      'PageMode'     => 'UseOutlines',
			      'Author'       => 'Fabien Tassin',
			      'Title'        => 'My title',
			      'CreationDate' => [ localtime ],
			 );
    my $root = $pdf->new_page('MediaBox' => [ 0, 0, 612, 792 ]);

    # Add a page which inherits its attributes from $root
    my $page = $root->new_page;

    # Prepare 2 fonts
    my $f1 = $pdf->font('Subtype'  => 'Type1',
 	   	        'Encoding' => 'WinAnsiEncoding',
 		        'BaseFont' => 'Helvetica');
    my $f2 = $pdf->font('Subtype'  => 'Type1',
 		        'Encoding' => 'WinAnsiEncoding',
 		        'BaseFont' => 'Helvetica-Bold');

    # Prepare a Table of Content
    my $toc = $pdf->new_outline('Title' => 'Document',
                                'Destination' => $page);
    $toc->new_outline('Title' => 'Section 1');
    my $s2 = $toc->new_outline('Title' => 'Section 2',
                               'Status' => 'closed');
    $s2->new_outline('Title' => 'Subsection 1');

    $page->stringc($f2, 40, 306, 426, "PDF::Create");
    $page->stringc($f1, 20, 306, 396, "version $PDF::Create::VERSION");

    # Add another page
    my $page2 = $root->new_page;
    $page2->line(0, 0, 612, 792);
    $page2->line(0, 792, 612, 0);

    $toc->new_outline('Title' => 'Section 3');
    $pdf->new_outline('Title' => 'Summary');

    # Add something to the first page
    $page->stringc($f1, 20, 306, 300,
                   'by Fabien Tassin <fta@sofaraway.org>');

    # Add the missing PDF objects and a the footer then close the file
    $pdf->close;

DESCRIPTION

PDF::Create allows you to create PDF documents using a large number of primitives, and emit the result as a PDF file or stream. PDF stands for Portable Document Format.

Documents can have several pages, a table of content, an information section and many other PDF elements. More functionnalities will be added as needs arise.

Documents are constructed on the fly so the memory footprint is not tied to the size of the pages but only to their number.

Methods

new

To create a new PDF, send a new() message to the PDF::Create class. For example:

my $pdf = new PDF::Create;

This will create an empty PDF structure. A lot of attributes can be used:

- filename: destination file that will contain the resulting
  PDF or ...

- fh: ... an already opened filehandle

- Version: can be 1.0 to 1.3 (default: 1.2)

- PageMode: how the document should appear when opened.
  Allowed values are:

   - UseNone: Open document with neither outline nor thumbnails
     visible. This is the default value.

   - UseOutlines: Open document with outline visible.

   - UseThumbs: Open document with thumbnails visible.

   - FullScreen: Open document in full-screen mode. In
     full-screen mode, there is no menu bar, window controls,
     nor any other window present.

- Author: the name of the person who created this document

- Creator: if the document was converted into a PDF document
  from another form, this is the name of the application that
  created the original document.

- Title: the title of the document

- Subject: the subject of the document

- Keywords: keywords associated with the document

- CreationDate: the date the document was created. This is passed
  as an anonymous array in the same format as localtime returns.
  (ie. a struct tm).

Example:

        my $pdf = new PDF::Create('filename'     => 'mypdf.pdf',
                                  'Version'      => 1.2,
                                  'PageMode'     => 'UseOutlines',
                                  'Author'       => 'Fabien Tassin',
                                  'Title'        => 'My title',
				  'CreationDate' => [ localtime ],
                             );

The created object is returned.

close

Add the missing sections needed to obtain a complete and valid PDF document then close the file if needed.

get_data

If you didn't ask the $pdf object to write its output to a file, you can pick up the pdf code by calling this method. It returns a big string. You need to call close first, mind.

add_comment [string]

Add a comment to the document.

new_outline [parameters]

Add an outline to the document using the given parameters. Return the newly created outline.

Parameters can be:

- Title: the title of the outline. Mandatory.

- Destination: the destination of this outline. In this version, it is only possible to give a page as destination. The default destination is the current page.

- Parent: the parent of this outline in the outlines tree. This is an outline object.

Example:

my $outline = $pdf->new_outline('Title' => 'Item 1',
                                'Destination' => $page);
$outline->new_outline('Title' => 'Item 1.1');
$pdf->new_outline('Title' => 'Item 1.2',
                  'Parent' => $outline);
$pdf->new_outline('Title' => 'Item 2');

new_page

Add a page to the document using the given parameters. Return the newly created page.

Parameters can be:

- Parent: the parent of this page in the pages tree. This is a page object.

- Resources: Resources required by this page.

- MediaBox: Rectangle specifying the natural size of the page, for example the dimensions of an A4 sheet of paper. The coordinates are measured in default user space units. It must be the reference of a 4 values array. You can use get_page_size to get the size of standard paper sizes.

- CropBox: Rectangle specifying the default clipping region for the page when displayed or printed. The default is the value of the MediaBox.

- ArtBox: Rectangle specifying an area of the page to be used when placing PDF content into another application. The default is the value of the CropBox. [PDF 1.3]

- TrimBox: Rectangle specifying the intended finished size of the page (for example, the dimensions of an A4 sheet of paper). In some cases, the MediaBox will be a larger rectangle, which includes printing instructions, cut marks, or other content. The default is the value of the CropBox. [PDF 1.3].

- BleedBox: Rectangle specifying the region to which all page content should be clipped if the page is being output in a production environment. In such environments, a bleed area is desired, to accommodate physical limitations of cutting, folding, and trimming equipment. The actual printed page may include printer's marks that fall outside the bleed box. The default is the value of the CropBox. [PDF 1.3]

- Rotate: Specifies the number of degrees the page should be rotated clockwise when it is displayed or printed. This value must be zero (the default) or a multiple of 90.

get_page_size

Returns the size of standard paper sizes to use for MediaBox-parameter of new_page. get_page_size has one required parameter to specify the paper name. Possible values are a0-a6, letter, broadsheet, ledger, tabloid, legal, executive and 36x36. Default is a4.

font

Prepare a font using the given arguments. This font will be added to the document only if it is used at least once before the close method is called.

Parameters can be:

- Subtype: Type of font. PDF defines some types of fonts. It must be one of the predefined type Type1, Type3, TrueType or Type0.

In this version, only Type1 is supported. This is the default value.

- Encoding: Specifies the encoding from which the new encoding differs. It must be one of the predefined encodings MacRomanEncoding, MacExpertEncoding or WinAnsiEncoding.

In this version, only WinAnsiEncoding is supported. This is the default value.

- BaseFont: The PostScript name of the font. It can be one of the following base font: Courier, Courier-Bold, Courier-BoldOblique, Courier-Oblique, Helvetica, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic, Symbol or ZapfDingbats. All of them are supported in this version except the last two ones.

The default value is Helvetica.

image filename

Prepare an XObject (image) using the given arguments. This image will be added to the document only if it is used at least once before the close method is called. In this version GIF, interlaced GIF and JPEG is supported. Usage of interlaced GIFs are slower because they are decompressed, modified and compressed again.

Parameters:

- filename: file name of image (required).

Page methods

This section describes the methods that can be used by a PDF::Create::Page object.

In its current form, this class is divided into two main parts, one for drawing (using PostScript like paths) and one for writing.

Some methods are not described here because they must not be called directly (e.g. new and add).

new_page params

Add a sub-page to the current page.

See PDF::Create::new_page

string font size x y text

Add text to the current page using the font object at the given size and position. The point (x, y) is the bottom left corner of the rectangle containing the text.

Example :

   my $f1 = $pdf->font('Subtype'  => 'Type1',
	   	        'Encoding' => 'WinAnsiEncoding',
		        'BaseFont' => 'Helvetica');
   $page->string($f1, 20, 306, 396, "some text");

stringl font size x y text

Same as string.

stringr font size x y text

Same as string but right aligned.

stringc font size x y text

Same as string but centered.

string_width font text

Return the size of the text using the given font in default user space units. This does not contain the size of the font yet.

line x1 y1 x2 y2

Draw a line between (x1, y1) and (x2, y2).

set_width w

Set the width of subsequent lines to w points.

Low level drawing methods

moveto x y

Moves the current point to (x, y), omitting any connecting line segment.

lineto x y

Appends a straight line segment from the current point to (x, y). The current point is (x, y).

curveto x1 y1 x2 y2 x3 y3

Appends a Bezier curve to the path. The curve extends from the current point to (x3 ,y3) using (x1 ,y1) and (x2 ,y2) as the Bezier control points. The new current point is (x3 ,y3).

rectangle x y w h

Adds a rectangle to the current path.

closepath

Closes the current subpath by appending a straight line segment from the current point to the starting point of the subpath.

newpath

Ends the path without filling or stroking it.

stroke

Strokes the path.

closestroke

Closes and strokes the path.

fill

Fills the path using the non-zero winding number rule.

fill2

Fills the path using the even-odd rule

image image_id xpos ypos xalign yalign xscale yscale rotate xskew yskew

Inserts an image.

Parameters can be:

- image: Image id returned by PDF::image (required).

- xpos, ypos: Position of image (required).

- xalign, yalign: Alignment of image. 0 is left/bottom, 1 is centered and 2 is right, top.

- xscale, yscale: Scaling of image. 1.0 is original size.

- rotate: Rotation of image. 0 is no rotation, 2*pi is 360° rotation.

- xskew, yskew: Skew of image.

SEE ALSO

PDF::Create::Page(3), perl(1)

AUTHOR

Fabien Tassin (fta@sofaraway.org)

GIF and JPEG-support: Michael Gross (mdgrosse@sbox.tugraz.at)

COPYRIGHT

Copyright 1999-2001, Fabien Tassin. All rights reserved. It may be used and modified freely, but I do request that this copyright notice remain attached to the file. You may modify this module as you wish, but if you redistribute a modified version, please attach a note listing the modifications you have made.