NAME

PDF::Create - Create PDF files.

VERSION

Version 1.46

DESCRIPTION

"PDF::Create" allows you to create PDF document using a number of primitives.The result is 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.

SYNOPSIS

"PDF::Create" provides an easy module to create PDF output from your perl script. It is designed to be easy to use and simple to install and maintain. It provides a couple of subroutines to handle text, fonts, images and drawing primitives. Simple documents are easy to create with the supplied routines.

In addition to be reasonable simple "PDF::Create" is written in pure Perl and has no external dependencies (libraries, other modules, etc.). It should run on any platform where perl is available.

For complex stuff some understanding of the underlying Postscript/PDF format is necessary. In this case it might be better go with the more complete PDF::API2 modules to gain more features at the expense of a steeper learning curve.

Example PDF creation with "PDF::Create" (see PDF::Create::Page for details of methods available on a page):

    use strict; use warnings;
    use PDF::Create;

    my $pdf = PDF::Create->new(
        'filename'     => 'sample.pdf',
        'Author'       => 'John Doe',
        'Title'        => 'Sample PDF',
        'CreationDate' => [ localtime ]
    );

    # Add a A4 sized page
    my $root = $pdf->new_page('MediaBox' => $pdf->get_page_size('A4'));

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

    # Prepare a font
    my $font = $pdf->font('BaseFont' => 'Helvetica');

    # Prepare a Table of Content
    my $toc = $pdf->new_outline('Title' => 'Title Page', 'Destination' => $page1);

    # Write some text
    $page1->stringc($font, 40, 306, 426, 'PDF::Create');
    $page1->stringc($font, 20, 306, 396, "version $PDF::Create::VERSION");
    $page1->stringc($font, 20, 306, 300, 'by John Doe <john.doe@example.com>');

    # Add another page
    my $page2 = $root->new_page;

    # Draw some lines
    $page2->line(0, 0,   592, 840);
    $page2->line(0, 840, 592, 0);

    $page2->string($font, 20, 50, 400, "default á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
    $page2->string_underline($font, 20, 50, 400, "default á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");

    use utf8;
    $page2->string($font, 20, 50, 350, "use utf8 á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
    $page2->string_underline($font, 20, 50, 350, "use utf8 á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");

    no utf8;
    $page2->string($font, 20, 50, 300, "no utf8 á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
    $page2->string_underline($font, 20, 50, 300, "no utf8 á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");

    $toc->new_outline('Title' => 'Second Page', 'Destination' => $page2);

    # Close the file and write the PDF
    $pdf->close;

CONSTRUCTOR

The method "new(%params)" create a new pdf structure for your PDF. It returns an object handle which can be used to add more stuff to the PDF. The parameter keys to the constructor are detailed as below:

    +--------------+------------------------------------------------------------+
    | Key          | Description                                                |
    +--------------+------------------------------------------------------------+
    |              |                                                            |
    | filename     | Destination file that will contain resulting PDF or '-' for|
    |              | stdout. If neither filename or fh are specified, the       |
    |              | content will be stored in memory and returned when calling |
    |              | close().                                                   |
    |              |                                                            |
    | fh           | Already opened filehandle that will contain resulting PDF. |
    |              | See comment above regarding close().                       |
    |              |                                                            |
    | Version      | PDF Version to claim, can be 1.0 to 1.3 (default: 1.       |
    |              |                                                            |
    | PageMode     | How the document should appear when opened.Possible values |
    |              | UseNone (Default), UseOutlines, UseThumbs and FullScreen   |
    |              |                                                            |
    | 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 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.   |
    |              |                                                            |
    | Debug        | The debug level, defaults to 0. It can be any positive     |
    |              | integers.                                                  |
    |              |                                                            |
    +--------------+------------------------------------------------------------+

Example:

    my $pdf = PDF::Create->new(
        'filename'     => 'sample.pdf',
        'Version'      => 1.2,
        'PageMode'     => 'UseOutlines',
        'Author'       => 'John Doe',
        'Title'        => 'My Title',
        'CreationDate' => [ localtime ]
    );

If you are writing a CGI you can send your PDF on the fly to stdout / directly to the browser using '-' as filename.

CGI Example:

  use CGI;
  use PDF::Create;

  print CGI::header(-type => 'application/x-pdf', -attachment => 'sample.pdf');
  my $pdf = PDF::Create->new(
      'filename'     => '-',
      'Author'       => 'John Doe',
      'Title'        => 'My title',
      'CreationDate' => [ localtime ]
  );

METHODS

new_page(%params)

Add a page to the document using the given parameters. "new_page" must be called first to initialize a root page, used as model for further pages.Returns a handle to the newly created page. Parameters can be:

    +-----------+---------------------------------------------------------------+
    | Key       | Description                                                   |
    +-----------+---------------------------------------------------------------+
    |           |                                                               |
    | Parent    | The parent of this page in the pages tree.This is 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 4 values array.You can use C<get_page_size> to get to get  |
    |           | the size of standard paper sizes.C<get_page_size> knows about |
    |           | A0-A6, A4L (landscape), Letter, Legal, Broadsheet, Ledger,    |
    |           | Tabloid, Executive and 36x36.                                 |
    | 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. The entire page,      |
    |           | including contents is rotated.                                |
    |           |                                                               |
    +-----------+---------------------------------------------------------------+

Example:

    my $a4 = $pdf->new_page( 'MediaBox' => $pdf->get_page_size('A4') );

    my $page1 = $a4->new_page;
    $page1->string($f1, 20, 306, 396, "some text on page 1");

    my $page2 = $a4->new_page;
    $page2->string($f1, 20, 306, 396, "some text on page 2");

font(%params)

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 are listed below:

    +----------+----------------------------------------------------------------+
    | Key      | Description                                                    |
    +----------+----------------------------------------------------------------+
    | 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 fonts: Courier, Courier-Bold, Courier-BoldOblique,        |
    |          | Courier-Oblique, Helvetica, Helvetica-Bold,                    |
    |          | Helvetica-BoldOblique, Helvetica-Oblique, Times-Roman,         |
    |          | Times-Bold, Times-Italic, Times-BoldItalic or Symbol.          |
    +----------+----------------------------------------------------------------+

The ZapfDingbats font is not supported in this version.Default font is Helvetica.

    my $f1 = $pdf->font('BaseFont' => 'Helvetica');

new_outline(%params)

Adds an outline to the document using the given parameters. Return the newly created outline. Parameters can be:

    +-------------+-------------------------------------------------------------+
    | Key         | Description                                                 |
    +-------------+-------------------------------------------------------------+
    |             |                                                             |
    | Title       | The title of the outline. Mandatory.                        |
    |             |                                                             |
    | Destination | The Destination of this outline item. 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. This way you represent the tree of your     |
    |             | outlines.                                                   |
    |             |                                                             |
    +-------------+-------------------------------------------------------------+

Example:

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

get_page_size($name)

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

    my $root = $pdf->new_page( 'MediaBox' => $pdf->get_page_size('A4') );

version($number)

Set and return version number. Valid version numbers are 1.0, 1.1, 1.2 and 1.3.

close(%params)

Close does the work of creating the PDF data from the objects collected before. You must call "close()" after you have added all the contents as most of the real work building the PDF is performed there. If omit calling close you get no PDF output. Returns the raw content of the PDF. If "fh" was provided when creating object of "PDF::Create" then it does not try to close the file handle. It is, therefore, advised you call "flush()" rather than "close()".

flush()

Generate the PDF content and returns the raw content as it is.

reserve($name, $type)

Reserve the next object number for the given object type.

add_comment($message)

Add comment to the document.The string will show up in the PDF as postscript-style comment:

    % this is a postscript comment

annotation(%params)

Adds an annotation object, for the time being we only do the 'Link' - 'URI' kind This is a sensitive area in the PDF document where text annotations are shown or links launched. "PDF::Create" only supports URI links at this time.

URI links have two components,the text or graphics object and the area where the mouseclick should occur.

For the object to be clicked on you'll use standard text of drawing methods. To define the click-sensitive area and the destination URI.

Example:

    # Draw a string and underline it to show it is a link
    $pdf->string($f1, 10, 450, 200, 'http://www.cpan.org');

    my $line = $pdf->string_underline($f1, 10, 450, 200, 'http://www.cpan.org');

    # Create the hot area with the link to open on click
    $pdf->annotation(
        Subtype => 'Link',
        URI     => 'http://www.cpan.org',
        x       => 450,
        y       => 200,
        w       => $l,
        h       => 15,
        Border  => [0,0,0]
    );

The point (x, y) is the bottom left corner of the rectangle containing hotspot rectangle, (w, h) are the width and height of the hotspot rectangle. The Border describes the thickness of the border surrounding the rectangle hotspot.

The function "string_underline" returns the width of the string, this can be used directly for the width of the hotspot rectangle.

image($filename)

Prepare an XObject (image) using the given arguments. This image will be added to the document if it is referenced 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. The gif support is limited to images with a LZW minimum code size of 8. Small images with few colors can have a smaller minimum code size and will not work. If you get errors regarding JPEG compression, then the compression method used in your JPEG file is not supported by "PDF::Image::JPEG". Try resaving the JPEG file with different compression options (for example, disable progressive compression).

Example:

    my $img = $pdf->image('image.jpg');

    $page->image(
        image  => $img,
        xscale => 0.25, # scale image for better quality
        yscale => 0.25,
        xpos   => 50,
        ypos   => 60,
        xalign => 0,
        yalign => 2,
    );

get_data()

If you did not 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.

LIMITATIONS

"PDF::Create" comes with a couple of limitations or known caveats:

PDF Size / Memory

Unless using a filehandle, "PDF::Create" assembles the entire PDF in memory. If you create very large documents on a machine with a small amount of memory your program can fail because it runs out of memory. If using a filehandle, data will be written immediately to the filehandle after each method.

Small GIF images

Some gif images get created with a minimal lzw code size of less than 8. "PDF::Create" can not decode those and they must be converted.

SUPPORT

I support "PDF::Create" in my spare time between work and family, so the amount of work I put in is limited.

If you experience a problem make sure you are at the latest version first many of things have already been fixed.

Please register bug at the CPAN bug tracking system at <http://rt.cpan.org> or send email to "bug-PDF-Create [at] rt.cpan.org"

Be sure to include the following information:

- PDF::Create Version you are running
- Perl version (perl -v)
- Operating System vendor and version
- Details about your operating environment that might be related to the issue being described
- Exact cut and pasted error or warning messages
- The shortest, clearest code you can manage to write which reproduces the bug described.

I appreciate patches against the latest released version of "PDF::Create" which fix the bug.

Feature request can be submitted like bugs. If you provide patch for a feature which does not go against the "PDF::Create" philosophy (keep it simple) then you have a good chance for it to be accepted.

AUTHORS

Fabien Tassin

GIF and JPEG-support: Michael Gross (info@mdgrosse.net)

Maintenance since 2007: Markus Baertschi (markus@markus.org)

Currently maintained by Mohammad S Anwar (MANWAR) "<mohammad.anwar at yahoo.com>"

REPOSITORY

<https://github.com/manwar/pdf-create>

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.

LICENSE

This is free software; you can redistribute it and / or modify it under the same terms as Perl 5.6.0.