Provided by: libpdf-create-perl_1.06-1_all bug

NAME

       PDF::Create - create PDF files

SYNOPSIS

       Create PDF output from your perl program using 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":

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

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

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

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

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

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

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

         # Draw some lines
         $page2->line(0, 0, 612, 792);
         $page2->line(0, 792, 612, 0);

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

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

DESCRIPTION

       PDF::Create allows you to create PDF documents 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.

Methods

       o    new([parameters])

            Create a new pdf structure for your PDF.

            Example:

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

            "new" returns an object handle used to add more stuff to the PDF.

            'filename'
                      destination file that will contain the resulting PDF or
                      an already opened filehandle or '-' for stdout.

            'Version' PDF Version to claim, 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 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).

            If you are writing a CGI you can send your PDF on the fly to
            stdout or 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 = new PDF::Create('filename'     => '-', # Stdout
                                        'Author'       => 'John Doe',
                                        'Title'        => 'My title',
                                                    'CreationDate' => [ localtime ],
                                       );

       o    close()

            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 !

       o    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.

       o    add_comment([string])

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

                % this is a postscript comment

       o    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 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');

       o    new_page([parameters])

            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.

            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");

            Returns a handle to 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.
              "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.

       o    get_page_size(<pagesize>)

            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.

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

       o    font([parameters])

            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.

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

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

            The Symbol or ZapfDingbats fonts are not supported in this
            version.

            The default font is Helvetica.

       o    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.

            Parameters:

            - filename: file name of image (required).

   URI links
       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 you use the
       "annotation()" method.

       o    annotation([parameters])

            Define an annotation. 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.

            Example:

                # Draw a string and undeline it to show it is a link
                $pdf->string($f1,10,450,200,'http://www.cpan.org')
                $l=$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_undeline" returns the width of the string,
            this can be used directly for the width of the hotspot rectangle.

   Page methods
       Page methods are used to draw stuff on a page. Although these methods
       are packaged in the separate module "PDF::Create::Page" you should call
       them always through the $page handler you get from the "new_page()"
       method.

       There are internal changes on the horizon who will break code calling
       methods differently !

       o    new_page()

            Add a sub-page to the current page.

            See "new_page" above

       o    string(font, size, x, y, text [,alignment] )

            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.

            The optional alignment can be 'r' for right-alignment and 'c' for
            centered.

            Example :

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

       o    string_underline(font, size, x, y, text [,alignment] )

            Draw a line for underlining. The parameters are the same as for
            the string function, but only the line is drawn. To draw an
            underlined string you must call both, string and string_underline.

            Example :

                $page->string($f1, 20, 306, 396, "some underlined text");
                $page->string_underline($f1, 20, 306, 396, "some underlined text");

            To change the color of your text use the "setrgbcolor" function.

            "string_underline" returns the length of the string. So its return
            value can be used directly for the bounding box of an annotation.

       o    stringl(font size x y text)

            Same as "string".

       o    stringr(font size x y text)

            Same as "string" but right aligned (alignment 'r').

       o    stringc(font size x y text)

            Same as "string" but centered (alignment 'c').

       o    printnl(text font size x y)

            Similar to "string" but parses the string for newline and prints
            each part on a separate line. Lines spacing is the same as the
            font-size. Returns the number of lines.

            Note the different parameter sequence. The first call should
            specify all parameters, font is the absolute minimum, a warning
            will be given for the missing y position and 800 will be assumed.
            All subsequent invocations can omit all but the string parameters.

            Attention: There is no provision for changing pages. If you run
            out of space on the current page this will draw the string(s)
            outside the page and it will be invisble !

       o    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, to
            get the length you must multiply by the font size.

       o    line(x1, y1, x2, y2)

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

       o    set_width(w)

            Set the width of subsequent lines to "w" points.

       o    setrgbcolor(r, g, b)

       o    setrgbcolorstroke(r, g, b)

            Set the color of the subsequent drawing operations.

            PDF distinguishes between the stroke and fill operations and
            provides separate color settings for each.

            - "setrgbcolor()" sets the fill colors used for normal text or
            filled objects.

            - "setrgbcolorstroke()" sets the stroke color used for lines.

       o    moveto(x, y)

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

       o    lineto(x, y)

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

       o    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 the set to (x3
            ,y3).

       o    rectangle(x, y, w, h)

            Draws a rectangle.

       o    closepath()

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

       o    newpath()

            Ends the current path. The next drawing operation will start a new
            path.

       o    stroke()

            Strokes (draws) the path.

       o    closestroke()

            Closes and strokes the path.

       o    fill()

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

       o    fill2()

            Fills the path using the even-odd rule

            Example drawing:

              # draw a filled triangle
              $page->newpath;
              $page->setrgbcolor 0.1 0.3 0.8;
              $page->moveto 100 100;
              $page->lineto 260 300;
              $page->lineto 300 100;
              $page->lineto 100 100;
              $page->fill;

       o    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 360AX
            rotation.

            - xskew, yskew: Skew of image.

Limitations

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

       PDF Size / Memory
            "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.

       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 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.

SEE ALSO

       Adobe PDF reference
       <http://www.adobe.com/devnet/pdf/pdf_reference.html>

       My git repository for "PDF::Create"
       <http://github.com/markusb/pdf-create>

   Other PDF procesing CPAN modules
       <http://search.cpan.org/perldoc?PDF::Labels> Routines to produce
       formatted pages of mailing labels in PDF, uses PDF::Create internally

       <http://search.cpan.org/perldoc?PDF::Haru> Perl interface to Haru Free
       PDF Library

       <http://search.cpan.org/perldoc?PDF::EasyPDF> PDF creation from a one-
       file module, similar to PDF::Create

       <http://search.cpan.org/perldoc?PDF::CreateSimple> Yet another PDF
       creation module

       <http://search.cpan.org/perldoc?PDF::Report> A wrapper written for
       PDF::API2

AUTHORS

       Fabien Tassin

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

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

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.

       Copyright 2007-, Markus Baertschi Copyright 2010, Gary Lieberman