man PDF::API2 () - A Perl Module Chain to faciliate the Creation and Modification of High-Quality "Portable Document Format (aka. PDF)" Files.
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
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(); ... print $pdf->stringify;
$pdf = PDF::API2->new(); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new(-file => 'our/new.pdf'); ... $pdf->save;Opens an existing PDF for modification. Example:
$pdf = PDF::API2->open('my/old.pdf'); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->open('our/to/be/updated.pdf'); ... $pdf->update;Opens an existing PDF-stream for modification. Example:
open($fh,'our/stream.pdf') or die "$@"; @pdf = <$fh>; $pdf = PDF::API->openScalar(join('',@pdf)); ... $pdf->saveas('our/new.pdf');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 => [ CW$pageobj, CW%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 => CW$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 => CW$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 => [ CW$left, CW$bottom, CW$right, CW$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 => CW$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 => CW$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 => [ CW$left, CW$top, CW$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], );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. pageencaps ... enables than API2 will add save/restore commands upon imported/opened pages to preserve graphics-state for modification. copyannots ... enables importing of annotations (*EXPERIMENTAL*). Checks if the previously opened pdf is encrypted. Sets/Gets the info structure of the document. Example:
%h = $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" ); print "Author: $h{Author}\n";Sets/Gets the supported info-structure tags. Example:
@attrs = $pdf->infoMetaAttributes; print "Supported Attributes: @attr\n"; @attrs = $pdf->infoMetaAttributes('CustomField1'); print "Supported Attributes: @attr\n";Sets/Gets the XMP XML data-stream. Example:
$xml = $pdf->xmpMetadata; print "PDFs Metadata reads: $xml\n"; $xml=<<EOT; <?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?> <?adobe-xap-filters esc="CRLF"?> <x:xmpmeta xmlns:x='adobe:ns:meta/' x:xmptk='XMP toolkit 2.9.1-14, framework 1.6'> <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' xmlns:iX='http://ns.adobe.com/iX/1.0/'> <rdf:Description rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8' xmlns:pdf='http://ns.adobe.com/pdf/1.3/' pdf:Producer='Acrobat Distiller 6.0.1 for Macintosh'></rdf:Description> <rdf:Description rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8' xmlns:xap='http://ns.adobe.com/xap/1.0/' xap:CreateDate='2004-11-14T08:41:16Z' xap:ModifyDate='2004-11-14T16:38:50-08:00' xap:CreatorTool='FrameMaker 7.0' xap:MetadataDate='2004-11-14T16:38:50-08:00'></rdf:Description> <rdf:Description rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8' xmlns:xapMM='http://ns.adobe.com/xap/1.0/mm/' xapMM:DocumentID='uuid:919b9378-369c-11d9-a2b5-000393c97fd8'/> <rdf:Description rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8' xmlns:dc='http://purl.org/dc/elements/1.1/' dc:format='application/pdf'><dc:description><rdf:Alt><rdf:li xml:lang='x-default'>Adobe Portable Document Format (PDF)</rdf:li></rdf:Alt></dc:description><dc:creator><rdf:Seq><rdf:li>Adobe Systems Incorporated</rdf:li></rdf:Seq></dc:creator><dc:title><rdf:Alt><rdf:li xml:lang='x-default'>PDF Reference, version 1.6</rdf:li></rdf:Alt></dc:title></rdf:Description> </rdf:RDF> </x:xmpmeta> <?xpacket end='w'?> EOT $xml = $pdf->xmpMetadata($xml); print "PDFs Metadata now reads: $xml\n";Force objects to be written to file if available. Example:
$pdf = PDF::API2->new(-file => 'our/new.pdf'); ... $pdf->finishobjects($page, $gfx, $txt); ... $pdf->save;
- $pdf->update
-
Updates a previously opened document after all changes have been applied.
Example:
$pdf = PDF::API2->open('our/to/be/updated.pdf'); ... $pdf->update;
Saves the document to file. Example:$pdf = PDF::API2->new(); ... $pdf->saveas("our/new.pdf");
Returns the document in a string. Example:$pdf = PDF::API2->new(); ... print $pdf->stringify;
- $pdf->end
- Destroys the document.
PAGE METHODS
Returns a new page object or inserts-and-returns a new page at CW$index. Note: on CW$index
-1 ... is inserted before the last page 1 ... is inserted before page number 1 (the first page) 0 ... is simply appendedReturns the pageobject of page CW$index. Note: on CW$index
-1,0 ... returns the last page 1 ... returns page number 1Example: (A Document with 99 Pages)
$page = $pdf->openpage(1); # returns the first page $page = $pdf->openpage(9); # returns the last page $page = $pdf->openpage(-1); # returns the last page $page = $pdf->openpage(9); # returns undefReturns a form-xobject created from CW$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 CW$index
-1,0 ... returns the last page 1 ... returns page number 1Example:
$pdf = PDF::API2->new; $old = PDF::API2->open('my/old.pdf'); $xo = $pdf->importPageIntoForm($old,2); # get page 2 $page = $pdf->page; $gfx = $page->gfx; $gfx->formimage($xo,0,0,1); # put it on page 1 with scale x1 $pdf->saveas("our/new.pdf");Returns the pageobject of page CW$targetindex, imported from CW$sourcepdf,$sourceindex. Note: on CW$index
-1,0 ... returns the last page 1 ... returns page number 1Note: you can specify a page object instead as CW$targetindex so that the contents of the sourcepage will be 'merged into'. Example:
$pdf = PDF::API2->new; $old = PDF::API2->open('my/old.pdf'); $page = $pdf->importPage($old,2); # get page 2 into page 1 $pdf->saveas("our/new.pdf");Returns the number of pages in the document. Sets the global mediabox. Other methods: cropbox, bleedbox, trimbox and artbox. Example:
$pdf = PDF::API2->new; $pdf->mediabox('A4'); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->mediabox(595,842); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->mediabox(0,0,595,842); ... $pdf->saveas("our/new.pdf");Sets the global cropbox. Example:
$pdf = PDF::API2->new; $pdf->cropbox('A4'); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->cropbox(595,842); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->cropbox(0,0,595,842); ... $pdf->saveas("our/new.pdf");Sets the global bleedbox. Example:
$pdf = PDF::API2->new; $pdf->bleedbox('A4'); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->bleedbox(595,842); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->bleedbox(0,0,595,842); ... $pdf->saveas("our/new.pdf");Sets the global trimbox. Example:
$pdf = PDF::API2->new; $pdf->trimbox('A4'); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->trimbox(595,842); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->trimbox(0,0,595,842); ... $pdf->saveas("our/new.pdf");Sets the global artbox. Example:
$pdf = PDF::API2->new; $pdf->artbox('A4'); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->artbox(595,842); ... $pdf->saveas("our/new.pdf");
$pdf = PDF::API2->new; $pdf->artbox(0,0,595,842); ... $pdf->saveas("our/new.pdf");
FONT METHODS
Adds one or more directories to the search-path for finding font files. Returns the list of searched directories. 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 CW%options are:
'-encode' ... changes the encoding of the font from its default.
'-dokern' ... enables kerning if data is available.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 CW%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)
'-dokern' ... enables kerning if data is available.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 CW%options are:
'-encode' ... changes the encoding of the font from its default.
'-isocmap' ... per default the MS Unicode Map is used, if this option is given the ISO Unicode Map will be used.
'-dokern' ... enables kerning if data is available.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 CW%options are:
'-encode' ... changes the encoding of the font from its default.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 degreesValid CW%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) Returns a new BDF font object, based on the specified adobe-bdf file. See PDF::API2::Resource::Font::BdFont for an explanation. 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 CW%options are:
'-encode' ... changes the encoding of the font from its default.
IMAGE METHODS
Returns a new jpeg image object. Returns a new tiff image object. Returns a new pnm image object. Returns a new png image object. Returns a new gif image object. Returns a new image object from GD::Image. Options: The only option currently supported is CW-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
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. Returns a new colorspace-object based on the web color palette. See PDF::API2::Resource::ColorSpace::Indexed::WebColor for an explanation. Returns a new colorspace-object based on the hue color palette. See PDF::API2::Resource::ColorSpace::Indexed::Hue for an explanation. 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. 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
creates the specified barcode object as a form-xo.
OTHER METHODS
Returns a new form-xobject. Examples:
$xo = $pdf->xo_form;Returns a new extended graphics state object. Examples:
$egs = $pdf->egstate;Returns a new pattern-object. Returns a new shading-object. Returns a new or existing outlines object.
RESOURCE METHODS
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 2.0 2005/11/16 02:16:00 areibens revision workaround for SF cvs import not to screw up CPAN
Revision 1.2 2005/11/16 01:27:48 areibens genesis2
Revision 1.1 2005/11/16 01:19:24 areibens genesis
Revision 1.86 2005/10/21 19:51:05 fredo fixed proc_pages
Revision 1.85 2005/10/20 21:06:39 fredo documented '-dokern' option for ttfonts
Revision 1.84 2005/10/19 21:23:26 fredo documented '-dokern' option for core- and psfonts
Revision 1.83 2005/09/12 16:54:21 fredo added -isocmap option
Revision 1.82 2005/06/17 19:43:45 fredo fixed CPAN modulefile versioning (again)
Revision 1.81 2005/06/17 18:53:04 fredo fixed CPAN modulefile versioning (dislikes cvs)
Revision 1.80 2005/06/10 16:12:49 fredo documentation update
Revision 1.79 2005/03/23 16:42:06 fredo fixed typo in infoMetaAttributes
Revision 1.78 2005/03/21 22:36:36 fredo fix for landscape imports
Revision 1.77 2005/03/15 17:31:06 fredo corrected utf8 handling in info tags
Revision 1.76 2005/03/14 23:53:51 fredo added xmpMetadata method to get/set XMP document data
Revision 1.75 2005/03/14 22:01:05 fredo upd 2005
Revision 1.74 2005/02/25 18:07:48 fredo no message
Revision 1.73 2005/02/17 07:03:14 fredo added 'pageencaps' default option to fix unusual styled content streams
Revision 1.72 2005/02/14 20:09:48 fredo fixed an openpage recompression bug / thanks to steve_wu@iinet.net.au
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