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 Methods
  - Graphic State Methods
  - Color Methods
  - Drawing Methods
  - Bitmap Methods
- HISTORY
- 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->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)

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

# 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, ...?)