SourceForge Logo

Trampoline!© - Helping Acrobat® documents leap off the Tk canvas

What is it?

Trampoline! is a nearly pure-Tcl library extension that generates an Adobe Portable Document Format (PDF) document based upon the content of a Tk canvas. The intent of this extension is to provide a "modern" replacement for the Tk canvas widget command postscript, which generates a Postscript document based upon the content of a Tk canvas. Trampoline! is striving to be compliant with Adobe PDF Reference version 1.4.

Trampoline! 0.5.1 is a code fix release. No new features are added to this release of Trampoline!, but a number of changes have been made to allow proper PDF document generation on both Unix and Microsoft Windows platforms. The PDF document generated is also more compliant with the PDF standard. The generated test document can now be read sucessfully and without complaint by Adobe Acroread 5.0.8, Xpdf 2.02pl1, and Ghostview (gv) 3.5.8. Details on the changes made for this release of Trampoline! can be view in the file ChangeLog.txt.

The Trampoline! 0.5 library is loaded using the command package require trampoline, which creates the ::pdf namespace. Though there are a number of supporting functions within the namespace, the only one that is currently directly usable is the ::pdf::generate command. This command has two parameters. The first is the path to the canvas widget. The second is the name of the file that will hold the PDF document. More parameters and options will be added as the package matures.

Below is a screen capture of a Tcl/Tk demo application that uses Trampoline! to generate a PDF document based on the items in the canvas widget. The PDF document generated can be viewed by clicking on the image.

Trampoline! 0.5 features and limitations

Trampoline! is written for Tcl/Tk 8.4 or later. While it was developed and tested on a computer running Slackware Linux 9.1, some testing has also been computers running Microsoft Windows operating systems. Trampoline! should work on any platform that support Tcl/Tk and (optionally) the Img extension. Testers are encouraged to try Trampoline! on their platform. Reports of success or problems are welcome.

Trampoline! supports all canvas item types, but not every item option, as yet. The Img extension is used to capture the Tk widgets displayed within canvas window items. This is why Trampoline! is described as being a "nearly pure-Tcl" extension. If the user does not plan on having canvas window items within the canvas, the Img extension does not need to be loaded. Trampoline! will still function properly as long as no window items are on the canvas. Note that all canvas coordinates must be specified in pixels.

The following table lists the outstanding isses with each canvas item type:

Canvas ItemIssues
Arc
-dash, -activedash, -disableddash
  Only one-number or two-number dash patterns are supported,
  with longer patterns truncated to two-number dash patterns
-offset
  Not implemented
BitmapNone
ImageNone
Line
-dash, -activedash, -disableddash
  Only one-number or two-number dash patterns are supported,
  with longer patterns truncated to two-number dash patterns
-offset
  Not implemented
-smooth
  Uses PDF cubic Bezier splines, not Tk canvas polynomial splines
-splinesteps
  Not implemented
Oval
-dash, -activedash, -disableddash
  Only one-number or two-number dash patterns are supported,
  with longer patterns truncated to two-number dash patterns
-offset
  Not implemented
Polygon
-dash, -activedash, -disableddash
  Only one-number or two-number dash patterns are supported,
  with longer patterns truncated to two-number dash patterns
-offset
  Not implemented
-smooth
  Uses PDF cubic Bezier splines, not Tk canvas polynomial splines
-splinesteps
  Not implemented
Rectangle
-dash, -activedash, -disableddash
  Only one-number or two-number dash patterns are supported,
  with longer patterns truncated to two-number dash patterns
-offset
  Not implemented
Text
-font
  Restricted to using PDF Standard Type 1 Fonts
-justify
  Justification translation algorithm not fully tested
-width
  Must be set to zero
Window Widget must be exposed in order to be properly rendered

Installation and Use

To install the Trampoline! library, simply copy the library directory trampoline0.5 and its contents to a directory whose path is listed in the Tcl auto_path variable. Alternately, the path to the Trampoline! library can be added to the auto_path variable.

Once the installation is done, the Trampoline! library can be loaded into the in interpreter as follows:

  package require Img (needed only if window canvas items are used)
  package require trampoline

This will create the ::pdf namespace.

Future goals

Work still needs to be done in the areas mentioned above in Trampoline! 0.5 features and limitations. Eventually, Trampoline! will have as many of the commands and options of the canvas postscript command has as is feasible. Unique commands and options related to PDF document generation will also be added as warranted.

An effort is also underway to refactor the extension into Tk-independent and Tk-dependent components. The goal is to eventually have PDF document generation independent of any Tk commands. These functions would be placed in an extension called TclPDF. The Tk-dependent functions would call the PDF functions to generate a document. These functions would stay in the Trampoline! extension. Both libraries would share the ::pdf namespace, with Trampoline! acting as an add-on to TclPDF.

It is also hoped that at some future date Trampoline! would become part of tklib and TclPDF would become part of tcllib.

Legal issues

The Trampoline! sources are licensed under the same Open Source license as Tcl (BSD). Details can be found in the Trampoiline! source code.

Whenever the Abobe Acrobat Reader 5.0 (acroread) is started, a long list of patent numbers are presented :

Protected by U.S. Patents 4,837,613; 5,050,103; 5,185,818;
5,200,740; 5,233,336; 5,237,313; 5,255,357; 5,546,528;
5,634,064; 5,737,599; 5,781,785; 5,819,301; 5,832,530;
5,832,531; 5,860,074; 5,929,866; 5,930,813; 5,943,063;
5,995,086; 6,049,339; 6,073,148; 6,289,364; Patents
Pending. Contains an implementation of the LZW algorithm
licensed under U.S. Patent 4,558,302.

I checked out Section 1.4 (Intellectual Property) of the PDF Reference, Third Edition, Version 1.4 to determine the extent to which Adobe would defend their intellectual property from those wanting to implement software to generate PDF document. The section essentially states that as long as appropriate copyright notice is made and the documents generated follow the PDF format, Adobe will grant copyright permission. Adobe's goal with their copyright and patent enforcement is to ensure the integrity of the PDF standard.

Downloads

Trampoline! 0.5.1 is available as either gzipped tar archives for GNU/Linux (and other Un*xes) or pkzip archives for Microsoft Windows. Both can be obtained at the Trampoline! SourceForge Files page.
Earler versions of Trampoline! can also be found at the Trampoline! SourceForge Files page.

Feedback

Feedback and suggestions for new features for Trampoline! are invited. Be aware that development is still ongoing. New versions of Trampoline! will be made available as time allows. You can send your emails to mcody <at> users.sourceforge.net.

Links

Go to the Trampoline! SourceForge Summary page or browse the Trampoline! CVS repository.
Adobe PDF Specifications page
The ActiveState Tcl Developer Xchange.

Trampoline! and TclPDF 2004 Mac A. Cody

The Portable Document Format standard is Copyright © 1987-2004 Adobe Systems Incorporated and its licensors. All rights reserved. Adobe, the Adobe logo, Acrobat, the Acrobat logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Last updated Wednesday, December 1, 2004