The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Text-PDF-API-0.699.874
++
/ 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->info $title, $subject, $creator, $author, $keywords

This creates the pdf-info-object and initializes it with the given values.

$pdf->saveas $file

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

$pdf->stringify

This returns the PDF as a string rather than saving to a file. You usually may want to do this if you are donig CGI or Mail work and have enough memory or dont want to clean up your temporary files.

$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 , '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.699 you can specify the following encodings: adobe-standard adobe-symbol adobe-zapf-dingbats ansi-x3-110-1983 ansi-x3-4-1968 asmo-449 bs-4730 bs-viewdata cp037 cp10000 cp10006 cp10007 cp10029 cp10079 cp10081 cp1026 cp1250 cp1251 cp1252 cp1253 cp1254 cp1255 cp1256 cp1257 cp1258 cp437 cp500 cp737 cp775 cp850 cp852 cp855 cp857 cp860 cp861 cp862 cp863 cp864 cp865 cp866 cp866lr cp869 cp874 cp875 csa-z243-4-1985-1 csa-z243-4-1985-2 csa-z243-4-1985-gr csn-369103 dec-mcs din-66003 dk-us ds-2089 ebcdic-at-de-a ebcdic-at-de ebcdic-ca-fr ebcdic-dk-no-a ebcdic-dk-no ebcdic-es-a ebcdic-es-s ebcdic-es ebcdic-fi-se-a ebcdic-fi-se ebcdic-fr ebcdic-it ebcdic-pt ebcdic-uk ebcdic-us ecma-cyrillic es es2 gb-1988-80 gost-19768-74 greek-ccitt greek7-old greek7 hp-roman8 ibm037 ibm038 ibm1026 ibm273 ibm274 ibm275 ibm277 ibm278 ibm280 ibm281 ibm284 ibm285 ibm290 ibm297 ibm420 ibm424 ibm437 ibm500 ibm850 ibm851 ibm852 ibm855 ibm857 ibm860 ibm861 ibm862 ibm863 ibm864 ibm865 ibm868 ibm869 ibm870 ibm871 ibm880 ibm891 ibm903 ibm904 ibm905 ibm918 iec-p27-1 inis-8 inis-cyrillic inis invariant iso-10367-box iso-2033-1983 iso-5427 iso-5428 iso-646-basic iso-646-irv iso-6937-2-25 iso-6937-2-add iso-8859-1 iso-8859-13 iso-8859-15 iso-8859-2 iso-8859-3 iso-8859-4 iso-8859-5 iso-8859-6 iso-8859-7 iso-8859-8 iso-8859-9 iso-8859-supp iso-ir-90 it jis-c6220-1969-jp jis-c6220-1969-ro jis-c6229-1984-a jis-c6229-1984-b-add jis-c6229-1984-b jis-c6229-1984-hand-add jis-c6229-1984-hand jis-c6229-1984-kana jis-x0201 jus-i-b1-002 jus-i-b1-003-mac jus-i-b1-003-serb koi8-r koi8-u ksc5636 latin-greek-1 latin-greek latin-lap latin1 latin13 latin15 latin2 latin3 latin4 latin5 latin6 latin7 latin8 macintosh microsoft-dingbats msz-7795-3 nats-dano-add nats-dano nats-sefi-add nats-sefi nc-nc00-10 nf-z-62-010 ns-4551-1 ns-4551-2 pt pt2 sen-850200-b sen-850200-c t-101-g2 t-61-7bit t-61-8bit us-dk videotex-suppl

NOTE: The fonts are automagically reencoded to use the new encoding if it differs from that encoding specified at $pdf->newFont???.

SPECIAL NOTE: As of 0.699_84 you can specify the special encoding 'ucs2' which enables you to use 16-bit unicode-strings (network-byte ordered) with truetype-fonts only !!!

SPECIAL NOTE: As of 0.699.870 you can specify the special encoding 'utf8' which enables you to use utf8 unicode-strings, but for experimental usage only !

$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 Block Methods

$pdf->beginText

Starts a text block.

$pdf->endText

Ends a text block

$pdf->charSpacing [ $spacing ]
$pdf->wordSpacing [ $spacing ]
$pdf->textLeading [ $leading ]
$pdf->textRise [ $rise ]
$pdf->textRendering [ $rendering ]
$pdf->textMatrix [ @matrix ]

Sets the parameter for the text-block only. If parameter is not given the default as defined by $pdf->set* is used.

$pdf->textPos $mx, $my

Sets a new text position, but honoring the current FontMatrix.

$pdf->textFont [ $font, $size [, $encoding ] ]

Switches the font within the text-block or resets to the last $pdf->useFont. BEWARE: you can only change to a new font before a matrix or pos command since changing it after such command gives pdf-errors !!!

$pdf->textAdd $text

Adds text to the text-block.

$pdf->textNewLine [ $leading ]

Moves the text-pointer to a new line using TextLeading as default.

Text Utility Methods

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

$pdf->calcTextWidthFSET $fontname $size $encoding $text

Calculates the width of the text without needing useFont.

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

($fontsize, $fudgefactor) = $pdf->paragraphFit $font, $encoding, $leadingfactor, $width, $height, $text [, $fudge]

Calculates the the required $fontsize to fit $text into the paragraph $width x $height using $font, $encoding and $leadingfactor. $fudge is a factor used to correct increasing fontsizes in relation to the given $width and common text-patterns (wordlength, ...) found in both english and german languages which defaults to 0.95. The returned $fudgefactor is the actual factor used to calculate $fontsize since the algurithm can only mathematically estimate a fitting contition, but a perfect fit may ll somewhere between $fudgefactor and 1.

BEWARE: this function does a one-shot mathematical estimation which may not be correct under some circumstances !

BEWARE: same limitations as $pdf->calcTextWidthFSET !

($fontsize, $lastdelta) = $pdf->paragraphFit2 $font, $encoding, $leadingfactor, $width, $height, $text [, $maxdelta [, $maxiterations [, $startingfontsize ]]]

As $pdf->paragraphFit above but uses a iterative deterministic algorithm (like $pdf->textParagraph) to estimate the fontsize.

NOTE: this function works best for texts with more that 200 words to put you on the save side with no overflowing text.

BEWARE: this function fails hopelessly for ridiculous parameters and small texts !

($xend, $yend, $overflowtext) = $pdf->textParagraph $x, $y, $width, $height, $text [, $block ]

Positions $text into the paragraph specified by $x, $y, $width and $height. If $block is true the text is block aligned else it is left aligned. The function returns the end position of the text and if the text can not entirely positioned into the paragraph the actual overflow.

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

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
($xs,$ys,$xe,$ye)=$pdf->arcXYabDG $x, $y, $a, $b, $delta, $gamma, $move
($xs,$ys,$xe,$ye)=$pdf->arcXYrDG $x, $y, $r, $delta, $gamma, $move
$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, non-interlaced/non-filtered PNG and non-progressive rgb/cmyk-colorspace JPEGs.

Transperancy/Opacity information is currently ignored as well as Alpha-Channel information.

Note: As of version 0.604 the API supports additional image-formats via XS drop-in modules namely GIF, PPM, BMP (little-endian only).

Special Note: Adobe Photoshop(R) seams to produce errorneous JPEGs with cmyk-colorspace. This cannot be compensated, so either use rgb-JPEGs or use another program to generate these.

( $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, 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 ?

Version 0.6

removed: "nigma-hash" keygenerator had some disadvantages.

added: Digest::REHLHA module for key-generation (this comes with the API).

added: $p->arcXYrDG() and $p->arcXYabDG() to relief users of the (in my opinion) 'mind boggling' bezier-curve function for arcs.

added: $p->info() to include copyright/generator information in the pdf.

added: new text-block functions to ease the use of text.

changed: unicode<->name mapping was broken under perl-5.004xx.

Version 0.6?? to 0.699

major rewrite to remove dependency on Unicode::Map8 which seams to be chronically unavailable under win32 (eg. activestate perl). the internal unicode tables have the same file-format as the '.bin' by Unicode::Map8 so you can copy them over for use with the api as long as the new filename conforms to the following regular expression: /^[a-z0-9\-]+\.map$/

testing scripts remain broken and currently depend on the availibility of Data::DumpXML since Data::Dumper just core-dumps into my face everytime i run them.

Version 0.699_?

Implemetation of a testing-suite, code cleanups , rewitten bitmap-image handling for more modular structure , JPEG is now a native image-format (the usage of the jpeg-plugin is strongly discouraged) with the same limitations as the XS version.

Version 0.699_8?

cleaned up image functions to use x-o's and streamlined key-generation to compensate an arkward behavior of the Text::PDF pdf-parser.

enabled use of ucs2 encoding with ttfs.

Version 0.699.87x

changed versioning to gnu-shtool style

implementated experimental support for utf8 strings

cleaned up unicode handling (more todo)

THANKS

Martin Hosken [mhosken@sil.org] -- for writing Text::PDF in the first place

Lester Hightower [hightowe@TheAIMSGroup.com] -- fixes/reports: perl-5.004xx, key-generation, Makefile.PL

PLUG-INS

As of Version 0.604 bitmapped image loading functions can be extended via XS modules. Currently available: Text-PDF-API-GIF, Text-PDF-API-PPM and Text-PDF-API-BMP (little-endian only).

BUGS

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

TODO ( in no particular order )

documentation ?

drawing functions ?

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

function to populate a Text::PDF::API object from an existing pdf-file ?