Text::PDF::API - a wrapper api for the Text::PDF::* modules of Martin Hosken.
use Text::PDF::API;
$pdf = Text::PDF::API->new( %defaults );
$pdf->end;
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.
This creates the pdf-info-object and initializes it with the given values.
This saves the pdf-object to a file indicated by $file.
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.
This destroys the pdf-object and frees its memory.
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)
This sets the pdf-object defaults (see $pdf->getDefault for details).
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.
This closes the current page.
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.
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.
Sets the default font search directory.
Gets the default font search directory.
Adds a directory to the font search path.
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.
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.
This is a shortcut to add all pdf-core-fonts to the pdf-object.
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 !!!
Sets the translation (aka. x,y-offset) in the Font-Transformation-Matrices.
Sets the scale in the Font-Transformation-Matrices.
Sets the skew in the Font-Transformation-Matrices specified in degrees (0..360).
Sets the rotation in the Font-Transformation-Matrices specified in degrees (0..360) counter-clock-wise from the right horizontal.
Resets all Font-Transformation-Matrices.
Calculates the final Transformation-Matrix for use with the *Text* functions.
Sets the final Transformation-Matrix directly.
Returns the final Transformation-Matrix. Use $pdf->calcFontMatrix and then $pdf->getFontMatrix to retrive the combined effects of Translate, Skew, Scale & Rotate.
Starts a text block.
Ends a text block
Sets the parameter for the text-block only. If parameter is not given the default as defined by $pdf->set* is used.
Sets a new text position, but honoring the current FontMatrix.
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 !!!
Adds text to the text-block.
Moves the text-pointer to a new line using TextLeading as default.
Calculates the width of the text based on the parameters set by useFont.
BEWARE: Does not consider parameters specified by setFont* and *Matrix
functions.
Calculates the width of the text without needing useFont.
BEWARE: Does not consider parameters specified by setFont* and *Matrix
functions.
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 !
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 !
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.
Displays the $text based on the parameters given by the *Font*
functions.
Like $pdf->showText but overrides the x,y-offsets of the Matrices. The
*_R and *_C variants perform right and center
alignment !
Like a $pdf->useFont followed by a $pdf->showTextXY.
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.
Adds the parameters of the functions above to the current graphics state. To revert to the former parameters use $pdf->savePdfState and $pdf->restorePdfState.
quot errat demonstrandum
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.
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).
GENESIS
inital implementation without documentation
you can create pages, still no docs
various conceptual design stages
first public snapshot with some docs and first implementation of font caching (released as 0.01_12_snapshot)
reimplementaion of font-handling with unification of core and truetype fonts under the function ``newFont''
implementaion of font-encoding for truetypes
reimplementaion of font-encoding thru CID because Acrobat seems to ignore encoding tables for TTs when using normal embedding
implementaion of printText, useFont, showText & showTextXY
implementaion of *FontMatrix functions, changes in showText
& showTextXY
addition of setFontTranslate, Skew, Rotate & Scale with cleanup in
*FontMatrix
end of text/font implementation, let it stabilize :)
genesis of the graphical interface (CTM handling copied from fonts)
added text and graphic state functions
cleanup/extension of dokumentation, but still not finished
proposed implementation of drawing functions (NOT FINISHED)
finished implemetation of needed drawing functions
bugfixes in drawing and font functions first implementation of state functions
first implementation of bitmap functions
bugfixes in text/font functions
added support for loading of PNM(netpbm) and PNG bitmaps
added circle and ellipsis drawing functions
fixed calcTextWidth to allow the type1 core fonts to be measured too. added showTextXY_R and _C functions for alignment procedures :)
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
major rewrite to use Unicode::Map8 instead of the homegrown functions :) , add another dependency but at least a fast one
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.
documemtation update and release of the much hacked 0.5_pre??? code :)
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 ?
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.
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.
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.
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.
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
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).
MANY! If you find some report them to perl-text-pdf-modules@yahoogroups.com.
documentation ?
drawing functions ?
more bitmap import functions (jpeg,tiff,xbm,xpm,...?)
function to populate a Text::PDF::API object from an existing pdf-file ?