NAME

PDF::API2 - A Perl Module Chain to faciliate the Creation and Modification of High-Quality "Portable Document Format (aka. PDF)" Files.

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->ttfont('TimesNewRoman.ttf');

GENERIC METHODS

$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 later-on.

Example:

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

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

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

Opens an existing PDF for modification.

$pdf = PDF::API->openScalar $pdfstream

Opens an existing PDF-stream for modification.

$pdf->preferences %opts

Controls viewing-preferences for the pdf.

Page Mode Options:

-fullscreen ... Full-screen mode, with no menu bar, window controls, or any other window visible.

-thumbs ... Thumbnail images visible.

-outlines ... Document outline visible.

Page Layout Options:

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

Viewer Options:

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

Initial Page Option:

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

Initial Page 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],
);

$val = $pdf->default $parameter

$pdf->default $parameter, $val

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

$bool = $pdf->isEncrypted

Checks if the previously opened pdf is encrypted.

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

$pdf->update

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

$pdf->saveas $file

Saves the document to file.

$string = $pdf->stringify

Returns the document in a string.

$pdf->end

Destroys the document.

PAGE METHODS

$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 (the first page)
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

$xoform = $pdf->importPageIntoForm $sourcepdf, $sourceindex

Returns a form-xobject created from $sourcepdf,$sourceindex. This is useful if you want to transpose the imported page-description somewhat differently onto a page (ie. two-up, four-up, duplex, etc.).

Note: on $index

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

$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 $name

$pdf->mediabox $w, $h

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

Sets the global mediabox. Other methods: cropbox, bleedbox, trimbox and artbox.

$pdf->cropbox $name

$pdf->cropbox $w, $h

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

Sets the global cropbox.

$pdf->bleedbox $name

$pdf->bleedbox $w, $h

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

Sets the global bleedbox.

$pdf->trimbox $name

$pdf->trimbox $w, $h

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

Sets the global trimbox.

$pdf->artbox $name

$pdf->artbox $w, $h

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

Sets the global artbox.

FONT METHODS

@allFontDirs = PDF::API2::addFontDirs $dir1, ..., $dirN

Adds one or more directories to the search-path for finding font files. Returns the list of searched directories.

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

Returns a new adobe core font object.

See PDF::API2::Resource::Font::CoreFont for an explanation.

Examples:

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

Valid %options are:

'-encode' ... changes the encoding of the font from its default.

$font = $pdf->psfont $psfile [, %options]

Returns a new adobe type1 font object.

See PDF::API2::Resource::Font::Postscript for an explanation.

Examples:

$font = $pdf->psfont( 'Times-Book.pfa', -afmfile => 'Times-Book.afm' );
$font = $pdf->psfont( '/fonts/Synest-FB.pfb', -pfmfile => '/fonts/Synest-FB.pfm' );

Valid %options are:

'-encode' ... changes the encoding of the font from its default.

'-afmfile' ... specifies that font metrics to be read from the
              adobe font metrics file (AFM).

'-pfmfile' ... specifies that font metrics to be read from the
              windows printer font metrics file (PFM).
              (this option overrides the -encode option)

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

Returns a new truetype or opentype font object.

See PDF::API2::Resource::CIDFont::TrueType for an explanation.

Examples:

$font = $pdf->ttfont('Times.ttf');
$font = $pdf->ttfont('Georgia.otf');

Valid %options are:

'-encode' ... changes the encoding of the font from its default.

$font = $pdf->cjkfont $cjkname [, %options]

Returns a new cjk font object.

See PDF::API2::Resource::CIDFont::CJKFont for an explanation.

Examples:

$font = $pdf->cjkfont('korean');
$font = $pdf->cjkfont('traditional');

Valid %options are:

'-encode' ... changes the encoding of the font from its default.

IMAGE METHODS

$jpeg = $pdf->image_jpeg $file

Returns a new jpeg image object.

$tiff = $pdf->image_tiff $file

Returns a new tiff image object.

$pnm = $pdf->image_pnm $file

Returns a new pnm image object.

$png = $pdf->image_png $file

Returns a new png image object.

$gif = $pdf->image_gif $file

Returns a new gif image object.

$gdf = $pdf->image_gd $gdobj

Returns a new image object from GD::Image.

Examples:

$jpeg = $pdf->image_jpeg('../some/nice/picture.jpeg');
$tiff = $pdf->image_tiff('../some/nice/picture.tiff');
$pnm = $pdf->image_pnm('../some/nice/picture.pnm');
$png = $pdf->image_png('../some/nice/picture.png');
$gif = $pdf->image_gif('../some/nice/picture.gif');
$gdf = $pdf->image_gd($gdobj);

COLORSPACE METHODS

$cs = $pdf->colorspace_act $file

Returns a new colorspace-object based on a adobe-color-table file.

See PDF::API2::Resource::ColorSpace::Indexed::ACTFile for an explanation of the file format.

$cs = $pdf->colorspace_web

Returns a new colorspace-object based on the web color palette.

See PDF::API2::Resource::ColorSpace::Indexed::WebColor for an explanation.

$cs = $pdf->colorspace_hue

Returns a new colorspace-object based on the hue color palette.

See PDF::API2::Resource::ColorSpace::Indexed::Hue for an explanation.

$cs = $pdf->colorspace_separation $tint, $color

Returns a new limited separation colorspace-object based on the parameters.

$tint can be any valid ink-identifier, including but not limited to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or 'Orange'.

$color must be a valid color-specification limited to: '#rrggbb', '!hhssvv', '%ccmmyykk' or a "named color" (rgb).

The colorspace model for will be automatically chosen based on the specified color.

WARNING: this is NOT YET a full colorspace object, so it can only be used for gray-level bitmap-images.

OTHER METHODS

$xo = $pdf->xo_form

Returns a new form-xobject.

Examples:

$xo = $pdf->xo_form;

$egs = $pdf->egstate

Returns a new extended graphics state object.

Examples:

$egs = $pdf->egstate;

$otls = $pdf->outlines

Returns a new or existing outlines object.

BARCODE METHODS

$bc = $pdf->xo_codabar %opts

$bc = $pdf->xo_code128 %opts

$bc = $pdf->xo_2of5int %opts

$bc = $pdf->xo_3of9 %opts

$bc = $pdf->xo_ean13 %opts

creates the specified barcode object as a form-xo.

RESOURCE METHODS

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

Adds a resource to the global pdf 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

HISTORY

$Log: API2.pm,v $
Revision 1.24  2004/04/07 10:48:53  fredo
fixed handling of ColorSpace/Separation

Revision 1.23  2004/04/06 21:00:52  fredo
separation colorspace now a full resource

Revision 1.22  2004/04/04 23:42:10  fredo
fixed 270 degree rotation in openpage

Revision 1.21  2004/04/04 23:36:33  fredo
added simple separation colorspace

Revision 1.20  2004/03/20 09:11:45  fredo
modified font search path methodname

Revision 1.19  2004/03/20 08:38:38  fredo
added isEncrypted determinator

Revision 1.18  2004/03/18 09:43:32  fredo
added font search path handling

Revision 1.17  2004/02/12 14:38:33  fredo
added openScalar method

Revision 1.16  2004/02/05 13:18:39  fredo
corrected info hash utf8 usage

Revision 1.15  2004/02/04 23:43:53  fredo
pdf info method now properly recognized utf8 parameters

Revision 1.14  2004/01/21 12:29:06  fredo
moved release versioning to PDF::API2::Version

Revision 1.13  2004/01/19 14:16:32  fredo
update for 0.40_16

Revision 1.12  2004/01/15 21:26:04  fredo
docbug: fixed inconsistent links

Revision 1.11  2004/01/14 18:25:41  fredo
release update 0.40_15

Revision 1.10  2004/01/12 13:52:41  fredo
update for 0.40_14

Revision 1.9  2004/01/08 23:56:20  fredo
corrected producer tag versioning, updated to release 0.40_13

Revision 1.8  2003/12/08 13:05:18  Administrator
corrected to proper licencing statement

Revision 1.7  2003/12/08 11:47:38  Administrator
change step 3 for proper module versioning

Revision 1.6  2003/12/08 11:46:25  Administrator
change step 2 for proper module versioning

Revision 1.5  2003/12/08 11:43:10  Administrator
change step 1 for proper module versioning

Revision 1.4  2003/11/30 19:00:43  Administrator
added Code128/EAN128

Revision 1.3  2003/11/30 17:07:11  Administrator
merged into default