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

- NAME
- SYNOPSIS
- DESCRIPTION
  - Base Methods
  - Generic Methods
  - Font State Methods
  - Text Block Methods
  - Text Utility Methods
  - Graphic State Methods
  - Color Methods
  - Drawing Methods
  - Bitmap Methods
- HISTORY
- THANKS
- PLUG-INS
- BUGS
- TODO ( in no particular order )

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

  Note: The following methods can only be used in between beginText/endText !!!

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

$pdf->endText

  Ends a text block

## 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 ?