Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 ex-
       plicit 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 (cen-
       timeter), 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 ex-
	      plained 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::get-
	      Points.  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 ref-
	      erence 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	behav-
	      ior  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 sin-
	      gle 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 CONFIGURA-
	      TION.

       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  overrid-
	      den  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.  How-
	      ever, 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  cre-
	      ation, 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 dictio-
	      nary 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	recom-
	      mended 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, -sub-
	      ject, -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 set-
	      TextPosition 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	embed-
	      ded 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. Typ-
		     ically 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, cur-
       rently 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 re-
	      turned 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  pat-
	      tern. 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.	 Call-
	      ing  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-neg-
	      ative 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 qua-
	      dratic 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 mem-
	      ory.  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  op-
	      tion 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  sys-
	      tem.   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

SEE ALSO
       doctools

KEYWORDS
       document, pdf

COPYRIGHT
       Copyright (c) 2007-2011 Peter Spjuth
       Copyright (c) 2009 Yaroslav Schekin

pdf4tcl				      0.8			    pdf4tcl(n)

NAME | SYNOPSIS | DESCRIPTION | COORDINATES | UNITS | PUBLIC API | EXAMPLES | SEE ALSO | KEYWORDS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pdf4tcl&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help