PDF::API2
NAME
PDF::API2 - The Next Generation API for creating and modifing PDFs.
SYNOPSIS
use
PDF::API2;
= PDF::API2->new;
= PDF::API2->
open
(
'some.pdf'
);
$page
=
->page;
$page
=
->openpage(
$pagenum
);
$img
=
->image(
'some.jpg'
);
$font
=
->corefont(
'Times-Roman'
);
$font
=
->psfont(
'Times-Roman.pfb'
,
'Times-Roman.afm'
);
$font
=
->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
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
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
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: imagejpeg, imagepng, imagegd, imagepnm.
- $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
3 POD Errors
The following errors were encountered while parsing the POD:
- Around line 77:
'=item' outside of any '=over'
- Around line 135:
Non-ASCII character seen before =encoding in 'document’s'. Assuming CP1252
- Around line 1521:
You forgot a '=back' before '=head1'