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

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.

Examples:

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

$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',
	-alternate => 'DeviceRGB',
	-components => 3,
	-iccfile => 'codacus.icc'
);

$img = $pdf->barcode %options

Returns a new barcode object.

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

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

Note:

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->barcode $bcobj, $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

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

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