/ 
PDF-API2-0.40_83
River stage two • 31 direct dependents • 40 total dependents
/ PDF::API2

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.

Supported Parameters:

nounrotate ... prohibits API2 from rotating imported/opened page to re-create a default pdf-context.

copyannots ... enables importing of annotations (*EXPERIMENTAL*).

$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"
);
@meta_data_attribs = $pdf->infoMetaAttributes @meta_data_attribs

Sets/Gets the supported info-structure tags.

$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.
$font = $pdf->synfont $basefont [, %options]

Returns a new synthetic font object.

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

Examples:

$cf = $pdf->corefont('Times-Roman',-encode=>'latin1');
$sf = $pdf->synfont($cf,-slant=>0.85);  # compressed 85%
$sfb= $pdf->synfont($cf,-bold=>1);      # embolden by 10em
$sfi= $pdf->synfont($cf,-oblique=>-12); # italic at -12 degrees

Valid %options are:

-slant ... slant/expansion factor (0.1-0.9 = slant, 1.1+ = expansion).

-oblique ... italic angle (+/-)

-bold ... embolding factor (0.1+, bold=1, heavy=2, ...)

-space ... additional charspacing in em (0-1000)

$font = $pdf->bdfont $bdffile

Returns a new BDF font object, based on the specified adobe-bdf file.

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

$font = $pdf->unifont @fontspecs, %options

Returns a new uni-font object, based on the specified fonts and options.

BEWARE: This is not a true pdf-object, but a virtual/abstract font-definition !

See PDF::API2::Resource::UniFont for an explanation.

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, %options

Returns a new image object from GD::Image.

Options: The only option currently supported is -lossless => 1.

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

$cs = $pdf->colorspace_devicen \@tintCSx [, $samples]

Returns a new DeviceN colorspace-object based on the parameters.

Example:

$cy = $pdf->colorspace_separation('Cyan',    '%f000');
$ma = $pdf->colorspace_separation('Magenta', '%0f00');
$ye = $pdf->colorspace_separation('Yellow',  '%00f0');
$bk = $pdf->colorspace_separation('Black',   '%000f');
$pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');

$dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk,$pms023 ] );

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

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.

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;
$obj = $pdf->pattern

Returns a new pattern-object.

$obj = $pdf->shading

Returns a new shading-object.

$otls = $pdf->outlines

Returns a new or existing outlines object.

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.71  2005/01/03 03:47:52  fredo
fixed use named destination

Revision 1.70  2005/01/03 03:46:25  fredo
added named destination support

Revision 1.69  2004/12/31 03:12:09  fredo
no message

Revision 1.68  2004/12/16 00:30:51  fredo
added no warn for recursion

Revision 1.67  2004/11/29 15:19:23  fredo
added docs for bdfont, synfont and unifont

Revision 1.66  2004/11/24 20:09:57  fredo
added unifont

Revision 1.65  2004/10/17 03:57:21  fredo
added ToUnicode call for supported fonts

Revision 1.64  2004/10/01 01:39:24  fredo
reverted annotations import fix

Revision 1.63  2004/09/30 23:57:26  fredo
versioning beautify

Revision 1.62  2004/09/30 22:40:41  fredo
fixed pdf-producer to include OS

Revision 1.61  2004/09/30 21:18:21  fredo
changed file version back to cvs

Revision 1.60  2004/09/20 11:22:18  fredo
added default param to fix import-rotation
added default param to fix annotation-import

Revision 1.59  2004/09/03 12:35:09  fredo
pop'd to new version

Revision 1.58  2004/08/25 02:59:25  fredo
disabled memoize since long-running scripts bug from reused adresses

Revision 1.57  2004/07/24 23:10:55  fredo
fixed memoize bug for bdf fonts

Revision 1.56  2004/07/24 23:09:26  fredo
added bdf fonts

Revision 1.55  2004/07/23 13:41:11  fredo
fixed in decoding info dictionary

Revision 1.54  2004/07/21 08:07:17  fredo
added devicen colorspace

Revision 1.53  2004/07/15 14:28:21  fredo
added devicen colorspace

Revision 1.52  2004/06/22 01:33:43  fredo
corrected spelling

Revision 1.51  2004/06/21 22:33:10  fredo
added basic pattern/shading handling

Revision 1.50  2004/06/15 09:06:26  fredo
forced version to 1.50 for beta state

Revision 1.30  2004/06/15 08:09:07  fredo
fixed memoized bug

Revision 1.29  2004/06/01 00:09:57  fredo
memoized *font methods for braindead invokers

Revision 1.28  2004/05/28 11:29:01  fredo
added -lossless param to gd images

Revision 1.27  2004/05/21 10:12:29  fredo
fixed slight importpage quirk

Revision 1.26  2004/04/18 18:07:19  fredo
fixed _findFont method

Revision 1.25  2004/04/07 17:38:00  fredo
added infoMetaAttributes and support code

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 297:

Non-ASCII character seen before =encoding in 'document’s'. Assuming CP1252