/ 
Text-PDF-API-0.042
/ Text::PDF::API

NAME

Text::PDF::API - a wrapper api for the Text::PDF::* modules of Martin Hosken.

SYNOPSIS

use Text::PDF::API;

$pdf = Text::PDF::API->new( %defaults );

$pdf->end;

DESCRIPTION

Base Methods

$pdf = Text::PDF::API->new [%defaults]

This creates a new pdf-object initializes it with the given defaults and returns it. See the functions getDefault and setDefault for a list of supported parameters.

$pdf->saveas $file

This saves the pdf-object to a file indicated by $file.

$pdf->end

This destroys the pdf-object and frees its memory.

$pdf->getDefault $parameter

This returns the pdf-object default indicated by $parameter.

The current supported defaults are:

PageSize, valid values:

'a0'		=>	[ 2380	, 3368	]
'a1'		=>	[ 1684	, 2380	]
'a2'		=>	[ 1190	, 1684	]
'a3'		=>	[ 842	, 1190	]
'a4'		=>	[ 595	, 842	]
'a5'		=>	[ 421	, 595	]
'a6'		=>	[ 297	, 421	]
'letter'	=>	[ 612	, 792	]
'broadsheet'	=>	[ 1296	, 1584	]
'ledger'	=>	[ 1224	, 792	]
'tabloid'	=>	[ 792	, 1224	]
'legal'		=>	[ 612	, 1008	]
'executive'	=>	[ 522	, 756	]
'36x36'		=>	[ 2592	, 2592	]

PageWidth, valid values:

0 .. 32535 points (remember default = 72dpi)

PageHeight, valid values:

0 .. 32535 points (remember default = 72dpi)

PageOrientation, valid values:

Landscape, Portrait

Compression

0, 1 (= off, on)

PDFVersion

0 .. 3 (corresponding to the adobe acrobat versions up to 4.0)
$pdf->setDefault $parameter , $value

This sets the pdf-object defaults (see $pdf->getDefault for details).

$pdf->newpage [ $width, $height ]
$pdf->newpage [ $pagesize ]

This creates a new page in the pdf-object and assigns it to the default page context. If $width and $height are not given the funtion falls back to any given defaults (PageSize then PageWidth+PageHeight) and as a last resort to 'A4'. You can use also specify oonly the Pagesize as given under the defaults.

$pdf->endpage

This closes the current page.

Generic Methods

$pdf->savePdfState
$pdf->restorePdfState

Saves and restores the state of the pdf-document BUT NOT of the pdf-object.

BEWARE: Don't cross page boundaries with save/restore, if you really don't know the pdf-specification well enough.

$pdf->saveState {currently broken}
$pdf->restoreState {currently broken}

Saves and restores the state of the pdf-object and the underlying document.

NOTE: All states are automagically restored if you issue a $pdf->endpage.

Font State Methods

$pdf->setFontDir $directory

Sets the default font search directory.

$directory = $pdf->getFontDir

Gets the default font search directory.

$pdf->addFontPath $directory

Adds a directory to the font search path.

$pdf->newFont $name, $ttfile [, $encoding ]
$pdf->newFont $name

Adds a new font to the pdf-object. Based on the fonts name either a core, truetype or postscript font is assumed: TrueType have a ',' between the family and style names whereas the postscript and core fonts use a '-'.

Postscript fonts are encoded based on platform:

Mac	=> MacRoman
MSWin32	=> WinAnsi
Other	=> ISO-8559-1

The supported encodings of truetype fonts currently include:

AdobeStandard, AdobeSymbol, ZapfDingbats, 
ISOLatin1, MacRoman, 
MicrosoftAnsi (WinAnsi, CP1250), 
MicrosoftSymbol (WinSymbol, Symbol)

if the encoding is not specified ISO-8859-1 is used instead.

The pdf-core-fonts Symbol and ZapfDingbats are left as is.

If you would like to use the same font with different encodings just call newFont with a different $encoding parameter, fontcaching will avoid double embedding.

BEWARE: Postscript fonts other than the core fonts are not supported AND you have only one encoding available for the core fonts.

$pdf->addCoreFonts

This is a shortcut to add all pdf-core-fonts to the pdf-object.

$pdf->useFont $name, $size,$encoding

This selects the font at the specified size and encoding. The font must have been loaded with the same $name and $encoding parameters with $pdf->newFont

$pdf->setFontTranslate $tx, $ty

Sets the translation (aka. x,y-offset) in the Font-Transformation-Matrices.

$pdf->setFontScale $scalex, $scaley

Sets the scale in the Font-Transformation-Matrices.

$pdf->setFontSkew $alfa, $beta

Sets the skew in the Font-Transformation-Matrices specified in degrees (0..360).

$pdf->setFontRotation $alfa

Sets the rotation in the Font-Transformation-Matrices specified in degrees (0..360) counter-clock-wise from the right horizontal.

$pdf->clearFontMatrix

Resets all Font-Transformation-Matrices.

$pdf->calcFontMatrix

Calculates the final Transformation-Matrix for use with the *Text* functions.

$pdf->setFontMatrix $a, $b, $c, $d, $e, $f

Sets the final Transformation-Matrix directly.

($a, $b, $c, $d, $e, $f)=$pdf->getFontMatrix

Returns the final Transformation-Matrix. Use $pdf->calcFontMatrix and then $pdf->getFontMatrix to retrive the combined effects of Translate, Skew, Scale & Rotate.

$pdf->setCharSpacing $spacing
$pdf->setWordSpacing $spacing
$pdf->setTextLeading $leading
$pdf->setTextRise $rise
$pdf->setTextRendering $rendering

Text Methods

$pdf->showText $text

Displays the $text based on the parameters given by the *Font* functions.

$pdf->showTextXY $x, $y, $text
$pdf->showTextXY_R $x, $y, $text
$pdf->showTextXY_C $x, $y, $text

Like $pdf->showText but overrides the x,y-offsets of the Matrices. The *_R and *_C variants perform right and center alignment !

$pdf->printText $x, $y, $font, $size, $encoding, $text

Like a $pdf->useFont followed by a $pdf->showTextXY.

$pdf->calcTextWidth $text

Calculates the width of the text based on the parameters set by useFont.

BEWARE: Does not consider parameters specified by setFont* and *Matrix functions.

Graphic State Methods

$pdf->setGfxTranslate $tx, $ty
$pdf->setGfxScale $scalex, $scaley
$pdf->setGfxSkew $alfa, $beta
$pdf->setGfxRotation $alfa
$pdf->clearGfxMatrix
$pdf->calcGfxMatrix
$pdf->setGfxMatrix $a, $b, $c, $d, $e, $f
($a, $b, $c, $d, $e, $f)=$pdf->getGfxMatrix

These functions behave like the the font functions BUT affect the whole global graphics state.

BEWARE: If you use both the Gfx and Font versions of these functions the final result for Text would be the combined effects of both the Gfx and Font parameters.

$pdf->useGfxState

Adds the parameters of the functions above to the current graphics state. To revert to the former parameters use $pdf->savePdfState and $pdf->restorePdfState.

$pdf->useGfxFlatness $flatness
$pdf->useGfxLineCap $linecap
$pdf->useGfxLineDash @dasharray
$pdf->useGfxLineJoin $linejoin
$pdf->useGfxLineWidth $linewidth
$pdf->useGfxMeterlimit $limit

Color Methods

$pdf->setColorFill $red, $green, $blue
$pdf->setColorFill $cyan, $magenta, $yellow, $black
$pdf->setColorFill $gray
$pdf->setColorStroke $red, $green, $blue
$pdf->setColorStroke $cyan, $magenta, $yellow, $black
$pdf->setColorStroke $gray

Drawing Methods

$pdf->moveTo $x, $y
$pdf->lineTo $x, $y
$pdf->curveTo $x1, $y1, $x2, $y2, $x3, $y3
$pdf->rect $x, $y, $w, $h
$pdf->closePath
$pdf->endPath
$pdf->rectXY $x1, $y1, $x2, $y2
$pdf->lineXY $x1, $y1, $x2, $y2
$pdf->ellipsisXYAB $x, $y, $a, $b
$pdf->circleXYR $x, $y, $r
$pdf->stroke
$pdf->closestroke
$pdf->fill
$pdf->closefill
$pdf->fillNZ
$pdf->fillstroke
$pdf->closefillstroke
$pdf->fillstrokeNZ
$pdf->closefillstrokeNZ

quot errat demonstrandum

Bitmap Methods

( $key , $width , $height ) = $pdf->newImage $file
( $key , $width , $height ) = $pdf->newImage $imgobj

Current loading support includes NetPBM images of the RAW_BITS variation and non-interlaced/non-filtered PNG. Transperancy/Opacity information is currently ignored as well as Alpha-Channel information.

The usage of GD::Image (GIF or PNG/JPEG) or Image::* (XBM/XPM) objects will be supported in the near future.

$pdf->placeImage $key, $x, $y, $scalex, $scaley

HISTORY

Version 0.00

GENESIS

Version 0.01

inital implementation without documentation

Version 0.01_01

you can create pages, still no docs

Version 0.01_02 - 0.01_11

various conceptual design stages

Version 0.01_12

first public snapshot with some docs and first implementation of font caching (released as 0.01_12_snapshot)

Version 0.01_14

reimplementaion of font-handling with unification of core and truetype fonts under the function "newFont"

Version 0.01_15

implementaion of font-encoding for truetypes

Version 0.01_16

reimplementaion of font-encoding thru CID because Acrobat seems to ignore encoding tables for TTs when using normal embedding

Version 0.01_17

implementaion of printText, useFont, showText & showTextXY

Version 0.01_18

implementaion of *FontMatrix functions, changes in showText & showTextXY

Version 0.01_19

addition of setFontTranslate, Skew, Rotate & Scale with cleanup in *FontMatrix

Version 0.01_20

end of text/font implementation, let it stabilize :)

Version 0.02

genesis of the graphical interface (CTM handling copied from fonts)

Version 0.02_01

added text and graphic state functions

Version 0.02_02

cleanup/extension of dokumentation, but still not finished

Version 0.02_03

proposed implementation of drawing functions (NOT FINISHED)

Version 0.02_04

finished implemetation of needed drawing functions

Version 0.03

bugfixes in drawing and font functions first implementation of state functions

Version 0.03_01

first implementation of bitmap functions

Version 0.03_02

bugfixes in text/font functions

Version 0.03_03

added support for loading of PNM(netpbm) and PNG bitmaps

Version 0.03_04

added circle and ellipsis drawing functions

Version 0.03_05

fixed calcTextWidth to allow the type1 core fonts to be measured too. added showTextXY_R and _C functions for alignment procedures :)

Version 0.04

rewrite of type1 core-font handling to ease development support for other type1 fonts in future releases of Text::PDF and Text::PDF::API.

small bugfixes in calcTextWidth and showTextXY_[RC].

small documentation update

BUGS

MANY! If you find some report them to perl-text-pdf-modules@egroups.com.

TODO ( in no particular order )

documentation ?

drawing functions ?

more encodings ?

fix encoding for core fonts ?

bitmap import functions (jpeg,xbm,xpm, ...?)