PDF::API2

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 %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 = 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.

$pdf->info %infohash

Sets the info structure of the document.

$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

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:

As of version 0.2.3.4 the development of the PNG import methods has been discontinued in favor of the GD::Image import facility.

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

$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