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 $fontname, $ttfile

$pdf->newFont $fontname, $psffile, $afmfile

$pdf->newFont $fontname

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

BEWARE: Postscript fonts other than the core fonts are supported, BUT the implementation is still somewhere in alpha/beta stage and may not result in valid pdf-files under certain conditions.

NOTE: this function is for BACKWARD COMPATIBLITY ONLY (as of version 0.5) and will be removed sometime before version 1.0.

RECOMMENDATION: Start using the following three functions below.

$pdf->newFontCore $fontname [, $encoding [, @glyphs ]]

$pdf->newFontTTF $fontname, $ttffile [, $encoding ]

$pdf->newFontPS $fontname, $psffile, $afmfile [, $encoding [, @glyphs ]]

Although you can add a font thru the $pdf->newFont function, these three new functions are much more stable (newFontPS is alpha-quality) and reliable.

The $encoding is the name of one of the encoding schemes supported by Unicode::Map8, 'asis' or 'custom'. If you use 'custom' as encoding, you have to supply the @glyphs array which should specify 256 glyph-names as defined by the "PostScript(R) Language Reference 3rd. Ed. -- Appendix E"

If you do not give $encoding or 'asis', than the afms internal encoding is used.

If you give an unknown $encoding, the encoding defaults to WinAnsiEncoding.

$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 parameter with $pdf->newFont

If you do not give $encoding, than the encoding from $pdf->newFont??? is used.

NOTE: As of version API 0.5 you can specify any encoding supported by Unicode::Map8, since the fonts are automagically reencoded to use the new encoding if it differs from that encoding specified at $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

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.

( $key , $width , $height ) = $pdf->rawImage $name, $width $height $type @imagearray

This function supports loading of point-arrays for embedding image information into the pdf. $type must be one of the following:

'-rgb' ... each element of the array is a color component
		in the range of 0..255
'-RGB' ... each element of the array is a hex-encoded color pixel
		with two hex-digits per color component

$name must be a unique name for this image (at least 8 characters long).

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

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

Version 0.05 (Oct. 2000)

major rewrite to use Unicode::Map8 instead of the homegrown functions :) , add another dependency but at least a fast one

Versions 0.5_pre??? (Dec. 2000)

major rewrite of font-handling routines stalls the tutorial/exaples collection. now adobe-type1 fonts (pfb/pfa + afm) and the core-fonts can be used the same way as truetype with the Unicode::Map8 encodings.

Version 0.5 (07-01-2001)

documemtation update and release of the much hacked 0.5_pre??? code :)

Version 0.5001 to 0.5003

minor bugfixes:

under certain conditions the 'image' functions stopped working, thanks to Lester Hightower [hightowe@TheAIMSGroup.com] for reporting that bug. hope that my newly invented "nigma-hash" keygenerator fixes this.

the symbol and zapfdingbat corefonts did not work ... since they missed attributes and had wrong font-flags set ... doesn't anybody use them ?

BUGS

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

TODO ( in no particular order )

documentation ?

drawing functions ?

more encodings ?

fix encoding for core fonts ?

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

To install Text::PDF::API, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Text::PDF::API

CPAN shell

perl -MCPAN -e shell
install Text::PDF::API

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)