pdf4tcl(n) 0.5 pdf4tcl "Pdf document generation"

NAME

pdf4tcl - Pdf document generation

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    COORDINATES
    UNITS
    PUBLIC API
        PACKAGE COMMANDS
        OBJECT COMMAND
        OBJECT METHODS
        OBJECT METHODS
        OBJECT METHODS, TEXT
        OBJECT METHODS, IMAGES
        OBJECT METHODS, COLORS
        OBJECT METHODS, GRAPHICS
        OBJECT CONFIGURATION
        PAGE CONFIGURATION
    EXAMPLES
    SEE ALSO
    KEYWORDS
    COPYRIGHT

SYNOPSIS

DESCRIPTION

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, origo is in the bottom left corner. With -orient true, origo is in the top left corner. Origo 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 UNIT for valid units. If no unit is given, the value is interpreted as points.

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

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 origo, 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.

Limitations:

Fonts for text items are currently 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.

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.

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 x y: Move coordinate for next text command.
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.
objectName drawTextBox x y width height str ?option value...?: Draw text.
objectName getFontMetric metric: Get information about current font. The available metrics are ascend, descend, fixed, bboxy and height.

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

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 setLineStyle width args
objectName line x1 y1 x2 y2
objectName qCurve x1 y1 xc yc x2 y2
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...?

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 UNIT 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, origo is in the bottom left corner. With -orient true, origo 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.