Jeszra Environment

Jeszra Environment
←	Chapter 1. Introduction	→

Generated Files

Jeszra generates a wide range of documents. In addition, templates are usable from different programming languages; Jeszra generates supportive classes for templates. Jeszra also generates Documentation and Scalable Vector Graphics. The following tables describe all the file types supported by Jeszra.

Table 1.1. Major Files generated by Jeszra

File Type	Description
.tcl,.tk	The Tcl-project file generated by Jeszra. This file contains the implementation of a composite window. Possible variations are: plain Tcl-file including the instantiation of the Graphical User Interface; or as a template, which has to be instantiated like every other window.
*.test	This Tcl-test file contains the instantiation code for generated templates. Only a single initial test file gets created per project. You may add additional, hand-written test cases to this test file.
*.xml	DocBook XML File. There is an additional a minor DocBook XML file. The DocBook XML-file contains a refentry DocBook element. This element shall be included via ENTITY from a higher DocBook 4.x element, such as chapter or book. Every Jeszra template receives its own manual page. These manual pages are themselves generated by Jeszra. Likewise were the Runtime Library and Gestalt Items manual pages created by Jeszra.
*.svg	XML based vector graphics. Jeszra converts Tk Graphical User Interfaces into Scalable Vector Graphics or imports Scalable Vector Graphics. Scalable Vector Graphics is widely applicable, for example in HTML and PDF. A FO-wrapper is needed for printing Scalable Vector Graphics through FOP.

Table 1.2. Minor Files generated by Jeszra

File Type	Description
*.xml	Jeszra asks for a property description, whenever a non-standard property is defined as part of a template interface. This description gets stored as a DocBook XML file. The description will be later included in the generated refentry document. The refentry and its properties must reside inside the same directory. Jeszra may otherwise fail to detect the property descriptions.
*.lisp	Lisp (CLOS) File. Jeszra generates LTk based Lisp wrapper classes for templates. This wrapper classes are then being used from Lisp to instantiate the window.
*.rb	Ruby File. Jeszra generates wrapper classes for the Ruby programming language . This wrapper classes allow to control and instantiate templates from within a Ruby interpreter.
*.py	Python File. Jeszra generates wrapper classes for the Python programming language . This wrapper classes allow to control and instantiate templates from within a Python interpreter.

Table 1.3. Editor support generate by Jeszra

File Type	Description
*.el	Elisp File; Emacs skeletons for the Tcl-Major Mode . Use skeletons in Emacs to further simplify the writing of code.
*.xctxtmacro	Apple® Xcode Text Macros File for the Tcl-mode . Import these macros into Apple® Xcode to easy the writing of Tcl/Tk code. The Apple® Xcode Tcl-mode is included in the Apple® Xcode tar file from the “Gestalt Items” download section.

Table 1.4. Internal Files generate by Jeszra

File Type	Description
*.gpal	Jeszra’s palettes files. These palettes are created and used through the Jeszra preferences. Import and exporting palettes under »Palettes« inside of »Working«. Creating or modifying a palette under »Customize Palettte«.
*.hln	help lines definitions.

Table 1.5. Index Files generated by Jeszra

Index Files Description

pkgIndex.tcl

Index Files	Description
pkgIndex.tcl	Tcl Infrastructure. »pkgIndex.tcl« contains a cross-table for the »package« command. Any `package require ` depends on an associated `package ifneeded ` entry inside of a »pkgIndex.tcl« file. The used »pkgIndex.tcl« files must reside in a directory –or subdirectory thereof– listed in the `auto_path` variable. Local directories should be listed first in `auto_path`.
tclIndex.tcl	The old-style Tcl-way to search for procedures. »tclIndex.tcl« also depends on `auto_path`. The »unknown« handler queries this index.

Tcl Infrastructure. »pkgIndex.tcl« contains a cross-table for the »package« command.

Any package require * depends on an associated package ifneeded * entry inside of a »pkgIndex.tcl« file.

The used »pkgIndex.tcl« files must reside in a directory –or subdirectory thereof– listed in the auto_path variable. Local directories should be listed first in auto_path.

tclIndex.tcl

The old-style Tcl-way to search for procedures. »tclIndex.tcl« also depends on auto_path.

The »unknown« handler queries this index.

Tcl/Tk

Jeszra requires Tcl/Tk 8.4 or higher, the Runtime Library and Gestalt Items. The Runtime Library and Gestalt Items are bundled with Jeszra.

Using TkPath is highly recommended. The TkPath used version must be higher than 0.2.5. Jeszra supports both TkPath 0.2 and 0.3. TkPath 0.2 is more mature –stable– than 0.3 (at the time of writing 0.3.1) and thus recommended over 0.3.1. Switch to TkPath 0.3, when it’s mature enough for deployment.

TkPath and Tcl/Tk

Under X Window System: Tcl/Tk 8.4 with TkPath 0.2.8 is recommended.
Under AQUA®: Tcl/Tk 8.5 with TkPath 0.2.8 is recommended. TkPath 0.3.1 has some visual difficulties on AQUA®.

Jeszra will use functionalities from Tcl/Tk 8.6 in the future.

TkZinc 3.3.4

Jeszra uses TkZinc 3.3.4 for diagrams. TkZinc 3.3.4 should be installed to work with diagrams.

As with TkPath, TkZinc 3.3.4 is extensively supported by Jeszra including transformations, grouping and Scalable Vector Graphics generation.

Please also install »tclsplines«, when using Jeszra for vector graphics. The package »tclsplines« provides access to the interpolation code inside of the Tk canvas window. This function is used by Jeszra to create smoothed lines and polygons in Scalable Vector Graphics. Jeszra also uses »tclspline« too smooth TkZinc 3.3.4 curve and TkPath path objects.

Images

Tcl/Tk up to version 8.5 supports only a few bitmap formats. PNG support was only added recently to Tcl/Tk version 8.6.

Jeszra may use third-party packages such as: »base64«, »tkpng« and »Img«, if available.

What does Jeszra do with it?

tkpng as the name suggests adds support for PNG bitmaps.
»base64« from the »Standard Library« is used to encode GIF bitmaps and PNG bitmaps in Base64. These encoded bitmaps are then embedded in Tcl-code or in Scalable Vector Graphics.
The Img package gives access to many bitmap formats. Jeszra uses Img for base64 encoding (the data command), too.
The Img package is preferred (dominant) over the base64 package. Because the base64 package does not always generate valid encoding. The Img package must be loaded before any Tk image is created!
Img is being used to generated Scalable Vector Graphics embedded screen-shots when necessary. The results with Tcl/Tk 8.4 and Img 1.3 under AQUA® were however unusable.

tDOM

Jeszra utilizes tDOM to create a Scalable Vector Graphics DOM-tree in memory. This DOM-tree is currently only being used for Scalable Vector Graphics import and export . In future versions a DOM-tree will become a requirement for DocBook 5.x generation as-well.

Example 1.2. Using tDOM

# Img must be loaded before
# any image gets created.
package require Img
...

# Use base64 alternatively to Img:
# package require base64
package require tdom

package require rtl
package require gstripes

# »source« is a better approach
# for loading the code generation modules.
# source vg26/library/can2svg.tcl
# ...
package require tkParser
package require tkStorage
package require tclDumper
package require svgDom
package require svgCode
package require svgParser
package require c2s_conversion
package require svgDumper

# The code generation must be configured:
array set ::rat ...

# Generate...
vgcode::clear

# The given window path name is the hierarchy
# view inside of Jeszra:
set w \
 .gestalt.space.document.hierarchy.gridwin.canvas
proc do args {::eval $args}
dumper::vanilla $w Hierarchy Hierarchy {}
vgcode::dump-widget $w $w 7 Hierarchy
svgdom::dump foo.svg $dumper::_doc

Example 1.2, “Using tDOM” displays how to access the Scalable Vector Graphics code generation from a Tcl/Tk application. The parser is configured through the global array »rat«. All settings, related to code generation are stored under »settings,Code,*«. The module startup.tcl can be used to create a standard configuration, as shown in Example 1.3, “Standard Configuration”.

Example 1.3. Standard Configuration

...
package require gstartup
gstartup::init
...

The »canvas« window in Example 1.2, “Using tDOM” is the Jeszra hierarchy view. This Tcl script can be used from the console. The Jeszra- home directory must be included in auto_path , Jeszra’s pkgIndex.tcl file contains the references to the needed modules.

Scalable Vector Graphics generation requires tDOM.

The module svgdom.tcl facilitates the DOM-Tree access.

The root element – DOM-tree– can be reached through the variable »::dumper::_doc«.

Fonts

Jeszra uses the standard fonts on the different windowing systems.

Under AQUA® »Lucida Grande« and Monaco.

Under X Window System the »bitstream® vera« font family.

Under Microsoft® Windows® the system fonts.

A TrueType® font: »Gestalt.ttf«, »Gestalt.dfont« on AQUA®, is distributed with Jeszra. The »Gestalt« font contains all the icons displayed inside of Jeszra. »Gestalt.ttf« is a so-called symbol font.

Jeszra uses built-in bitmaps (either as PNG or GIF) as a fall back solution for its icons, whenever »Gestalt.ttf« isn’t installed. These bitmap icons are intentionally ugly, so please install it’s icon font!

Using the glyphs from a symbol fonts as icons creates zoomable, anti-aliased icons with unbeatable high performance. Even memory consumption is kept minimal. Symbol fonts are embeddable as Web-Fonts in a web-site, too! Reducing loading time and memory consumption when compared to bitmaps. The Jeszra and Gestalt Items web-sites at SourceForge make use of web-fonts either inside the HTML pages and the embedded Scalable Vector Graphicss.

Disadvantages of Bitmaps compared to Vectors

Rendering the Graphical User Interface on-screen consumes much more computing power –approximately two times more than with vector graphics.
Bitmaps are Resolution dependent.
It is difficult to change colours in a bitmap, needed to support different colour designs.
Jeszra uses the Option Database entries »spotColor« and »alternateSpotColor« together with »activeForeground«, »activeBackground« and foreground to predefine colours for its icon set.

A Scalable Vector Graphics variant of »Gestalt.ttf« is included within the distribution.

Example 1.4. X Window System Fonts

Copy »Gestalt.ttf« to the X Window System font directory: /usr/X11R6/lib/X11/fonts/TTF/.

Add the following line to the fonts.dir The first line inside of fonts.dir represents the number of installed fonts, increase this number by »1«.

Gestalt.ttf
-ars-gestalt-medium-r-normal--0-0-0-0-p-0-iso8859-1

Some X Window System desktop environments allow for user installed fonts. This mechanism might not always work properly!

Example 1.5. AQUA® Fonts

Use the »Font Book« application under AQUA® to install »Gestalt.dfont«, either as a user or system font.

»Font Book« reports an error: »Missing OpenType Data« for »Gestalt.ttf«, install the AQUA® variant »Gestalt.dfont« instead! »Gestalt.ttf« however must be used for Web-fonts or for embedding it inside of generated PDFs, »Gestalt.dfont« is not suitable for this tasks.

Example 1.6. Microsoft® Windows® Fonts

Drag »Gestalt.ttf« into the Fonts folder under »System Settings«.

Scalable Vector Graphics

Jeszra generates Scalable Vector Graphics from a Tk Graphical User Interface. The canvas, TkPath and TkZinc 3.3.4 as well as many other windows are converted to Scalable Vector Graphics.

Screen-shots are taken with Img, when Jeszra does not know how to convert the window. This applies for controls originating from Tile; introspection is insufficient for these controls.

Images and screen-shots are base64 encoded and are embedded into the generated Scalable Vector Graphics. The Img package is the recommended tool for base64 encoding. Images are stored inside the first <defs/> section of the generated Scalable Vector Graphics. The embedded images are later referenced through the <use> element.

»pimage« images may be directly placed into the generated Scalable Vector Graphics code. This is necessary whenever the dimensions of an image was modified. Jeszra monitors pimage width and height alterations and acts accordingly.

The Tk text window is rudimentarily converted to Scalable Vector Graphics. Only the text itself is preserved, formatting is partly lost. The text introspection capabilities are not suitable to preserve the formatting in Scalable Vector Graphics version 1.1.

Hidden windows are ignored by the Scalable Vector Graphics code generation. Scalable Vector Graphics is generated for all the content of a window, that is the entire contents of a visible canvas window is converted into Scalable Vector Graphics. Be aware, that hidden windows, embedded in a visible canvas are not included in the generated Scalable Vector Graphics, though.

Each window is represented as a new viewport <Scalable Vector Graphics>. The coordinates of this viewport are the same as the coordinates of the window. Scrolling areas are thus preserved inside the generated Scalable Vector Graphics.

The generated Scalable Vector Graphics is inert. Only the cursor property is carried over to Scalable Vector Graphics. State related values such as »-activefill« , »-disabledoutline« etc. are resolved in advance and converted accordingly.

Fully animated and interactive Scalable Vector Graphics is planned for the future, in addition to the inert version.

The generated Scalable Vector Graphics can be used inside of documents or for resolution independent –using the printer resolution– printing. Printing can be channeled through a FO-Processor such as FOP. Scalable Vector Graphics must be embedded in a simplistic fo-wrapper for printing through FOP.

Jeszra does not have Scalable Vector Graphics specific requirements other than tDOM for Scalable Vector Graphics generation. See also the section called “tDOM”. Scalable Vector Graphics import requires TkPath in addition to tDOM.

Scalable Vector Graphics Recommendations

Img or base64 are used for screen-shots or embedded images. See also the section called “Images”.
FOP, or any other fo-processor. FOP can be used to generate PDF from Scalable Vector Graphics and DocBook documents.
FOP can be used for printing Scalable Vector Graphics.
Java®, needed by FOP and many DocBook related tools such as Saxon.
A Scalable Vector Graphics dedicated vector graphics program, such as Inkscape or Adobe Illustrator®...
A Scalable Vector Graphics enabled web-browser.
fontforge, a font editor. FontForge is able to create Scalable Vector Graphics-fonts. A stand-alone Scalable Vector Graphics document better contains all the used fonts. See also the section called “Fonts”.
Web-fonts are an alternative approach to embedded fonts.

How-to use Jeszra’s Scalable Vector Graphics creation capabilities, inside of a Tcl/Tk application, is displayed in Example 1.2, “Using tDOM”. It is recommended to combine Scalable Vector Graphics and gstripes . Gstripes should be used as the print-preview of a more traditional Graphical User Interface.

DocBook

DocBook 4.5 is supported by Jeszra. There is already some work done concerning migration to DocBook 5. DocBook 5 makes it possible to not only create simple documents, but also to manage them as a project. Future Jeszra version will increase the DocBook support via DOM manipulations and perhaps package and revision management.

The complete Jeszra documentation is written in DocBook. All the recommended tools were extensively used to create this documentation.

Most DocBook tools are written in Java® and thus a Java® Runtime environment is required.

Recommended DocBook Tools

Saxon, (version 6.5 was used); a XSLT-Processor. Saxon is integrated with XAE.
Xslthl, (version 1.2 was used); recommended is version 2.0 or higher. Xslthl provides syntax highlighting for source code.
Diffmk, diffmk analyzes changes inside of DocBook documents and generates change-bars accordingly.
FOP, (version 0.2, 0.93 and 0.95 have been used); recommended is version 0.95 or higher. FOP generates MIF, PDF®, Scalable Vector Graphics, PostScript® ... and can be used to print a FO-document. A DocBook document must first be translated to FO, before using it with FOP.
Scalable Vector Graphics can be used right away, embedded in a very simple FO-wrapper.
An entire Tcl/Tk Graphical User Interface becomes printable, when passed through Jeszra’s Scalable Vector Graphics generation. The generated printout is a vector graphics and thus the printer’s resolution can be utilized rather than the display’s resolution.

←	↖	→
Installation and Using Jeszra	↑	Jeszra Functionality