NAME¶
PDF::API2 - Facilitates the creation and modification of PDF files
SYNOPSIS¶
use PDF::API2;
# Create a blank PDF file
$pdf = PDF::API2->new();
# Open an existing PDF file
$pdf = PDF::API2->open('some.pdf');
# Add a blank page
$page = $pdf->page();
# Retrieve an existing page
$page = $pdf->openpage($page_number);
# Set the page size
$page->mediabox('Letter');
# Add a built-in font to the PDF
$font = $pdf->corefont('Helvetica-Bold');
# Add an external TTF font to the PDF
$font = $pdf->ttfont('/path/to/font.ttf');
# Add some text to the page
$text = $page->text();
$text->font($font, 20);
$text->translate(200, 700);
$text->text('Hello World!');
# Save the PDF
$pdf->saveas('/path/to/new.pdf');
GENERIC METHODS¶
- $pdf = PDF::API2->new(%options)
- Creates a new PDF object. If you will be saving it as a
file and already know the filename, 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();
- $pdf = PDF::API2->open($pdf_file)
- Opens an existing PDF file.
Example:
$pdf = PDF::API2->open('our/old.pdf');
...
$pdf->saveas('our/new.pdf');
$pdf = PDF::API2->open('our/to/be/updated.pdf');
...
$pdf->update();
- $pdf = PDF::API2->openScalar($pdf_string)
- Opens a PDF contained in a string.
Example:
# Read a PDF into a string, for the purpose of demonstration
open $fh, 'our/old.pdf' or die $@;
undef $/; # Read the whole file at once
$pdf_string = <$fh>;
$pdf = PDF::API2->openScalar($pdf_string);
...
$pdf->saveas('our/new.pdf');
- $pdf->preferences(%options)
- 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.
- -twocolumnright
- 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.
- -printscalingnone
- Set the default print setting for page scaling to
none.
Initial Page Options:
- -firstpage => [ $page, %options ]
- 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 => [$page, -fit => 1],
);
- $val = $pdf->default($parameter)
- $pdf->default($parameter, $value)
- Gets/sets the default value for a behaviour of PDF::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*).
- $bool = $pdf->isEncrypted()
- Checks if the previously opened PDF is encrypted.
- %infohash = $pdf->info(%infohash)
- Gets/sets 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";
- @metadata_attributes =
$pdf->infoMetaAttributes(@metadata_attributes)
- Gets/sets the supported info-structure tags.
Example:
@attributes = $pdf->infoMetaAttributes;
print "Supported Attributes: @attr\n";
@attributes = $pdf->infoMetaAttributes('CustomField1');
print "Supported Attributes: @attributes\n";
- $xml = $pdf->xmpMetadata($xml)
- Gets/sets 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: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 "PDF metadata now reads: $xml\n";
- $pdf->pageLabel($index, $options)
- Sets page label options.
Supported Options:
- -style
- Roman, roman, decimal, Alpha or alpha.
- -start
- Restart numbering at given number.
- -prefix
- Text prefix for numbering.
Example:
# Start with Roman Numerals
$pdf->pageLabel(0, {
-style => 'roman',
});
# Switch to Arabic
$pdf->pageLabel(4, {
-style => 'decimal',
});
# Numbering for Appendix A
$pdf->pageLabel(32, {
-start => 1,
-prefix => 'A-'
});
# Numbering for Appendix B
$pdf->pageLabel( 36, {
-start => 1,
-prefix => 'B-'
});
# Numbering for the Index
$pdf->pageLabel(40, {
-style => 'Roman'
-start => 1,
-prefix => 'Index '
});
- $pdf->finishobjects(@objects)
- Force objects to be written to file if possible.
Example:
$pdf = PDF::API2->new(-file => 'our/new.pdf');
...
$pdf->finishobjects($page, $gfx, $txt);
...
$pdf->save();
- $pdf->update()
- Saves a previously opened document.
Example:
$pdf = PDF::API2->open('our/to/be/updated.pdf');
...
$pdf->update();
- $pdf->saveas($file)
- Saves the document to file.
Example:
$pdf = PDF::API2->new();
...
$pdf->saveas('our/new.pdf');
- $string = $pdf->stringify()
- Returns the document as a string.
Example:
$pdf = PDF::API2->new();
...
print $pdf->stringify();
- $pdf->end()
- Destroys the document.
PAGE METHODS¶
- $page = $pdf->page()
- $page = $pdf->page($page_number)
- Returns a new page object. By default, the page is added to
the end of the document. If you include an existing page number, the new
page will be inserted in that position, pushing existing pages back.
$page_number can also have one of the following values:
- -1 inserts the new page as the second-last page
- 0 inserts the page as the last page
Example:
$pdf = PDF::API2->new();
# Add a page. This becomes page 1.
$page = $pdf->page();
# Add a new first page. $page becomes page 2.
$another_page = $pdf->page(1);
- $page = $pdf->openpage($page_number)
- Returns the PDF::API2::Page object of page $page_number.
If $page_number is 0 or -1, it will return the last page in the document.
Example:
$pdf = PDF::API2->open('our/99page.pdf');
$page = $pdf->openpage(1); # returns the first page
$page = $pdf->openpage(99); # returns the last page
$page = $pdf->openpage(-1); # returns the last page
$page = $pdf->openpage(999); # returns undef
- $xoform = $pdf->importPageIntoForm($source_pdf,
$source_page_number)
- Returns a Form XObject created by extracting the specified
page from $source_pdf.
This is useful if you want to transpose the imported page somewhat
differently onto a page (e.g. two-up, four-up, etc.).
If $source_page_number is 0 or -1, it will return the last page in the
document.
Example:
$pdf = PDF::API2->new();
$old = PDF::API2->open('our/old.pdf');
$page = $pdf->page();
$gfx = $page->gfx();
# Import Page 2 from the old PDF
$xo = $pdf->importPageIntoForm($old, 2);
# Add it to the new PDF's first page at 1/2 scale
$gfx->formimage($xo, 0, 0, 0.5);
$pdf->saveas('our/new.pdf');
Note: You can only import a page from an existing PDF file.
- $page = $pdf->importpage($source_pdf,
$source_page_number, $target_page_number)
- Imports a page from $source_pdf and adds it to the
specified position in $pdf.
If $source_page_number or $target_page_number is 0 or -1, the last page in
the document is used.
Note: If you pass a page object instead of a page number for
$target_page_number, the contents of the page will be merged into the
existing page.
Example:
$pdf = PDF::API2->new();
$old = PDF::API2->open('our/old.pdf');
# Add page 2 from the old PDF as page 1 of the new PDF
$page = $pdf->importpage($old, 2);
$pdf->saveas('our/new.pdf');
Note: You can only import a page from an existing PDF file.
- $count = $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.
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');
- $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¶
- @directories = PDF::API2::addFontDirs($dir1, $dir2,
...)
- 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.
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.
- -dokern
- Enables kerning if data is available.
See Also: PDF::API2::Resource::Font::CoreFont.
- $font = $pdf->psfont($ps_file, [%options])
- Returns a new Adobe Type1 font object.
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 the location of the font metrics file.
- -pfmfile
- Specifies the location of the printer font metrics file.
This option overrides the -encode option.
- -dokern
- Enables kerning if data is available.
- $font = $pdf->ttfont($ttf_file, [%options])
- Returns a new TrueType or OpenType font object.
Examples:
$font = $pdf->ttfont('Times.ttf');
$font = $pdf->ttfont('Georgia.otf');
Valid %options are:
- -encode
- Changes the encoding of the font from its default.
- -isocmap
- Use the ISO Unicode Map instead of the default MS Unicode
Map.
- -dokern
- Enables kerning if data is available.
- -noembed
- Disables embedding of the font file.
- $font = $pdf->cjkfont($cjkname, [%options])
- Returns a new CJK font object.
Examples:
$font = $pdf->cjkfont('korean');
$font = $pdf->cjkfont('traditional');
Valid %options are:
- -encode
- Changes the encoding of the font from its default.
See Also: PDF::API2::Resource::CIDFont::CJKFont
- $font = $pdf->synfont($basefont, [%options])
- Returns a new synthetic font object.
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
- Emboldening factor (0.1+, bold = 1, heavy = 2, ...)
- -space
- Additional character spacing in ems (0-1000)
See Also: PDF::API2::Resource::Font::SynFont
- $font = $pdf->bdfont($bdf_file)
- Returns a new BDF font object, based on the specified Adobe
BDF file.
See Also: PDF::API2::Resource::Font::BdFont
- $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 Also: PDF::API2::Resource::UniFont.
Valid %options are:
- -encode
- Changes the encoding of the font from its default.
IMAGE METHODS¶
- $jpeg = $pdf->image_jpeg($file)
- Imports and returns a new JPEG image object.
- $tiff = $pdf->image_tiff($file)
- Imports and returns a new TIFF image object.
- $pnm = $pdf->image_pnm($file)
- Imports and returns a new PNM image object.
- $png = $pdf->image_png($file)
- Imports and returns a new PNG image object.
- $gif = $pdf->image_gif($file)
- Imports and returns a new GIF image object.
- $gdf = $pdf->image_gd($gd_object, %options)
- Imports and returns a new image object from GD::Image.
Options: The only option currently supported is "-lossless
=> 1".
COLORSPACE METHODS¶
- $cs = $pdf->colorspace_act($file)
- Returns a new colorspace object based on an Adobe Color
Table file.
See PDF::API2::Resource::ColorSpace::Indexed::ACTFile for a reference to the
file format's specification.
- $cs = $pdf->colorspace_web()
- Returns a new colorspace-object based on the web color
palette.
- $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 will automatically be 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 will automatically be chosen based on the first
colorspace specified.
BARCODE METHODS¶
- $bc = $pdf->xo_codabar(%options)
- $bc = $pdf->xo_code128(%options)
- $bc = $pdf->xo_2of5int(%options)
- $bc = $pdf->xo_3of9(%options)
- $bc = $pdf->xo_ean13(%options)
- Creates the specified barcode object as a form
XObject.
OTHER METHODS¶
- $xo = $pdf->xo_form()
- Returns a new form XObject.
- $egs = $pdf->egstate()
- Returns a new extended graphics state object.
- $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.
BUGS¶
This module does not work with perl's -l command-line switch.
AUTHOR¶
PDF::API2 was originally written by Alfred Reibenschuh.
It is currently being maintained by Steve Simms.