pdf4tcl - Pdf document generation
This package provides a container class for generating pdf documents.
All coordinates and distances can be expressed with or without a unit. See UNITS for valid units. When the page is configured with -orient set to false, origin is in the bottom left corner. With -orient true (the default), origin is in the top left corner. Origin is displaced to account for margins, i.e. if margins are 100, the user coordinate (0,0) corresponds to (100,100) on the paper. Page option -orient can also affect the anchor point for things like images.
Any coordinates and distances can be expressed with or without an explicit unit. If no unit is given, the default unit for the document is used. A unit may be one of mm (millimeter), m (millimeter), cm (centimeter), c (centimeter), p (points) or i (inches). Commands returning coordinates or distances always return a double value in the document's default unit.
This command creates a new pdf4tcl object with an associated Tcl command whose name is objectName. This object command is explained in full detail in the sections OBJECT COMMAND and OBJECT METHODS. The object command will be created under the current namespace if the objectName is not fully qualified, and in the specified namespace otherwise. If objectName is %AUTO% a name will generated. The return value is the newly created object's name.
The options and their values coming after the name of the object are used to set the initial configuration of the object. See OBJECT CONFIGURATION.
This call returns the size of a named paper type, e.g. "a4". Paper names are case insensitive. The argument paper may also be a two element list with values as accepted by ::pdf4tcl::getPoints. The return value is a list with width and height in points.
This call returns the list of known paper types.
This call translates a measurement to points (1/72 inch). The format of val is 'num ?unit?' where num is a valid integer or double. See UNITS for valid units. If no unit is given, the value is interpreted as points.
This call loads a TTF font from file to be used by any pdf4tcl objects. The basefontname is used to reference this font. To use this base font in documents, a font with some encoding must be created from it using createFont or createFontSpecEnc.
This call creates a base font from TTF binary data.
This call loads a Type1 font from two files (.afm and .pfb) to be used by any pdf4tcl objects. The basefontname is used to reference this font. To use this base font in documents, a font with some encoding must be created from it using createFont or createFontSpecEnc.
This call creates a base font from AFM text and PFB binary data.
This call creates a font that can be used in documents from a base font. The given encoding defines the (up to) 256 unicode characters that can be drawn when fontname is selected. To use more characters, multiple fonts need to be created and selected based on what needs to be written.
pdf4tcl::loadBaseTrueTypeFont BaseArial "arial.ttf"
pdf4tcl::createFont BaseArial MyArial cp1251
pdf4tcl::loadBaseType1Font BaseType1 "a010013l.afm" "a010013l.pfb"
pdf4tcl::createFont BaseType1 MyType1 cp1251
pdf4tcl::new mypdf -paper a4 -compress 0
mypdf startPage
mypdf setFont 10 MyArial
set txt "\u042D\u0442\u043E \u0442\u0435\u043A\u0441\u0442 \u043D\u0430 \u0440\u0443\u0441\u0441\u043A\u043E\u043C\
\u044F\u0437\u044B\u043A\u0435. This is text in Russian."
mypdf text $txt -bg #CACACA -x 50 -y 100
mypdf setFont 10 MyType1
mypdf text $txt -x 50 -y 200
mypdf write -file fonts.pdf
mypdf destroy
This call creates a font that can be used in documents from a base font. The subset must be a list of (up to 256) unicode values which are the characters that can be drawn when fontname is selected.
pdf4tcl::loadBaseTrueTypeFont BaseArial "arial.ttf"
# Subset is a list of unicodes:
for {set f 0} {$f < 128} {incr f} {lappend subset $f}
lappend subset [expr 0xB2] [expr 0x3B2]
pdf4tcl::createFontSpecEnc BaseArial MyArial $subset
pdf4tcl::new mypdf -paper a4
mypdf startPage
mypdf setFont 16 MyArial
set txt "sin\u00B2\u03B2 + cos\u00B2\u03B2 = 1"
mypdf text $txt -x 50 -y 100
mypdf write -file specenc.pdf
mypdf destroy
This call returns the list of known font names, i.e. those accepted in a call to setFont. This includes the default fonts and fonts created by e.g. ::pdf4tcl::createFont.
This call translates an RGB color value to a CMYK color value. It is used internally if -cmyk was set at object creation to translate colors. You can redefine this procedure to provide your own translation.
This call translates a CMYK color value to an RGB color value. It is used internally to translate colors. You can redefine this procedure to provide your own translation.
This call concatenates PDF files into one. Currently the implementation limits the PDFs a lot since not all details are taken care of yet. Straightforward ones like those created with pdf4tcl or ps2pdf should work mostly ok.
This call extracts form data from a PDF file. The return value is a dictionary with id/info pairs. The id is the one set with -id to addForm, if the PDF was generated with pdf4tcl. The info is a dictionary with the following fields:
All commands created by ::pdf4tcl::new have the following general form and may be used to invoke various operations on their pdf object.
The method method and its arg'uments determine the exact behavior of the command. See section OBJECT METHODS for the detailed specifications.
The method returns a list of all known options and their current values when called without any arguments.
The method behaves like the method cget when called with a single argument and returns the value of the option specified by said argument.
The method reconfigures the specified options of the object, setting them to the associated values, when called with an even number of arguments, at least two.
The legal options are described in the section OBJECT CONFIGURATION.
This method expects a legal configuration option as argument and will return the current value of that option for the object the method was invoked for.
The legal configuration options are described in section OBJECT CONFIGURATION.
This method destroys the object it is invoked for. If the -file option was given at object creation, the output file will be finished and closed.
This method starts a new page in the document. The page will have the default page settings for the document unless overridden by option. See PAGE CONFIGURATION for page settings. This will end any ongoing page.
This method ends a page in the document. It is normally not needed since it is implied by e.g. startPage and finish. However, if the document is built page by page in e.g. an event driven environment it can be good to call endPage explicitly to have all the page's work finished before reentering the event loop.
This method starts a new XObject in the document. An XObject is a reusable drawing object and behaves just like a page where you can draw any graphics. An XObject must be created between pages and this method will end any ongoing page. The return value is an id that can be used with putImage to draw it on the current page or with some forms. All page settings (PAGE CONFIGURATION) are valid when creating an XObject. Default options are -paper = {100p 100p}, -landscape = 0, -orient = document default, -margin= 0.
This method ends an XObject definition. It works just like endPage.
This method ends the document. This will do endPage if needed. If the -file option was given at object creation, the output file will be finished and closed.
This method returns the generated pdf. This will do endPage and finish if needed. If the -file option was given at object creation, nothing is returned.
This method writes the generated pdf to the given filename. If no filename is given, it is written to stdout. This will do endPage and finish if needed. If the -file option was given at object creation, an empty file is created.
Add an interactive form at the given position and size. Supported types are text and checkbutton. Option -init gives an initial value for the form. Option -id gives the form an ID that must be unique within a document. If not given, one will be generated. For a text, option -multiline enables multi line editing. For a checkbutton, options -on and -off can be given an xobject (created with startXObject) to control its appearance.
This method returns the size of the available area on the page, after removing margins. The return value is a list of width and height, in the document's default unit.
Draws the contents of the canvas widget path on the current page. The return value is the bounding box in pdf page coordinates of the area covered. Option -bbox gives the area of the canvas to be drawn. Default is the entire contents, i.e. the result of $path bbox all. Options -x, -y, -width and -height defines an area on the page where to place the contents. Default area starts at origin, stretching over the drawable area of the page. Option -sticky defines how to place the contents within the area. The area is always filled in one direction, preserving aspect ratio, unless -sticky defines that the other direction should be filled too. Default -sticky is nw. If option -bg is true, a background is drawn in the canvas' background color. Otherwise only objects are drawn. Default is false. Option -fontmap gives a dictionary mapping from Tk font names to PDF font names. Option -textscale overrides the automatic downsizing made for tk::canvas text items that are deemed too large. If -textscale is larger than 1, all text items are reduced in size by that factor.
Fonts:
If no font mapping is given, fonts for text items are limited to PDF's builtins, i.e. Helvetica, Times and Courier. A guess is made to chose which one to use to get a reasonable display on the page.
An element in a font mapping must exactly match the -font option in the text item. The corresponding mapping value is a PDF font family, e.g. one created by pdf4tcl::createFont, possibly followed by a size. It is recommended to use named fonts in Tk to control the font mapping in detail.
Limitations:
Option -splinesteps for lines/polygons is ignored.
Stipple offset is limited. The form x,y should work.
Window items require Img to be present and must be visible on-screen when the canvas is drawn.
This method sets metadata fields for this document. Supported field options are -author, -creator, -keywords, -producer, -subject, -title, -creationdate and -format.
Add a bookmark on the current page.
This method embeds a file into the PDF stream. File data is considered binary. Returns an id that can be used in subsequent calls to attachFile.
This method adds a file annotation to the current page. The location of the file annotation is given by the coordinates x, y, width, height. The annotation is rendered by default as a paperclip icon, which allows the extraction of the attached file. An fid from a previous call to embedFile must be set as well as a description, which is shown by the PDF viewer upon activating the annotation.
set fid [$pdfobject embedFile "data.txt" -contents "This should be stored in the file."] $pdfobject attachFile 0 0 100 100 $fid "This is the description"
This method sets the font used by text drawing routines. If fontname is not provided, the previously set fontname is kept.
This method returns the width of a string under the current font.
This method returns the width of a character under the current font.
Set coordinate for next text command.
Increment position by dx, dy for the next text command.
This method returns the current text coordinate.
Moves text coordinate down and resets x to where the latest setTextPosition was. The number of lines to move down can be set by spacing. This may be any real number, including negative, and defaults to the value set by setLineSpacing.
Set the default line spacing used be e.g. newLine. Initially the spacing is 1.
Get the current default line spacing.
Draw text at the position defined by setTextPosition using the font defined by setFont.
Draw the text string str wrapping at blanks and tabs so that it fits within the box defined by x, y, width and height. An embedded newline in str causes a new line in the output. If str is too long to fit in the specified box, it is truncated and the unused remainder is returned.
Get information about current font. The available metrics are ascend, descend, fixed, bboxb, bboxt and height.
A limited set of image formats are directly understood by pdf4tcl, currently some JPEG, some PNG, and some TIFF formats. To use unsupported formats, use Tk and the Img package to load and dump images to raw format which can be fed to putRawImage and addRawImage.
Put an image on the current page. The image must have been added previously by addImage or addRawImage. The id is the one returned from the add command.
Put an image on the current page. Works like putImage except that the raw image data is given directly.
image create photo img1 -file image.gif set imgdata [img1 data] mypdf putRawImage $imgdata 60 20 -height 40
Add an image to the document. Returns an id that can be used in subsequent calls to putImage. Supported formats are PNG, JPEG and TIFF.
Add an image to the document. Works like addImage except that the raw image data is given directly.
image create photo img1 -file image.gif set imgdata [img1 data] set id [mypdf addRawImage $imgdata] mypdf putImage $id 20 60 -width 100
This method returns the height of the image identified by id.
This method returns the size of the image identified by id. The return value is a list of width and height.
This method returns the width of the image identified by id.
Colors can be expressed in various formats. First, as a three element list of values in the range 0.0 to 1.0. Second, in the format #XXXXXX where the Xes are two hexadecimal digits per color value. Third, if Tk is available, any color accepted by winfo rgb is accepted.
Sets the background color for text operations where -bg is true.
Alternative calling form, to set color in CMYK color space.
Sets the fill color for graphics operations, and the foreground color for text operations.
Alternative calling form, to set color in CMYK color space.
Sets the stroke color for graphics operations.
Alternative calling form, to set color in CMYK color space.
Sets the width for subsequent line drawing. Line width must be a non-negative number.
Sets the dash pattern for subsequent line drawing. Offset and any elements in the dash pattern must be non-negative numbers. on off is a series of pairs of numbers which define a dash pattern. The 1st, 3rd ... numbers give units to paint, the 2nd, 4th ... numbers specify unpainted gaps. When all numbers have been used, the pattern is re-started from the beginning. An optional last argument sets the dash offset, which defaults to 0. Calling setLineDash with no arguments resets the dash pattern to a solid line.
Sets the width and dash pattern for subsequent line drawing. Line width and any elements in the dash pattern must be non-negative numbers. args is a series of numbers (not a tcl list) which define a dash pattern. The 1st, 3rd ... numbers give units to paint, the 2nd, 4th ... numbers specify unpainted gaps. When all numbers have been used, the pattern is re-started from the beginning. This method do not support offsetting the pattern, see setLineDash for a more complete method.
Draws a line from x1, y1 to x2, y2
If x4, y4 are present, draws a cubic bezier from x1, y1 to x4, y4 with control points x2, y2 and x3, y3. Otherwise draws a quadratic bezier from x1, y1 to x3, y3, with control point x2, y2
Draw a polygon. There must be at least 3 points. The polygon is closed back to the first coordinate unless -closed is false in which case a poly-line is drawn.
Draw a circle at the given center coordinates.
Draw an oval at the given center coordinates.
Draw an arc, following the given oval. The arc starts at angle phi, given in degrees starting in the "east" direction, counting counter clockwise. The arc extends extend degrees.
Draw an arrow. Default angle is 20 degrees.
Draw a rectangle.
Create a clip region. To cancel a clip region you must restore a graphic context that was saved before.
Save graphic/text context. (I.e. insert a raw PDF "q" command). This saves the settings of at least these calls: clip, setBgColor, setFillColor, setStrokeColor, setLineStyle, setLineWidth, setLineDash, setFont, and setLineSpacing. Each call to gsave should be followed by a later call to grestore in the same page.
Restore graphic/text context. (I.e. insert a raw PDF "Q" command).
All pdf4tcl objects understand the options from PAGE CONFIGURATION, which defines default page settings when used with a pdf4tcl object. The objects also understand the following configuration options:
pdf4tcl::new mypdf -paper a3 mypdf startPage mypdf setFont 12 Courier mypdf text "Hejsan" -x 50 -y 50 mypdf write -file mypdf.pdf mypdf destroy
doctools
document, pdf
Copyright © 2007-2016 Peter Spjuth
Copyright © 2009 Yaroslav Schekin