DragonFly On-Line Manual Pages

pdf4tcl(n) Pdf document generation pdf4tcl(n)

______________________________________________________________________________

NAME
pdf4tcl - Pdf document generation

SYNOPSIS
package require Tcl 8.4

package require ?dict?

package require snit

package require pdf4tcl ?0.8?

::pdf4tcl::new objectName ?option value...?

::pdf4tcl::getPaperSize paper

::pdf4tcl::getPaperSizeList

::pdf4tcl::getPoints val

::pdf4tcl::loadBaseTrueTypeFont basefontname ttf_file_name

::pdf4tcl::createBaseTrueTypeFont basefontname ttf_data

::pdf4tcl::loadBaseType1Font basefontname AFM_file_name PFB_file_name

::pdf4tcl::createBaseType1Font basefontname AFM_data PFB_data

::pdf4tcl::createFont basefontname fontname encoding_name

::pdf4tcl::createFontSpecEnc basefontname fontname subset

objectName method ?arg arg ...?

objectName configure

objectName configure option

objectName configure -option value...

objectName cget -option

objectName destroy

objectName startPage ?option value...?

objectName endPage

objectName finish

objectName get

objectName write ?-file filename?

objectName getDrawableArea

objectName canvas path ?option value...?

objectName metadata ?option value...?

objectName bookmarkAdd ?option value...?

objectName setFont size ?fontname?

objectName getStringWidth str

objectName getCharWidth char

objectName setTextPosition x y

objectName moveTextPosition dx dy

objectName getTextPosition

objectName newLine ?spacing?

objectName setLineSpacing spacing

objectName getLineSpacing

objectName text str ?option value...?

objectName drawTextBox x y width height str ?option value...?

objectName getFontMetric metric

objectName putImage id x y ?option value...?

objectName putRawImage data x y ?option value...?

objectName addImage filename ?option value...?

objectName addRawImage data ?option value...?

objectName getImageHeight id

objectName getImageSize id

objectName getImageWidth id

objectName setBgColor red green blue

objectName setFillColor red green blue

objectName setStrokeColor red green blue

objectName setLineWidth width

objectName setLineDash ?on off...? ?offset?

objectName setLineStyle width args

objectName line x1 y1 x2 y2

objectName curve x1 y1 x2 y2 x3 y3 ?x4 y4?

objectName polygon ?x y...? ?option value...?

objectName circle x y radius ?option value...?

objectName oval x y radiusx radiusy ?option value...?

objectName arc x y radiusx radiusy phi extend ?option value...?

objectName arrow x1 y1 x2 y2 size ?angle?

objectName rectangle x y width height ?option value...?

______________________________________________________________________________

DESCRIPTION
This package provides a container class for generating pdf documents.

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

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

PUBLIC API
PACKAGE COMMANDS
::pdf4tcl::new objectName ?option value...?
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.

::pdf4tcl::getPaperSize paper
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.

::pdf4tcl::getPaperSizeList
This call returns the list of known paper types.

::pdf4tcl::getPoints val
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.

::pdf4tcl::loadBaseTrueTypeFont basefontname ttf_file_name
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. Note that the type loading
functions require Tcl 8.5.

::pdf4tcl::createBaseTrueTypeFont basefontname ttf_data
This call creates a base font from TTF binary data.

::pdf4tcl::loadBaseType1Font basefontname AFM_file_name PFB_file_name
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.

::pdf4tcl::createBaseType1Font basefontname AFM_data PFB_data
This call creates a base font from AFM text and PFB binary data.

::pdf4tcl::createFont basefontname fontname encoding_name
This call creates a font that can be used in documents from a
base font.

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 1
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

::pdf4tcl::createFontSpecEnc basefontname fontname subset
This call creates a font that can be used in documents from a
base font. The subset must be a list of unicode values.

OBJECT COMMAND
All commands created by ::pdf4tcl::new have the following general form
and may be used to invoke various operations on their pdf object.

objectName method ?arg arg ...?
The method method and its arg'uments determine the exact
behavior of the command. See section OBJECT METHODS for the
detailed specifications.

OBJECT METHODS
objectName configure
The method returns a list of all known options and their current
values when called without any arguments.

objectName configure option
The method behaves like the method cget when called with a
single argument and returns the value of the option specified by
said argument.

objectName configure -option value...
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.

objectName cget -option
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.

objectName destroy
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.

objectName startPage ?option value...?
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.

objectName endPage
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.

objectName finish
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.

objectName get
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.

objectName write ?-file filename?
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.

OBJECT METHODS, PAGE
objectName getDrawableArea
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.

objectName canvas path ?option value...?
Draws the contents of the canvas widget path on the current
page. 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.

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. 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 requires Img to be present and must be visible on-
screen when the canvas is drawn.

objectName metadata ?option value...?
This method sets metadata fields for this document. Supported
field options are -author, -creator, -keywords, -producer,
-subject, -title, -creationdate and -format.

objectName bookmarkAdd ?option value...?
Add a bookmark on the current page.

-title text
Set the text of the bookmark.

-level level
Set the level of the bookmark. Default is 0.

-closed boolean
Select if the bookmark is closed by default. Default is
false, i.e. not closed.

OBJECT METHODS, TEXT
objectName setFont size ?fontname?
This method sets the font used by text drawing routines. If
fontname is not provided, the previously set fontname is kept.

objectName getStringWidth str
This method returns the width of a string under the current
font.

objectName getCharWidth char
This method returns the width of a character under the current
font.

objectName setTextPosition x y
Set coordinate for next text command.

objectName moveTextPosition dx dy
Increment position by dx, dy for the next text command.

objectName getTextPosition
This method returns the current text coordinate.

objectName newLine ?spacing?
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.

objectName setLineSpacing spacing
Set the default line spacing used be e.g. newLine. Initially
the spacing is 1.

objectName getLineSpacing
Get the current default line spacing.

objectName text str ?option value...?
Draw text at the position defined by setTextPosition using the
font defined by setFont.

-align left|right|center (default left)

-angle degrees (default 0) - Orient string at the specified
angle.

-xangle degrees (default 0)

-yangle degrees (default 0) - Apply x or y shear to the text.

-x x (default 0)

-y y (default 0) - Allow the text to be positioned without
setTextPosition.

-bg bool (default 0)

-background bool (default 0)

-fill bool (default 0)
Any of -bg, -background or -fill cause the text to be
drawn on a background whose colour is set by setBgColor.

objectName drawTextBox x y width height str ?option value...?
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.

-align left|right|center|justify)
Specifies the justification. If not given, the text is
left justified.

-linesvar var
Gives the name of a variable which will be set to the
number of lines written.

objectName getFontMetric metric
Get information about current font. The available metrics are
ascend, descend, fixed, bboxb, bboxt and height.

ascend Top of typical glyph, displacement from anchor point.
Typically a positive number since it is above the anchor
point.

descend
Bottom of typical glyph, displacement from anchor point.
Typically a negative number since it is below the anchor
point.

fixed Boolean which is true if this is a fixed width font.

bboxb Bottom of Bounding Box, displacement from anchor point.
Typically a negative number since it is below the anchor
point.

bboxt Top of Bounding Box, displacement from anchor point.
Typically a positive number since it is above the anchor
point.

height Height of font's Bounding Box.

OBJECT METHODS, IMAGES
A limited set of image formats are directly understood by pdf4tcl,
currently JPEG and some PNG 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.

objectName putImage id x y ?option value...?
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.

-width width
Set the width of the image. Default width is one point
per pixel. If height is set but not width, the width is
selected to preserve the aspect ratio of the image.

-height height
Set the height of the image. Default height is one point
per pixel. If width is set but not height, the height is
selected to preserve the aspect ratio of the image.

objectName putRawImage data x y ?option value...?
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

objectName addImage filename ?option value...?
Add an image to the document. Returns an id that can be used in
subsequent calls to putImage. Supported formats are PNG and
JPEG.

-id id Explicitly select an id for the image. The id must be
unique within the document.

-type name
Set the image type. This can usually be deduced from the
file name, this option helps when that is not possible.
This can be either "png" or "jpeg".

objectName addRawImage data ?option value...?

image create photo img1 -file image.gif
set imgdata [img1 data]
set id [mypdf addRawImage $imgdata]
mypdf putImage $id 20 60 -width 100

objectName getImageHeight id
This method returns the height of the image identified by id.

objectName getImageSize id
This method returns the size of the image identified by id. The
return value is a list of width and height.

objectName getImageWidth id
This method returns the width of the image identified by id.

OBJECT METHODS, COLORS
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.

objectName setBgColor red green blue
Sets the background color for text operations where -bg is true.

objectName setFillColor red green blue
Sets the fill color for graphics operations, and the foreground
color for text operations.

objectName setStrokeColor red green blue
Sets the stroke color for graphics operations.

OBJECT METHODS, GRAPHICS
objectName setLineWidth width
Sets the width for subsequent line drawing. Line width must be
a non-negative number.

objectName setLineDash ?on off...? ?offset?
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.

objectName setLineStyle width args
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.

objectName line x1 y1 x2 y2
Draws a line from x1, y1 to x2, y2

objectName curve x1 y1 x2 y2 x3 y3 ?x4 y4?
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

objectName polygon ?x y...? ?option value...?
Draw a polygon. There must be at least 3 points. The polygon is
closed back to the first coordinate.

-filled bool (default 0)
Fill the polygon.

-stroke bool (default 1)
Draw an outline of the polygon.

objectName circle x y radius ?option value...?
Draw a circle at the given center coordinates.

-filled bool (default 0)
Fill the circle.

-stroke bool (default 1)
Draw an outline of the circle.

objectName oval x y radiusx radiusy ?option value...?
Draw an oval at the given center coordinates.

-filled bool (default 0)
Fill the oval.

-stroke bool (default 1)
Draw an outline of the oval.

objectName arc x y radiusx radiusy phi extend ?option value...?
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.

-filled bool (default 0)
Fill the arc.

-stroke bool (default 1)
Draw an outline of the arc.

-style arc|pieslice|chord (default arc)
Defines the style of the arc. An arc draws the perimeter
of the arc and is never filled. A pieslice closes the arc
with lines to the center of the oval. A chord closes the
arc directly.

objectName arrow x1 y1 x2 y2 size ?angle?
Draw an arrow. Default angle is 20 degrees.

objectName rectangle x y width height ?option value...?
Draw a rectangle.

-filled bool (default 0)
Fill the rectangle.

-stroke bool (default 1)
Draw an outline of the rectangle.

OBJECT CONFIGURATION
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:

-compress boolean
Pages will be zlib compressed if this option is set to true.
This requires the presence of the zlib package. This option can
only be set at object creation.

-file filename
Continuously write pdf to filename instead of storing it in
memory. This option can only be set at object creation.

-unit defaultunit
Defines default unit for coordinates and distances. Any value
given without a unit is interpreted using this unit. See UNITS
for valid units. Default value is "p" as in points. This
option can only be set at object creation.

PAGE CONFIGURATION
-paper name
The argument of this option defines the paper size. The paper
size may be a string like "a4", where valid values are available
through ::pdf4tcl::getPaperSizeList. Paper size may also be a
two element list specifying width and height.

The default value of this option is "a4".

-landscape boolean
If true, paper width and height are switched.

The default value of this option is false.

-orient boolean
This sets the orientation of the y axis of the coordinate
system. With -orient false, origin is in the bottom left
corner. With -orient true, origin is in the top left corner.

The default value of this option is true.

-margin values
The margin is a one, two or four element list of margins. For
one element, it specifies all margins. Two elements specify
left/right and top/bottom. Four elements specify left, right,
top and bottom.

The default value of this option is zero.

-rotate angle
This value defines a rotation angle for the display of the page.
Allowed values are multiples of 90.

The default value of this option is zero.

EXAMPLES

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

DragonFly On-Line Manual Pages

NAME

SYNOPSIS

DESCRIPTION

COORDINATES

UNITS

PUBLIC API

EXAMPLES

SEE ALSO

KEYWORDS

COPYRIGHT