PDF::API2

NAME

PDF::API2 - The Next Generation API for creating and modifing PDFs.

SYNOPSIS

        use PDF::API2;

        $pdf = PDF::API2->new;
        $pdf = PDF::API2->open('some.pdf');
        $page = $pdf->page;
        $page = $pdf->openpage($pagenum);
        $img = $pdf->image('some.jpg');
        $font = $pdf->corefont('Times-Roman');
        $font = $pdf->psfont('Times-Roman.pfb','Times-Roman.afm');
        $font = $pdf->ttfont('TimesNewRoman.ttf');

METHODS

PDF::API2

$pdf = PDF::API->new %opts

Creates a new pdf-file object. If you know beforehand to save the pdf to file you can give the '-file' option, to minimize possible memory requirements.

Example:

        $pdf = PDF::API2->new();

        $pdf = PDF::API2->new(-file => 'ournew.pdf');

$pdf->preferences %opts

Controls viewing=preferences for the pdf.

Options:

        -fullscreen ... Full-screen mode, with no menu bar, window controls, or any other window visible.
        -thumbs ... Thumbnail images visible.
        -outlines ... Document outline visible.
        -singlepage ... Display one page at a time.
        -onecolumn ... Display the pages in one column.
        -twocolumnleft ... Display the pages in two columns, with oddnumbered pages on the left.
        -twocolumnrigth ... Display the pages in two columns, with oddnumbered pages on the right.
        -hidetoolbar ... Specifying whether to hide tool bars.
        -hidemenubar ... Specifying whether to hide menu bars.
        -hidewindowui ... Specifying whether to hide user interface elements.
        -fitwindow ... Specifying whether to resize the document’s window to the size of the displayed page.
        -centerwindow ... Specifying whether to position the document’s window in the center of the screen.
        -displaytitle ... Specifying whether the window’s title bar should display the document title
                        taken from the Title entry of the document information dictionary.
        -afterfullscreenthumbs ... Thumbnail images visible after Full-screen mode.
        -afterfullscreenoutlines ... Document outline visible after Full-screen mode.

        -firstpage => [ $pageobj, %opts] ... Specifying the page to be displayed,
                        plus one of the following options:

                -fit => 1

                Display the page designated by page, with its contents magnified just enough to
                fit the entire page within the window both horizontally and vertically. If the
                required horizontal and vertical magnification factors are different, use the
                smaller of the two, centering the page within the window in the other dimension.

                -fith => $top

                Display the page designated by page, with the vertical coordinate top positioned
                at the top edge of the window and the contents of the page magnified just enough
                to fit the entire width of the page within the window.

                -fitv => $left

                Display the page designated by page, with the horizontal coordinate left positioned
                at the left edge of the window and the contents of the page magnified just enough
                to fit the entire height of the page within the window.

                -fitr => [ $left, $bottom, $right, $top ]

                Display the page designated by page, with its contents magnified just enough to
                fit the rectangle specified by the coordinates left, bottom, right, and top
                entirely within the window both horizontally and vertically. If the required
                horizontal and vertical magnification factors are different, use the smaller of
                the two, centering the rectangle within the window in the other dimension.

                -fitb => 1

                Display the page designated by page, with its contents magnified just enough
                to fit its bounding box entirely within the window both horizontally and
                vertically. If the required horizontal and vertical magnification factors are
                different, use the smaller of the two, centering the bounding box within the
                window in the other dimension.

                -fitbh => $top

                Display the page designated by page, with the vertical coordinate top
                positioned at the top edge of the window and the contents of the page
                magnified just enough to fit the entire width of its bounding box
                within the window.

                -fitbv => $left

                Display the page designated by page, with the horizontal coordinate
                left positioned at the left edge of the window and the contents of the page
                magnified just enough to fit the entire height of its bounding box within the
                window.

                -xyz => [ $left, $top, $zoom ]

                Display the page designated by page, with the coordinates (left, top) positioned
                at the top-left corner of the window and the contents of the page magnified by
                the factor zoom. A zero (0) value for any of the parameters left, top, or zoom
                specifies that the current value of that parameter is to be retained unchanged.

Example:

        $pdf->preferences(
                -fullscreen => 1,
                -onecolumn => 1,
                -afterfullscreenoutlines => 1,
                -firstpage => [ $pageobj , -fit => 1],
        );

$pdf = PDF::API->open $pdffile

Opens an existing PDF.

$page = $pdf->page

$page = $pdf->page $index

Returns a new page object or inserts-and-returns a new page at $index.

Note: on $index

        -1 ... is inserted before the last page
        1 ... is inserted before page number 1
        0 ... is simply appended

$pageobj = $pdf->openpage $index

Returns the pageobject of page $index.

Note: on $index

        -1,0 ... returns the last page
        1 ... returns page number 1

$pageobj = $pdf->clonepage $sourceindex, $targetindex

Returns the pageobject of page $targetindex, cloned from $sourceindex.

Note: on $index

        -1,0 ... returns the last page
        1 ... returns page number 1

Beware:

Under some circumstances, this method may cause $pdf->update to die. These circumstances remain unresolved but previously generated pdfs via API2 remain unaffected so far.

$pageobj = $pdf->importpage $sourcepdf, $sourceindex, $targetindex

Returns the pageobject of page $targetindex, imported from $sourcepdf,$sourceindex.

Note: on $index

        -1,0 ... returns the last page
        1 ... returns page number 1

Note: you can specify a page object instead as $targetindex so that the contents of the sourcepage will be 'merged into'.

$pagenumber = $pdf->pages

Returns the number of pages in the document.

$pdf->mediabox $w, $h

$pdf->mediabox $llx, $lly, $urx, $ury

Sets the global mediabox.

$pdf->update

Updates a previously "opened" document after all changes have been applied.

$pdf->saveas $file

Saves the document.

$string = $pdf->stringify

Returns the document in a string.

$pdf->end

Destroys the document.

%infohash $pdf->info %infohash

Sets/Gets the info structure of the document.

Example:

        $pdf->info(
                'Author'       => " Alfred Reibenschuh ",
                'CreationDate' => "D:20020911000000+01'00'",
                'ModDate'      => "D:YYYYMMDDhhmmssOHH'mm'",
                'Creator'      => "fredos-script.pl",
                'Producer'     => "PDF::API2",
                'Title'        => "some Publication",
                'Subject'      => "perl ?",
                'Keywords'     => "all good things are pdf"
        );

$pdf->finishobjects @objects

Force objects to be written to file.

$val = $pdf->default $parameter

$pdf->default $parameter, $val

Gets/Sets default values for the behaviour of ::API2.

$font = $pdf->corefont $fontname [, %options]

Returns a new or existing adobe core font object.

Examples:

        $font = $pdf->corefont('Times-Roman');
        $font = $pdf->corefont('Times-Bold');
        $font = $pdf->corefont('Helvetica');
        $font = $pdf->corefont('ZapfDingbats');

$font = $pdf->psfont $pfbfile,$afmfile

Returns a new or existing adobe type1 font object.

Examples:

        $font = $pdf->psfont('Times-Book.pfb','Times-Book.afm');
        $font = $pdf->psfont('/fonts/Synest-FB.pfb','/fonts/Synest-FB.afm');
        $font = $pdf->psfont('../Highland-URW.pfb','../Highland-URW.afm');

$font = $pdf->ttfont $ttfile [, %options]

Returns a new or existing truetype font object.

Examples:

        $font = $pdf->ttfont('TimesNewRoman.ttf');
        $font = $pdf->ttfont('/fonts/Univers-Bold.ttf');
        $font = $pdf->ttfont('../Democratica-SmallCaps.ttf');

$img = $pdf->image $file

Returns a new image object from a file or a GD::Image object.

Examples:

        $img = $pdf->image('yetanotherfun.jpg');
        $img = $pdf->image('truly24bitpic.png');
        $img = $pdf->image('reallargefile.pnm');

        $gdimgobj=GD::Image->newFromPng('truly24bitpic.png');
        $img = $pdf->image($gdimgobj);

Important Note:

This is an unmaintained function, please use one of the following for proper support: image_jpeg, image_png, image_gd, image_pnm.

$img = $pdf->image_jpeg $file

Returns a new image object from a jpeg-file.

Examples:

        $img = $pdf->image_jpeg('yetanotherfun.jpg');

$img = $pdf->image_png $file

Returns a new image object from a png-file.

Examples:

        $img = $pdf->image_png('yetanotherfun.png');

$img = $pdf->image_tiff $file

Returns a new image object from a tiff-file.

Examples:

        $img = $pdf->image_tiff('yetanotherfun.TIF');

Please Note:

Currently supported are any combination of the following tiff-features: white-is-zero, black-is-zero, rgb, palette, cmyk, packbits, ccittfax g3-1d, ccittfax g4, lzw and flate, as-long-as the image is not striped !!!

$img = $pdf->image_pnm $file

Returns a new image object from a portable anymap (aka. netpbm).

Examples:

        $img = $pdf->image_pnm('yetanotherfun.pbm');
        $img = $pdf->image_pnm('yetanotherfun.pgm');
        $img = $pdf->image_pnm('yetanotherfun.ppm');

$img = $pdf->pdfimage $file, $page_number

Returns a new image object, which is actually a page from another pdf.

Examples:

        $img = $pdf->pdfimage('test1.pdf',1);
        $img = $pdf->pdfimage('another-test.pdf',2);
        $img = $pdf->pdfimage('really-large.pdf',1000);

$img = $pdf->pdfimageobj $pdfobj, $page_number

As $pdf->pdfimage, but takes an already opened pdfobject (API2->open) as parameter.

Note: This is functionally the same as the one above, but far less resource-intensive, if you use many pages (possible the same) from one single pdf.

$shadeing = $pdf->shade

Returns a new shading object.

$pat = $pdf->pattern

Returns a new pattern object.

$cs = $pdf->colorspace %parameters

Returns a new colorspace object.

Examples:

        $cs = $pdf->colorspace(
                -type => 'CalRGB',
                -whitepoint => [ 0.9, 1, 1.1 ],
                -blackpoint => [ 0, 0, 0 ],
                -gamma => [ 2.2, 2.2, 2.2 ],
                -matrix => [
                        0.41238, 0.21259, 0.01929,
                        0.35757, 0.71519, 0.11919,
                        0.1805,  0.07217, 0.95049
                ]
        );

        $cs = $pdf->colorspace(
                -type => 'CalGray',
                -whitepoint => [ 0.9, 1, 1.1 ],
                -blackpoint => [ 0, 0, 0 ],
                -gamma => 2.2
        );

        $cs = $pdf->colorspace(
                -type => 'Lab',
                -whitepoint => [ 0.9, 1, 1.1 ],
                -blackpoint => [ 0, 0, 0 ],
                -gamma => [ 2.2, 2.2, 2.2 ],
                -range => [ -100, 100, -100, 100 ]
        );

        $cs = $pdf->colorspace(
                -type => 'Indexed',
                -base => 'DeviceRGB',
                -maxindex => 3,
                -whitepoint => [ 0.9, 1, 1.1 ],
                -blackpoint => [ 0, 0, 0 ],
                -gamma => [ 2.2, 2.2, 2.2 ],
                -colors => [
                        [ 0,0,0 ],      # black = 0
                        [ 1,1,1 ],      # white = 1
                        [ 1,0,0 ],      # red = 2
                        [ 0,0,1 ],      # blue = 3
                ]
        );

        $cs = $pdf->colorspace(
                -type => 'ICCBased',
                -base => 'DeviceRGB',
                -components => 3,
                -iccfile => 'codacus.icc'
        );

@color = $pdf->businesscolor $basecolor [, $lightdark ]

@color = $pdf->businesscolor $colornumber [, $lightdark ]

Returns a color-array suitible for use with the stroke/fillcolor methods.

$img = $pdf->barcode %options

Returns a new barcode object.

Note: refer to PDF::API2::Barcode for more details.

$egs = $pdf->extgstate

Returns a new extended-graphics-state object.

$otls = $pdf->outlines

Returns a new or existing outlines object.

$page->resource $type, $key, $obj, $force

Adds a resource to the global page-inheritance tree.

Example:

        $pdf->resource('Font',$fontkey,$fontobj);
        $pdf->resource('XObject',$imagekey,$imageobj);
        $pdf->resource('Shading',$shadekey,$shadeobj);
        $pdf->resource('ColorSpace',$spacekey,$speceobj);

Note: You only have to add the required resources, if they are NOT handled by the *font*, *image*, *shade* or *space* methods.

AUTHOR

alfred reibenschuh