NAME

PDF::API2 - The Next Generation API for creating and modifing PDFs.

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->psfont('Times-Roman.pfb','Times-Roman.afm');
$font = $pdf->ttfont('TimesNewRoman.ttf');

METHODS

PDF::API2

$pdf = PDF::API->new

$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

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

$pdf->info %infohash

Sets the info structure of the document.

$val = $pdf->default $parameter

$pdf->default $parameter, $val

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

$font = $pdf->corefont $fontname [, $lightembed]

Returns a new or existing adobe core font object.

Examples:

$font = $pdf->corefont('Times-Roman',1);
$font = $pdf->corefont('Times-Bold');
$font = $pdf->corefont('Helvetica',1);
$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

$font = $pdf->ttfont $ttfile, $lazy

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');

Beware:

The $lazy option set to 1 will make several assumptions about truetype, used encoding and the reader-application (eg. Adobe Acrobat) to provide easy access to fonts without embedding.

1. API2 assumes the used encoding to be compatible with pdf's 'WinAnsiEncoding' or 'latin1'. This is fixed and cannot be changed !

2. API2 assumes that the fonts is not needed to be embedded and as such that the reader-application (eg. Acrobat 5) supports proper font search or substitution.

3. Encodings of symbol-fonts do not have to be changed, since this should also be handled by the reader-application (eg. Acrobat).

4. Utf8 methods will discard any characters outside of the 'latin1' and 'ms-symbol' ranges.

Benefits:

The $lazy option set to 1 has the following benefits:

1. No font-file will be embedded, saveing space, time and performance for other tasks.

2. You do not have to know where your windows system fonts are located, since instead of specifying a valid fontfile you can use one of the aliases below to use the font.

3. This method is even faster that using a pdf corefont, if your primary target-platform is the "adobe acrobat reader" on windows.

Lazy Example:

$font = $pdf->ttfont('TimesNewRoman',1);

Windows Font Names:

arial arialbold arialitalic arialbolditalic arialblack 
comicsansms comicsansmsbold 
couriernew couriernewbold couriernewitalic couriernewbolditalic 
tahoma tahomabold 
timesnewroman timesnewromanbold timesnewromanitalic timesnewromanbolditalic 
verdana verdanabold verdanaitalic verdanabolditalic 
wingdings

Note:

Please see PDF::API2::xFont for other informations.

$img = $pdf->image $file

Returns a new image object.

Examples:

$img = $pdf->image('yetanotherfun.jpg');
$img = $pdf->image('truly24bitpic.png');
$img = $pdf->image('reallargefile.pnm');

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

$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'
);

$img = $pdf->barcode %options

Returns a new barcode object.

Note: refer to PDF::API2::Barcode for more details.

$otls = $pdf->outlines

Returns a new or existing outlines object.

$page->resource $type, $key, $obj

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.

PDF::API2::Outlines

Subclassed from PDF::API2::Outline.

$otls = PDF::API2::Outlines->new $api

Returns a new outlines object (called from $pdf->outlines).

PDF::API2::Outline

Subclassed from Text::PDF::Dict.

$otl = PDF::API2::Outline->new $api,$parent,$prev

Returns a new outline object (called from $otls->outline).

$otl->title $text

Set the title of the outline.

$sotl=$otl->outline

Returns a new sub-outline.

$otl->dest $pageobj [, %opts]

Sets the destination page of the outline.

PDF::API2::ColorSpace

Subclassed from Text::PDF::Array.

$cs = PDF::API2::ColorSpace->new $pdf, $key, %parameters

Returns a new colorspace object (called from $pdf->colorspace).

PDF::API2::ExtGState

Subclassed from Text::PDF::Dict.

$egs = PDF::API2::ExtGState->new @parameters

Returns a new extgstate object (called from $pdf->extgstate).

$egs->strokeadjust $boolean

$egs->strokeoverprint $boolean

$egs->filloverprint $boolean

$egs->overprintmode $num

$egs->blackgeneration $obj

$egs->blackgeneration2 $obj

$egs->undercolorremoval $obj

$egs->undercolorremoval2 $obj

$egs->transfer $obj

$egs->transfer2 $obj

$egs->halftone $obj

PDF::API2::Font

$font2 = $font->clone $subkey

Returns a clone of a font object.

@glyphs = $font->glyphs $encoding

Returns an array with glyphnames of the specified encoding.

$font->encode $encoding

Changes the encoding of the font object. If you want more than one encoding for one font use 'clone' and then 'encode'.

Note: The following encodings are supported (as of version 0.1.16_beta):

adobe-standard adobe-symbol adobe-zapf-dingbats 
cp1250 cp1251 cp1252 
cp437 cp850
es es2 pt pt2
iso-8859-1 iso-8859-2 latin1 latin2
koi8-r koi8-u
macintosh
microsoft-dingbats

Note: Other encodings must be seperately installed via the pdf-api2-unimaps archive.

$pdfstring = $font->text $text

Returns a properly formated string-representation of $text for use in the PDF.

$wd = $font->width $text

Returns the width of $text as if it were at size 1.

PDF::API2::xFont

Provides special internal font-methods for PDF::API2.

@font_names = PDF::API2::xFont::listwinfonts

Returns an array with all the installed truetype font-names of your windows system, or a default fallback (compatible with Acrobat 5) if under unix.

PDF::API2::CoreFont

Subclassed from Text::PDF::AFont and PDF::API2::Font.

$font = PDF::API2::CoreFont->new @parameters

Returns a adobe core font object (called from $pdf->corefont).

PDF::API2::PSFont

Subclassed from Text::PDF::AFont and PDF::API2::Font.

$font = PDF::API2::PSFont->new @parameters

Returns a adobe type1 font object (called from $pdf->psfont).

PDF::API2::TTFont

Subclassed from Text::PDF::TTFont0 and PDF::API2::Font.

$font = PDF::API2::TTFont->new $pdf,$ttffile,$pdfname

Returns a truetype font object (called from $pdf->ttfont).

$pdfstring = $font->text $text

Returns a properly formated string-representation of $text for use in the PDF.

$pdfstring = $font->text_utf8 $text

Returns a properly formated string-representation of $text for use in the PDF but requires $text to be in UTF8.

$wd = $font->width $text

Returns the width of $text as if it were at size 1.

$wd = $font->width_utf8 $text

Returns the width of $text as if it were at size 1, but requires $text to be in UTF8.

$font->encode $encoding

Changes the encoding of the font object. Since encodings are one virtual in ::API2 for truetype fonts you DONT have to use 'clone'.

PDF::API2::Page

Subclassed from Text::PDF::Pages

$page = PDF::API2::Page->new $pdf, $parent, $index

Returns a page object (called from $pdf->page).

$page = PDF::API2::Page->coerce $pdf, $pdfpage

Returns a page object converted from $pdfpage (called from $pdf->openpage).

$page->update

Marks a page to be updated (by $pdf->update).

$page->mediabox $w, $h

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

Sets the mediabox.

$page->cropbox $w, $h

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

Sets the cropbox.

$page->bleedbox $w, $h

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

Sets the bleedbox.

$page->trimbox $w, $h

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

Sets the trimbox.

$page->artbox $w, $h

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

Sets the artbox.

$gfx = $page->gfx

Returns a graphics content object.

$txt = $page->text

Returns a text content object.

$hyb = $page->hybrid

Returns a hybrid content object.

$ant = $page->annotation

Returns a annotation object.

$page->resource $type, $key, $obj

Adds a resource to the page-inheritance tree.

Example:

$co->resource('Font',$fontkey,$fontobj);
$co->resource('XObject',$imagekey,$imageobj);
$co->resource('Shading',$shadekey,$shadeobj);
$co->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.

PDF::API2::Annotation

Subclassed from Text::PDF::Dict.

$ant = PDF::API2::Annotation->new

Returns a annotation object (called from $page->annotation).

PDF::API2::Content

Subclassed from Text::PDF::Dict.

$co = PDF::API2::Content->new @parameters

Returns a new content object (called from $page->text/gfx).

$co->add @content

Adds @content to the object.

$co->save

Saves the state of the object.

$co->restore

Restores the state of the object.

$co->compress

Marks content for compression on output.

$co->fillcolor $grey

$co->fillcolor $api2colorobject

$co->fillcolor $red, $green, $blue

$co->fillcolor $cyan, $magenta, $yellow, $black

$co->fillcolorbyname $colorname, $ascmyk

$co->fillcolorbyspace $colorspace, @colordef

Sets fillcolor.

$co->strokecolor $grey

$co->strokecolor $api2colorobject

$co->strokecolor $red, $green, $blue

$co->strokecolor $cyan, $magenta, $yellow, $black

$co->strokecolorbyname $colorname, $ascmyk

$co->strokecolorbyspace $colorspace, @colordef

Sets strokecolor.

Defined color-names are:

aliceblue, antiquewhite, aqua, aquamarine, azure,
beige, bisque, black, blanchedalmond, blue, 
blueviolet, brown, burlywood, cadetblue, chartreuse, 
chocolate, coral, cornflowerblue, cornsilk, crimson, 
cyan, darkblue, darkcyan, darkgoldenrod, darkgray, 
darkgreen, darkgrey, darkkhaki, darkmagenta, 
darkolivegreen, darkorange, darkorchid, darkred,
darksalmon, darkseagreen, darkslateblue, darkslategray,
darkslategrey, darkturquoise, darkviolet, deeppink, 
deepskyblue, dimgray, dimgrey, dodgerblue, firebrick, 
floralwhite, forestgreen, fuchsia, gainsboro, ghostwhite, 
gold, goldenrod, gray, grey, green, greenyellow, 
honeydew, hotpink, indianred, indigo, ivory, khaki, 
lavender, lavenderblush, lawngreen, lemonchiffon, 
lightblue, lightcoral, lightcyan, lightgoldenrodyellow, 
lightgray, lightgreen, lightgrey, lightpink, lightsalmon,
lightseagreen, lightskyblue, lightslategray, 
lightslategrey, lightsteelblue, lightyellow, lime, 
limegreen, linen, magenta, maroon, mediumaquamarine, 
mediumblue, mediumorchid, mediumpurple, mediumseagreen, 
mediumslateblue, mediumspringgreen, mediumturquoise, 
mediumvioletred, midnightblue, mintcream, mistyrose, 
moccasin, navajowhite, navy, oldlace, olive, olivedrab, 
orange, orangered, orchid, palegoldenrod, palegreen, 
paleturquoise, palevioletred, papayawhip, peachpuff, 
peru, pink, plum, powderblue, purple, red, rosybrown, 
royalblue, saddlebrown, salmon, sandybrown, seagreen, 
seashell, sienna, silver, skyblue, slateblue, slategray, 
slategrey, snow, springgreen, steelblue, tan, teal, 
thistle, tomato, turquoise, violet, wheat, white, 
whitesmoke, yellow, yellowgreen

or the rgb-hex-notation:

#rgb, #rrggbb, #rrrgggbbb and #rrrrggggbbbb

or the cmyk-hex-notation:

%cmyk, %ccmmyykk, %cccmmmyyykkk and %ccccmmmmyyyykkkk

and additionally the hsv-hex-notation:

!hsv, !hhssvv, !hhhsssvvv and !hhhhssssvvvv

$co->flatness $flat

Sets flatness.

$co->linecap $cap

Sets linecap.

$co->linedash @dash

Sets linedash.

$co->linejoin $join

Sets linejoin.

$co->linewidth $width

Sets linewidth.

$co->meterlimit $limit

Sets meterlimit.

$co->matrix $a,$b,$c,$d,$e,$f

Sets matrix transformation.

$co->translate $x,$y

Sets translation transformation.

$co->scale $sx,$sy

Sets scaleing transformation.

$co->skew $sa,$sb

Sets skew transformation.

$co->rotate $rot

Sets rotation transformation.

$co->transform %opts

Sets transformations (eg. translate, rotate, scale, skew) in pdf-canonical order.

Example:

$co->transform(
	-translate => [$x,$y],
	-rotate    => $rot,
	-scale     => [$sx,$sy],
	-skew      => [$sa,$sb],
)

$co->resource $type, $key, $obj

Adds a resource to the page-inheritance tree.

Example:

$co->resource('Font',$fontkey,$fontobj);
$co->resource('XObject',$imagekey,$imageobj);
$co->resource('Shading',$shadekey,$shadeobj);
$co->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.

PDF::API2::Gfx

Subclassed from PDF::API2::Content.

$gfx = PDF::API2::Gfx->new @parameters

Returns a new graphics content object (called from $page->gfx).

$gfx->matrix $a, $b, $c, $d, $e, $f

Sets the matrix.

$gfx->move $x, $y

$gfx->line $x, $y

$gfx->hline $x

$gfx->vline $y

$gfx->curve $x1, $y1, $x2, $y2, $x3, $y3

$gfx->arc $x, $y, $a, $b, $alfa, $beta, $move

$gfx->ellipse $x, $y, $a, $b

$gfx->circle $x, $y, $r

$gfx->bogen $x1, $y1, $x2, $y2, $r, $move, $larc, $span

$gfx->pie $x, $y, $a, $b, $alfa, $beta

$gfx->pie3d $x, $y, $a, $b, $alfa, $beta, $thickness [, $sides]

$gfx->rect $x1,$y1, $w1,$h1, ..., $xn,$yn, $wn,$hn

$gfx->rectxy $x1,$y1, $x2,$y2

$gfx->poly $x1,$y1, ..., $xn,$yn

$gfx->close

$gfx->endpath

$gfx->clip $nonzero

$gfx->stroke

$gfx->fill $nonzero

$gfx->fillstroke $nonzero

$gfx->image $imgobj, $x,$y, $w,$h

$gfx->image $imgobj, $x,$y, $scale

$gfx->image $imgobj, $x,$y

Please Note: The width/height or scale given is in user-space coordinates which is subject to transformations which may have been specified beforehand.

Per default this has a 72dpi resolution, so if you want an image to have a 150 or 300dpi resolution, you should specify a scale of 72/150 (or 72/300) or adjust width/height accordingly.

$gfx->pdfimage $imgobj, $x, $y, $sx, $sy

$gfx->pdfimage $imgobj, $x, $y, $scale

$gfx->pdfimage $imgobj, $x, $y

Please Note: *TODO*

$gfx->barcode $barcodeobj, $center_x, $center_y, $scale [,$frame]

$gfx->barcode_inline $barcodeobj, $center_x, $center_y, $scale [,$frame]

$gfx->shade $shadeobj, $x1,$y1, $x2,$y2

$gfx->egstate $egsobj

PDF::API2::Text

Subclassed from PDF::API2::Content.

$txt = PDF::API2::Text->new @parameters

Returns a new text content object (called from $page->text).

$txt->matrix $a, $b, $c, $d, $e, $f

Sets the matrix.

$txt->font $fontobj,$size

$txt->charspace $spacing

$txt->wordspace $spacing

$txt->hspace $spacing

$txt->lead $leading

$txt->rise $rise

$txt->render $rendering

$txt->cr $linesize

$txt->nl

$txt->distance $dx,$dy

$txt->text $string

$width = $txt->text $string

Applys text to the content and optionally returns the width of the given text.

Note: Does not consider transformations, but only the set fontsize !

$txt->text_center $string

$txt->text_right $string

$txt->text_utf8 $utf8string

$txt->textln $string1, ..., $stringn

Example:

$txt->lead(-10);
$txt->textln($line1,$line2,$line3);

PDF::API2::Hybrid

Subclassed from PDF::API2::Gfx+Text+Content.

$hyb = PDF::API2::Hybrid->new @parameters

Returns a new hybrid content object (called from $page->hybrid).

$hyb->matrix $a, $b, $c, $d, $e, $f

Sets the matrix.

$hyb->textstart

$hyb->textend

PDF::API2::PdfImage

Subclassed from PDF::API2::Hybrid.

$wd = $img->width

$ht = $img->height

PDF::API2::Barcode

Subclassed from PDF::API2::Hybrid.

$bc = PDF::API2::Barcode->new $pdfkey, %options

Returns a new barcode object (called from $pdf->barcode).

Example:

PDF::API2::Barcode->new(
	$key,
	-font	=> $fontobj,	# the font to use for text
	-type	=> '3of9',	# the type of barcode
	-code	=> '0123456789', # the code of the barcode
	-extn	=> '012345',	# the extension of the barcode
				# (if applicable)
	-umzn	=> 10,		# (u)pper (m)ending (z)o(n)e
	-lmzn	=> 10,		# (l)ower (m)ending (z)o(n)e
	-zone	=> 50,		# height (zone) of bars 	
	-quzn	=> 10,		# (qu)iet (z)o(n)e
	-ofwt	=> 0.01,	# (o)ver(f)low (w)id(t)h
	-fnsz	=> 10,		# (f)o(n)t(s)i(z)e
	-text	=> 'alternative text'
);

Note: There is currently only support for the following barcodes:

3of9, 3of9ext, 3of9chk, 3of9extchk,
code128a, code128b, code128c, ean128

$wd = $bc->width

$ht = $bc->height

PDF::API2::Image

$img = PDF::API2::Image->new $pdf, $imgfile

Returns a new image object (called from $pdf->image).

$wd = $img->width

$ht = $img->height

AUTHOR

alfred reibenschuh

cpanm PDF::API2

perl -MCPAN -e shell
install PDF::API2