tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
NAME
tgif - Xlib based interactive 2-D drawing facility under X11.
Supports hierarchical construction of drawings and easy navigation
between sets of drawings. It's also a hyper-graphics (or hyper-
structured-graphics) browser on the World-Wide-Web.
SYNOPSIS
tgif [-display displayname] [-fg <color>] [-bg <color>] [-bd <color>]
[-rv] [-nv] [-bw] [-reqcolor] [-cwo[+sbwarp]] [-hyper] [-exec <file>]
[-dbim {xcin|chinput|xim|kinput2}] [-usexlib] [-geometry <geom>]
[=<geom>] [{file[.obj]|-merge file1[.obj] file2[.obj] ...}]
or
tgif -print [-eps] [-p] [-ps] [-f] [-text] [-epsi] [-tiffepsi] [-gif]
[-png] [-jpeg] [-xpm] [-xbm] [-html] [-pdf] [-display displayname] [-
stdout] [-raw[+h[eaderonly]]] [-dosepsfilter [-previewonly]] [-status]
[-gray] [-color | -reqcolor] [-adobe | -adobe=<number>/<number> |
-adobe=false ] [-dontreencode=<string>] [-producedby=<string>] [-page
<number>] [-print_cmd "<command>"] [-one_file_per_page] [-pepsc] [-
dontcondense | -condensed] [-bop_hook "<string>"] [-eop_hook
"<string>"] [-tmp_file_mode "<octal number>"] [-o<dir>] [-exec <file>]
[file1[.obj] file2[.obj] ...]
DESCRIPTION
Tgif is an interactive drawing tool that allows the user to draw and
manipulate objects in the X Window System. Tgif runs interactively in
the first form. In the second form shown in the SYNOPSIS section,
tgif just prints file1.obj, file2.obj, etc. (generated by tgif) into
PostScript(TM) page description files (without opening windows or
fonts) and pipes them to lpr(1) if none of the -eps, -p, -epsi,
-tiffepsi, -gif, -png, -jpeg, -xpm, -xbm, -html, -pdf, -ps, -f, or
-text options are specified. This form of printing is tgif's way of
exporting a tgif file to another format. In this case, any other
unrecognized command line options are sent to lpr(1). In this mode,
tgif is compatible with the obsoleted prtgif. A symbol file (see
descriptions below) can also be printed by specifying the .sym
extension explicitly.
The command line argument file specifies a file or an Uniform Resource
Locator (URL) of objects to be initially edited by tgif. Only HTTP or
FTP URL's are supported. (For a more detailed description of URL and
the World-Wide-Web, the reader is referred to [1].)
Tgif is purely based on Xlib. It is tested under X11R6, and it
requires a 3 button mouse.
OPTIONS
In the first form shown in the SYNOPSIS section, the command line
arguments can be:
- 1 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
-fg Foreground color specified in <color>.
-bg Background color specified in <color>.
-bd Border color specified in <color>.
-rv Start tgif in reversed-video mode.
-nv Start tgif in normal-video mode.
-bw Start tgif in black and white mode.
-reqcolor
Same effect as setting the Tgif.PrintUsingRequestedColor X
default to true (see the X DEFAULTS section below).
-cwo Canvas Window Only. Only the canvas window (see TGIF SUBWINDOWS
section below) will be displayed. This has the same effect as
setting the Tgif.CanvasWindowOnly X default to true.
-cwo+sbwarp
If -cwo+sbwarp is used, single-button-warp (clicking the left
mouse button to warp) is used to activate teleporting (see
TELEPORT/HYPERJUMP section below).
-hyper
Start tgif in the hyperspace mode (see HYPERSPACE section below).
-exec <file>
After tgif starts, execute the internal command in <file> (see
INTERNAL COMMANDS section below). If <file> is the string "-",
tgif executes internal commands from the standard input.
-dbim method
Use method as the input method for double-byte fonts (see
DOUBLE-BYTE INPUT METHOD section below).
-usexlib
If tgif is compiled with -DUSE_XT_INITIALIZE, X Toolkit
initialization routines will be used to setup tgif. Using this
commandline option will force tgif to ignore the
-DUSE_XT_INITIALIZE compiler option and use Xlib only. This is
useful when the system resource file for tgif is not installed
properly or messed up and needs to be bypassed.
In the second form shown in the SYNOPSIS section, the command line
arguments can be:
-eps (or -p)
Generates an Encapsulated PostScript(TM) file in file.eps; this
file can be included in a LaTeX file through the \psfig, \epsf,
- 2 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
or \psfile construct (see the LATEX FIGURE FORMATS section
below).
-ps (or -f)
Generates a PostScript file in file.ps; this file can be printed
to a PostScript printer with lpr(1).
-text
Generates a text file in file.txt; the text file contains all
visible text and can be fed to a spell checker.
-epsi
Generates an Encapsulated PostScript (EPS) file with a preview
bitmap in file.eps. Tgif aborts if a valid display is not
accessible.
-tiffepsi
Generates an EPS file with a DOS EPS Binary File Header and a
trailing TIFF image in file.eps. See the GENERATING MICROSOFT
WINDOWS EPSI FILES section for more details. Tgif aborts if a
valid display is not accessible.
-gif Generates a GIF file in file.gif. Please see the notes for
Tgif.GifToXpm in the X DEFAULTS section below. Tgif aborts if a
valid display is not accessible.
-png Generates a PNG file in file.png. Tgif aborts if a valid display
is not accessible.
-jpeg
Generates a JPEG file in file.jpg. Tgif aborts if a valid
display is not accessible.
-xpm Generates an X11 pixmap (XPM) file in file.xpm. Tgif aborts if a
valid display is not accessible.
-xbm Generates an X11 bitmap (XBM) file in file.xbm. Tgif aborts if a
valid display is not accessible.
-html
Generates a GIF file in file.gif and an HTML file in file.html.
Tgif aborts if a valid display is not accessible.
-pdf Generates a GIF file in file.gif and an PDF file in file.pdf.
Please see the notes for Tgif.PsToPdf in the X DEFAULTS section
below.
-stdout
Sends the output to the standard output instead of generating the
output in a file.
- 3 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
-raw Causes the content of the files to be dumped to stdout.
-raw+h
If -raw+h is used and if the file is an HTTP URL, the HTTP header
is also dumped to stdout.
-raw+headeronly
If -raw+headeronly is used and if the file is an HTTP URL, the
HTTP header is dumped to stdout.
-dosepsfilter
Makes tgif act as a filter for gettting rid of the DOS EPS Binary
File Header and the trailing TIFF image in a DOS/Windows EPS
file.
-previewonly
If -dosepsfilter is specified, -previewonly makes tgif act as a
filter for extracting the preview bitmap from the trailing TIFF
image in a DOS/Windows EPS file.
-status
If this option is used in conjunction with either -raw, -raw+h,
or -raw+headeronly causes a status line to be displayed in
stderr.
-gray
Using this option has the same effect as setting the
Tgif.UseGrayScale X default to true (see the X DEFAULTS section
below).
-color (or -reqcolor)
To print in color, one can use either the -color or the -reqcolor
option. The only difference between the two is that using
-reqcolor has the same effect as setting the
Tgif.PrintUsingRequestedColor X default to true (see the X
DEFAULTS section below).
-adobe (or -adobe=<number>/<number> -adobe=false)
Using this option has the same effect as specifying the
Tgif.UsePsAdobeString X default.
-dontreencode=<string>
Using this option has the same effect as specifying the
Tgif.DontReencode X default.
-producedby=<string>
Using this option has the same effect as specifying the
Tgif.ProducedBy X default.
-page
Causes a specified page (specified by <page>) to be printed.
- 4 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
-print_cmd
Using this option has the same effect as specifying the
Tgif.PrintCommand X default.
-one_file_per_page
Causes each page to be printed into a separate file.
-pepsc
Preserve EPS Comment. This command line option is obsoleted
since EPS comments are always preserved starting from tgif-
4.0.11.
-dontcondense
Using this option has the same effect as setting the
Tgif.DontCondensePSFile X default to true.
-condensed
Using this option has the same effect as setting the
Tgif.DontCondensePSFile X default to false.
-bop_hook and -eop_hook
Using these options have the same effect as specifying the
Tgif.PSBopHook and Tgif.PSEpsHook X defaults.
-tmp_file_mode
Using this option have the same effect as specifying the
Tgif.TmpFileMode X defaults.
-o If this option is not specified, the output file (eps, ps, etc.)
goes into the same directory as the input file. If -odir is
specified, the output file goes into the directory specified by
<dir>.
-merge file1 file2 ...
Using this option merges file1.obj, file2.obj, etc. into a
multipage file.
BASIC FUNCTIONALITIES
Primitive objects supported by tgif are rectangles, ovals, rounded-
corner rectangles, arcs, polylines, polygons, open-splines, closed-
splines, text, X11 bitmaps, some specific forms of X11 pixmaps, and
Encapsulated PostScript. Objects can be grouped together to form a
grouped object. A primitive or a grouped object can be made into an
icon object or a symbol object through user commands.
Tgif objects are stored in two types of files. A file with a .obj
extension (referred to as an object file) is a file of objects, and a
file with a .sym extension (referred to as a symbol file) specifies a
``building-block'' object. A teleport mechanism is provided to travel
(or hyperjump) among the .obj files. A building-block object consists
of the representation part and the definition part (which can be
- 5 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
empty) of the object. Tgif supports the ``bottom-up'' construction of
hierarchical drawings by providing the capability to ``instantiate'' a
building-block object in a drawing. Tgif also supports the ``top-
down'' specification of drawings by allowing the user to make any
object a representation of an un-specified subsystem. Both types of
files are stored in the form of Prolog facts. Prolog code can be
written to interpret the drawings! (It is left to the user to produce
the code. See the PROLOG/C TESTDRIVE section for more details.)
Prolog engines are referred to as drivers in the sections to follow.
(Other types of drivers are also allowed, e.g., written in C.)
Text based attributes can be attached to any non-text object.
Attributes specified in the representation part of a building-block
object are non-detachable when such an object is instantiated. See
the ATTRIBUTES section for details.
Tgif can generate output in a few different formats. By default, the
output is in the PostScript format (color PostScript is supported),
and it is generated into a file named /tmp/Tgifa* (produced by
mktemp() calls) where * is a number; this file is piped to lpr(1).
This takes place when the laser-printer icon is displayed in the
Choice Window (see the TGIF SUBWINDOWS section for the naming of tgif
windows). This output can be redirected to a file with a .ps
extension. This takes place when the PS icon is displayed in the
Choice Window. When the PDF icon is displayed in the Choice Window,
the output is generated into a file with a .pdf extension. By
default, tgif calls ps2pdf from the ghostscript(1) package to convert
a PS file to a PDF file. When the LaTeX (or EPSI) icon is displayed
in the Choice Window, the output is generated into a file with a .eps
extension. This file is in the Encapsulated PostScript (or
Encapsulated PostScript Interchange) format; it can be included in a
LaTeX document with the \psfig or the \epsf construct; this will be
discussed later. The only difference between the EPS and EPSI formats
is that an EPSI file contains a preview bitmap. However, it takes
time to generate the preview bitmap. If the EPS/EPSI file is to be
incorporated into some tool that does not know how to use the preview
bitmap, time can be saved by not using the EPSI format. When the T
icon is displayed in the Choice Window, the output generated into a
file with a .txt extension. This is a text file containing all
visible text; it can be fed to a spell checker. When the x11bm (X11
bitmap) icon is displayed in the Choice Window and color output is not
selected, tgif generates the output with the .xbm extension; the
output is in the X11 bitmap format. However, if the x11bm icon is
displayed in the Choice Window and color output is selected (through
the ^#k keyboard command -- ^ denotes the <Control> and # denotes the
<Meta> or <Alt> key), then tgif generates the output with the .xpm
extension, and the output is in the X11 pixmap format (the version of
this XPM format depends on the settings of the Tgif.XPmOutputVersion X
default). When the GIF icon is displayed in the Choice Window, the
output is generated into a file with a .gif extension. By default,
tgif calls xpmtoppm and ppmtogif from the netpbm(1) package to convert
- 6 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
an XPM file to a GIF file.
X11 bitmap files, certain forms of X11 pixmap files (such as the one
generated by tgif; see the section on X11 PIXMAP for details), GIF
files, and Encapsulated PostScript (EPS) files can be imported into
tgif and be represented as tgif primitive objects. Files in other
raster formats (e.g, JPEG, TIFF, etc.) can also be imported into tgif
if external tools can be used to convert them into X11 pixmap files.
Please see the IMPORT RASTER GRAPHICS section for details.
Tgif drawings are supposed to be printed on letter size paper (8.5in
by 11in). Both landscape and portrait page styles are supported by
tgif. Reduction (or magnification) can be controlled by the #%
keyboard command to set the reduction/magnification. If the compiler
flag -DA4PAPER is defined (in Imakefile or Makefile.noimake), then the
output is supposed to be printed on A4 papers (which has approximate
dimensions of 8.25in by 11.7in).
GRAPHICAL OBJECTS
An object in an object (.obj) file can be a primitive object, a
grouped object, or an icon object. A symbol (.sym) file can have any
number of objects allowed in an object file and exactly one symbol
object. (Recall that a symbol file specifies a building-block
object.) The symbol object in a symbol file is the representation
part of the building-block object, and the rest of the symbol file is
the definition part of the building-block object. The symbol object
is highlighted with a dashed outline to distinguish it from the rest
of the objects. When a building-block object is instantiated, the
symbol part of the file is copied into the graphics editor, and it
becomes the icon for the building-block object.
All objects in tgif can be moved, duplicated, deleted, rotated,
flipped, rotated, and sheared. However, in the non-stretchable text
mode, text objects can not be stretched. For an text object, if it
has not been stretched, rotated, or sheared, flipping it horizontally
will cause the text justification to change and flipping it vertically
has no effect.
Tgif supports 32 fill patterns, 32 pen patterns, 7 default line
widths, 4 line styles (plain, head arrow, tail arrow, double arrows)
for polylines and open-splines, 9 dash patterns, 3 types of text
justifications, 4 text styles (roman, italic, bold, bold-italic), 11
default text sizes (8, 10, 12, 14, 18, and 24 for the 75dpi fonts and
11, 14, 17, 20, 25, and 34 for the 100dpi fonts), 5 default fonts
(Times, Courier, Helvetica, New-Century-Schoolbook, Symbol), and 11
default colors (magenta, red, green, blue, yellow, pink, cyan, cadet-
blue, white, black, dark-slate-gray). Additional line widths can be
added through the use of Tgif.MaxLineWidths, Tgif.LineWidth#,
Tgif.ArrowWidth#, and Tgif.ArrowHeight# X defaults. Additional text
sizes can be added through the use of Tgif.FontSizes X default.
Additional fonts can be added through the use of Tgif.AdditionalFonts
- 7 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
X default. If the defaults fonts are not available, their replacement
fonts can be specified by Tgif.HasAlternateDefaultFonts and related X
defaults. Additional colors can be added through the use of
Tgif.MaxColors, and Tgif.Color# X defaults. One can also select
AddColor() from the Edit Menu to add a color.
Most commands in tgif can either be activated by a popup menu or by
typing an appropriate non-alphanumeric key. All operations that
change any object can be undone and then redone. Commands such as
zoom, scroll, change fonts while no text objects are selected, etc.
are not undoable. The undo/redo history buffer size can be set using
the Tgif.HistoryDepth X default.
TGIF SUBWINDOWS
The tgif windows are described in this section.
Top Window
Displays the current domain and the name of the file tgif is
looking at. Mouse clicks and key presses have no effect.
Menubar Window
This window is right under the Top Window. Pull-down menus can
be activated from it with any mouse buttons. Key presses have no
effect. If HideMenubar() is selected from the Layout Menu, this
window becomes invisible. If ShowMenubar() is selected from the
Layout Menu (which can be activated from the Canvas Window
below), this window becomes visible.
The View, Text, and Graphics pull-down menus are cascading menus
and can not be pinned (see the Popup Menus subsection below for a
description).
Message Window
This is right under the Menubar Window and to the left. It
displays tgif messages. Clicking the left mouse button in this
window scrolls the messages towards the bottom, clicking the
right mouse button scrolls towards the top, and clicking or
dragging the middle mouse button scrolls to the location in the
message history depending on where the mouse is clicked. If the
<Shift> (or <Control>) key is held down when clicking the
left/right mouse button, it scrolls right/left.
Panel (Choice) Window
This is the window to the right of the Message Window, and it
contains a collection of icons (not to be confused with the tgif
icon objects) reflecting the current state of tgif. In
top/bottom, left/right order, it displays the current drawing
mode, the page style (portrait or landscape), edit (see below),
print/export mode, zoom factor, move and stretch mode
(constrained or unconstrained), radius for rounded-corner
rectangles, text rotation, page number or row/column, page layout
- 8 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
mode (stacked or tiled), horizontal alignment (L C R S -),
vertical alignment (T M B S -), font, text size, vertical spacing
between lines of text within the same text object, text
justification, shape (see below), stretchable or non-stretchable
text mode, dash pattern, line style, polyline, spline, or
interpolated spline, line width, fill pattern, pen pattern,
color, and special (see below). Key presses have no effect in
this window.
In addition to displaying the current state of tgif, the icons in
the Choice Window can also be used to change the current state.
Each icon is associated with a particular state variable of tgif.
Clicking the left mouse button on top of an icon cycles the state
variable associated with the icon forward; clicking the right
mouse button cycles the state variable backwards. Dragging the
middle mouse button on top of an icon usually generates a popup
menu which corresponds to an entry in the Main Menu for the
Canvas Window below. (The ``edit'', ``shape'', and ``special''
icons mentioned above are dummy icons that allow the ``edit'',
``shape'', and ``special'' menus to be accessed in the Choice
Window. They do not respond to left and right mouse clicks.) The
response to the dragging of the middle mouse button is different
for the zoom, radius, and vertical spacing icons. Dragging the
mouse left or up increases the zoom or decreases the radius or
vertical spacing; dragging the mouse right or down has the
opposite effect.
If there are objects selected in the canvas window, then the
action of the mouse will cause the selected objects to change to
the newly selected mode; note that in this case, the current
choice won't change if the middle mouse button is used (unless
the Tgif.StickyMenuSelection X default is set to true).
The settings of the horizontal and vertical alignments determine
how objects (or vertices) align with each other when the ^l
keyboard command is issued, how each individual object (or
vertex) aligns with the grids when the ^t keyboard command is
issued, how objects or vertices distribute spatially with respect
to each other when the #l keyboard command is issued, and how
each icon replaces the old icon when the ^#u keyboard command is
issued. The horizontal alignments are left (L), center (C),
right (R), space (S), and ignore (-). The vertical alignments
are top (T), middle (M), bottom (B), space (S), and ignore (-).
In aligning operations, the space (S) and the ignore (-) settings
have the same effect. The space settings are used to distribute
objects such that the gaps between any two neighboring objects
are equal. In vertex mode, any non-ignore setting will cause the
selected vertices to be spaced out evenly. The best way to
understand them is to try them out.
- 9 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
The text vertical spacing determines the vertical distance to
advance when a carriage return is pressed during text editing.
If the user tries to set the value too negative, such that the
next line is exactly at the same position as the current line,
such a setting will not be allowed (this distance depends on the
current font and font size).
Canvas Window
This is the drawing area. The effects of the actions of the
mouse are determined by the current drawing mode. Before tgif-
4.x, dragging the right mouse button will generate the Mode Menu.
This is disabled by default in tgif-4.x, but you can turn it on
using the Tgif.Btn3PopupModeMenu X default.
The drawing modes are (in order, as they appear in the Mode Menu)
select, text, rectangle, corner oval, center oval, edge circle,
polyline (open-spline), polygon (closed-spline), arc (center
first), arc (endpoints first), rounded-corner rectangle, freehand
polyline (open-spline), select vertices, and rotate/shear. When
drawing a rectangle, an oval, or a rounded-corner rectangle, if
the <Shift> key is held down, a square, a circle, or a rounded-
corner square is drawn. Dragging the middle mouse button will
generate the Main Menu.
In the select mode, left mouse button selects, moves, stretches,
and reshapes objects (double-click will ``de-select'' all
selected objects in vertex mode). When an object is selected, it
is highlighted by little squares (referred as handles here) at
the corners/vertices (using the Tgif.HandleSize X default, the
sizes of the handles can be customized). Dragging one of the
handles stretches/reshapes the selected object. If one wants to
move a selected object, one should not drag the handles.
Instead, one should drag other parts of the object. For example,
if the object is a hollow rectangle (the fill is NONE and the pen
is not NONE), in order to select the rectangle, one should to
click on the outline of the rectangle with the left mouse button.
If one would like to move the rectangle, one should drag the
outline of the rectangle with the left mouse button. If the
object is a filled rectangle (fill is not NONE), one can click
inside the rectangle to select it and drag anywhere inside the
rectangle to move it.
Holding down the <Shift> key and clicking the left mouse on an
object which is not currently selected will add the object to the
list of already selected objects. The same action applied to an
object which is already selected will cause it to be de-selected.
When stretching objects (not reshaping poly-type objects),
holding down the <Shift> key after stretching is initiated
activates proportional stretching (basically, a scale operation
is being performed). In non-stretchable text mode, text objects
can not be stretched or scaled.
- 10 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
Double-clicking or clicking the middle mouse button while the
<Shift> key is held down will activate the teleport (or travel),
the launch, or the execute internal command mechanism. See the
sections on TELEPORT/HYPERJUMP, LAUNCH APPLICATIONS, and INTERNAL
COMMANDS for details. Teleporting has precedence over launching,
which has precedence over executing an internal command. In the
text drawing mode, dragging the middle mouse button while the
<Cntrl> key is held down inside the edit text area will move the
edit text area.
The arrow keys can also be used to move selected objects.
However, if no objects are selected, using the arrow keys will
scroll the drawing area by a small amount, and using the arrow
keys when <Control> key is held down will scroll a screen full.
In the select vertices mode, left mouse button selects and moves
vertices. Only the top-level polyline/open-spline and
polygon/closed-spline objects which are selected when the vertex
mode is activated are eligible for vertex operations. In this
mode, all eligible objects have their vertices highlighted with
squares. When a vertex is selected (using similar mechanism as
selecting objects described above), it is doubly highlighted with
a '+' sign. Operations available to these doubly highlighted
vertices are move, delete, align (with each other), distribute
(space them equally), and align to grid. The arrow keys can also
be used to move selected vertices.
Objects can be locked (through the #< keyboard command). Locked
object are shown with gray handles, and they can not be moved,
stretched, flipped, rotated, or sheared. When objects are
grouped, the resulting grouped object will also be locked if any
one of it's constituents is locked. Locked objects can have
their properties, such as color, font, pen, etc., changed;
furthermore, they can be deleted.
If the current move/stretch mode is of the constrained type
(activated and deactivated by the #@ keyboard command), top-level
polylines will have the following behavior. In a move operation,
if both endpoints of a polyline lie inside the objects being
moved, then the whole polyline is moved; otherwise, if only one
endpoint falls inside the objects being moved, then that endpoint
is moved. The vertex that is the neighbor of the moved endpoint
may also be moved either horizontally or vertically. If the last
line segment is horizontal or vertical, then the neighbor vertex
may be moved so that the direction of the last line segment is
maintained. In a stretch (not reshape) operation, if an endpoint
of a polyline lies inside the objects being moved, that endpoint
will be moved. The vertex that is the neighbor of the moved
endpoint will also be moved in the same manner as described
above.
- 11 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
When the drawing mode is set to text (a vertical-bar cursor is
shown), clicking the left mouse button causes selected text to go
into edit mode. Dragging the left mouse button or clicking the
left mouse button while the <Shift> key is held down highlights
substrings of the text. Double-clicking causes a word to be
selected. In edit mode, key presses are treated as text strings
being inputed, and arrow keys are used to move the current input
position. If a key press is preceded by an <ESC> key, then the
character's bit 7 is turned on. This allows non-ASCII
(international) characters to be entered. One can use xfd(1) to
see what the corresponding international character is for an
ASCII character. For the Symbol font, symbols such as the
integral, partial derivative, and copyright symbols can all be
found in this range. There are some characters that are
supported by X11 but not by PostScript; these characters are not
accepted by tgif. If the text being edited is an attribute of a
object, <Meta><Tab> will move the cursor to the next visible
attribute and <Shift><Tab> will move the cursor to the previous
visible attribute.
If the drawing mode is set to draw polygons (not closed-splines)
and if the <Shift> key is held down, the rubber-banded polygon
will be self-closing.
The freehand drawing mode can be used to draw polylines and open
splines. All intermediate points are specified by moving the
mouse (as opposed to clicking the mouse buttons as in the
polyline mode). The second endpoint is specified by releasing
the mouse button.
In all drawing modes (other than the text mode), pressing the
<ESC> key cancels the drawing (creation) of the current object.
Middle mouse button always generates the main tgif popup menu.
Holding down the <Shift> key and clicking the right mouse button
will change the drawing mode to select. Key presses with the
<Control> or <Meta> key held down (referred to as non-
alphanumeric key presses since they can also generate control
characters) are treated as commands, and their bindings are
summarized in the next section. Users can also define single key
commands to emulate the functions of the non-alphanumeric key
commands. The SHORTCUTS section will describe the details.
Scrollbars
Clicking the left mouse button in the vertical/horizontal
scrollbar causes the canvas window to scroll down/right by a
small distance; clicking the right mouse button has the reverse
effect. (The scrollbars in the popup windows for selecting file
names and domain names behave similarly.) Clicking with the
<Shift> key held down will scroll a window full. Clicking or
dragging the middle button will cause the page to scroll to the
- 12 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
location which corresponds to the gray area in the scrollbars.
(Tgif insists that the left-top corner of the Canvas Window is at
a distance that is a nonnegative multiple of some internal units
from the left-top corner of the actual page.)
Rulers
They track the mouse location. Mouse clicks and key presses have
no effect. When the page reduction/magnification is set at 100%,
the markings in the rulers correspond to centimeters when the
metric grid system is used, and they correspond to inches when
the English grid system is used. When the page
reduction/magnification is not set at 100%, the markings do not
correspond to the above mentioned units any more (this is
considered as a known bug).
Interrupt/Hyperspace Window
This window is right below the Message Window and to the left of
the horizontal ruler. When the Tgif.IntrCheckInterval X default
has a positive value, an interrupt icon is visible when the
Canvas Window is being redrawn. If the user clicks on this
window when the interrupt icon is visible, tgif aborts the
repainting of the objects. If this is done when a file is being
opened (either through Open() or Push()), the drawing of objects
is stopped, but the reading of the file continues (reading of the
file is not aborted).
If tgif is currently in the hyperspace mode (please see the
HYPERSPACE section below for more details), a space ship icon
will be displayed when the interrupt icon is not being displayed.
Clicking any button in this window will switch tgif in and out of
the hyperspace mode.
Page Control Window
The Page Control Window is to the left of the horizontal
scrollbar. This window is empty if the current page mode is set
to the tijled page mode. If the current page mode is set to the
stacked page mode, each page has a tab in tabs subwindow of this
window. Clicking the left mouse button on a tab goes to the
corresponding page. Clicking the middle mouse button brings up
the Page Menu. When there are too many pages in a drawing so
that one can not see the tabs for all the pages, one can use the
icons to the left side of the Page Control Window to scroll the
tabs subwindow. Clicking on the first icon scrolls the tabs
subwindow such that the first tab is visible. Clicking on the
4th icon scrolls the tabs subwindow such that the last tab is
visible. Clicking on the 2nd icon scrolls the tabs subwindow
towards the first tab by one tab and clicking on the 3rd icon
scrolls the tabs subwindow towards the last tab by one tab.
Status Window
This window is below the horizontal scrollbar. It shows what
- 13 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
action will be taken if a mouse button is depressed. When a menu
is pulled down or popped up, this window shows what action will
be taken if a menu item is selected. It also displays
miscellaneous status information. Mouse clicks and key presses
have no effect. If HideStatus() is selected from the Layout
Menu, this window becomes invisible. If ShowStatus() is selected
from the Layout Menu, this window becomes visible.
By default, when this window is displaying mouse button status,
right-handed mouse is assumed. Setting the
Tgif.ReverseMouseStatusButtons X default to true will reverse the
status (as if a left-handed mouse is used).
Popup Menus
When a menu is popped up by a mouse drag, the menu can be pinned
if it is dragged far enough horizontally (the distance is
determined by the setting of the Tgif.MainMenuPinDistance X
default). Clicking the right mouse button in a pinned menu will
cause it to disappear. Dragging the left mouse button in a
pinned menu will reposition the menu (except when the
Tgif.TitledPinnedMenu X default is set to true in which case the
left mouse button performs the same function as the middle mouse
button). Clicking the middle mouse button in it will activate
the item right below the mouse.
NON-ALPHANUMERIC KEY BINDINGS
Most operations that can be performed in tgif can be activated through
non-alphanumeric keys (some operations can only be activated through
popup menus or shortcut keys). This section summarizes the operations
that can be activated by a key stroke with the <Control> and/or the
<Meta> key held down. ``^'' denotes the <Control> key and ``#''
denotes the <Meta> key in the following description. (The
``keys.obj'' file, distributed with tgif, also summarizes the same
information, but it is organized differently. This file can be viewed
with tgif, and if installed properly, it can be found in the same
directory as the ``tgificon.obj'' file, mentioned in the FILES section
of this document.)
^a select all
^b send selected objects to the back
^c copy selected objects into the cut buffer
^d duplicate selected objects
^e save/restore drawing mode
^f send selected objects to the front
^g group selected objects (the grouped object will be brought to the
front)
^i instantiate a building-block object
^k pop back to (or return to) a higher level and close the symbol
file (reverse of ^v)
^l align selected objects according to the current alignment
settings
- 14 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
^n open a new un-named object file
^o open an object file to edit
^p print the current page (or export in XBM, XPM, GIF, HTML, PDF,
EPS, or PS formats)
^q quit tgif
^r redraw the page
^s save the current object/symbol file
^t align selected objects to the grid according to the current
alignment
^u ungroup selected objects
^v paste from the cut buffer
^w change the drawing mode to text
^x delete all selected objects
^y change domain
^z escape to driver
^, scroll left
^. scroll right
^- print the current page with a specified command
#a attach selected text objects to a selected non-text object as
attributes
#b escape to driver
#c rotate selected objects counter-clockwise
#d decrement the grid size
#e send a token on a selected polyline
#f flash a selected polyline
#g show/un-show grid points
#h flip the selected objects horizontally
#i increment the grid size
#j hide the attribute names of the selected objects
#k change the drawing mode to select
#l distribute selected objects according to the current alignment
#m move/justify an attribute of a selected object
#n show all the attribute names of the selected objects
#o zoom out
#p import a .obj or a .sym file into the current file
#q change the drawing mode to polyline/open-spline
#r change the drawing mode to rectangle
#s escape to driver
#t detach all the attributes of the selected objects
#u undo
#v flip the selected objects vertically
#w rotate the selected objects clockwise
#x escape to driver
#y escape to driver
#z zoom in
#9 create a user-specified arc (12 o'clock position is 0 degree)
#0 update the selected objects according to current settings
#, scroll up
#. scroll down
#- show all the attributes of the selected objects
- 15 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
#[ align the left sides of objects
#= align the horizontal centers of objects
#] align the right sides of objects
#{ align the top sides of objects
#+ align the vertical centers of objects
#} align the bottom sides of objects
#" make the selected polygon regular (fit the original bounding box)
#% set the percent print reduction (if < 100%) or magnification (if
> 100%)
#: go to default zoom
#` zoom out all the way so that the whole page is visible
#~ saved selected objects in a new file
#; cut and/or magnify a selected bitmap/pixmap object
#_ abut selected objects horizontally
#| abut selected objects vertically
## break up text objects into single character text objects
#^ scroll to the origin set by SaveOrigin()
#@ toggle between constrained and unconstrained move (stretch) modes
#$ change the drawing mode to select vertices
#& align selected objects to the paper according to the current
alignment
#* redo
#( import an Encapsulated PostScript file
#) scale selected objects by specifying X and Y scaling factors
#< lock the selected objects (can't be moved, stretched, flipped, or
rotated)
#> unlock the selected objects
^#a add points to the selected poly or spline
^#b change the text style to bold
^#c change to center justified text
^#d delete points from the selected poly or spline
^#e change the drawing mode to rounded-corner rectangles
^#f reverse-video the selected bitmap objects
^#g toggle snapping to the grid points
^#h hide all attributes of the selected objects
^#i make the selected object iconic
^#j make the selected icon object a grouped object
^#k select color or black-and-white output
^#l change to left justified text
^#m make the selected object symbolic
^#n make the selected symbol object a grouped object
^#o change the text style to roman
^#p change the text style to bold-italic
^#q change the drawing mode to polygon/closed-spline
^#r change to right justified text
^#s save the file under a new name
^#t change the text style to italic
^#u update iconic representations of selected objects
^#v change the drawing mode to oval
^#w toggle between poly and spline
- 16 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
^#x cycle among the various output file formats
^#y push into (or edit) the definition part of a building-block
(icon) object
^#z change the drawing mode to arcs
^#. import an X11 bitmap file
^#, import an X11 pixmap file
^#- toggle between English and Metric grid systems
^#= repeat the last Find command
SHORTCUTS
The user can define single character shortcut keys to emulate the
function of the non-alphanumeric key presses to activate commands.
This is done through the use of the Tgif.ShortCuts X default. (Please
note that these shortcut keys are only active when the drawing mode is
not set to the text mode.) The Tgif.ShortCuts consists of a list of
items, each of which specifies the bindings between a key (may be case
sensitive) and a command. The items are separated by blanks, and each
item is interpreted as follows. It consists of two parts, KEY and
COMMAND, which are concatenated together with a ':' character. The
format of the KEY part is one of :<Key>x, !<Key>x, or <Key>x (here the
character 'x' is used as an example; furthermore, the substring <Key>
must be spelled exactly the way it appears here). The first 2 formats
are equivalent, they specify the lower case x; the 3rd format
specifies both the characters 'x' and 'X'. The COMMAND part is a
string that matches strings in tgif's popup menus with space
characters removed (exceptions are noted below). This is illustrated
by the following example. In the Edit menu, two of the entries are,
"Delete ^x"
"SelectAll ^a"
which means that <Control>x activates and Delete() command, and
<Control>a activates the SelectAll() command. Therefore, both
Delete() and SelectAll() are valid names for the COMMAND part of a
shortcut specification. To complete the example, the following line
can be used to bind the lower case 'x' to Delete() and 'a' or 'A' to
SelectAll():
Tgif.ShortCuts: !<Key>x:Delete() \n\
<Key>a:SelectAll()
For more examples, please see the sample X defaults file,
tgif.Xdefaults, included in the tgif distribution.
Here is a list of exceptions where the COMMAND does not match a
command name in a menu entry. The left entry is a proper COMMAND
name, and the right is a list of strings that's shown in popup menus
which the COMMAND would correspond to.
CyclePrintFormat() Printer, LaTeXFig, RawPSFile, XBitmap,
TextFile, EPSI, GIF/ISMAP, TiffEPSI
- 17 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
ToggleBW/ColorPS() BlkWhtPS, ColorPS
ToggleGridSystem() EnglishGrid, MetricGrid
ToggleMapShown() ShowBit/Pixmap, HideBit/Pixmap
ToggleUseGrayScale() UseGrayScale, NoGrayScale
ToggleMoveMode() ConstMove, UnConstMove
ToggleShowMeasurement() ShowMeasurement, HideMeasurement
ToggleLineType() (advances between different curved shapes)
ScrollPageUp() (scroll up a window full)
ScrollPageDown() (scroll down a window full)
ScrollPageLeft() (scroll left a window full)
ScrollPageRight() (scroll right a window full)
FreeHandMode() (change the drawing mode to freehand poly/open-
spline)
CenterAnEndPoint() (move an endpoint of a polyline object to the
center of another object)
ToggleNamedAttrShown(<x>=) (toggle name shown for the attribute
<x>)
ToggleSmoothHinge() (convert smooth to hinge and hinge to smooth
points)
ToggleShowMenubar() ShowMenubar, HideMenubar
ToggleShowStatus() ShowStatus, HideStatus
ToggleShowMode() ShowMode, HideMode
ToggleOneMotionSelMove() OneMotionSelMove, ClickSelClickMove
ToggleHyperSpace() GoHyperSpace, LeaveHyperSpace
ImportOtherFileType(<x>) (import using a filter named <x>)
BrowseOtherType(<x>) (browse using a filter named <x>)
In addition to the above list, the following are also valid COMMAND
names (having the obvious meaning): ScrollLeft(), ScrollRight(),
ScrollUp(), ScrollDown(), SelectMode(), DrawText(), DrawBox(),
DrawOval(), DrawPoly(), DrawPolygon(), DrawRCBox(), DrawArc(), and
SelectVertexMode().
COLORS AND COLORMAPS
In most X environments, only 256 colors can be displayed at once. In
these environment, if an application needs 128 colors and another
application needs a totally different 129 colors, both applications
can not be displayed at once with all the colors they want. X solves
the problem by allowing applications to use their own colormaps (known
as private colormaps). Each private colormap can have at most 256
colors. There is also a shared colormap available for applications
that do not wish to use private colormaps. The main problem with
using private colormaps is that a user will see the the well-known
colormap flashing phenomenon when he/she switchs in and out of
applications that use private colormaps.
Tgif uses the shared colormap initially. When it needs more color
than what is available in the shared colormap, it will use a private
colormap automatically. When tgif no longer needs the extra colors,
it does not automatically revert to using the shared colormap because
- 18 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
it needs to be able to undo operations that use the extra colors. If
one does no longer needs the objects in the undo buffer, one can
select FlushUndoBuffer() from the Edit Menu to flush the undo buffer.
At this point, tgif will attempt to use the shared colormap to avoid
the colormap flashing problem. If one often uses XPM and GIF objects,
one can bind the <Shift>f key to the FlushUndoBuffer() operation by
setting the following X default and uses the <Shift>f key to regain
entries in the colormap when an XPM/GIF object is deleted:
Tgif.ShortCuts: !<Key>F:FlushUndoBuffer()
Even when a private colormap is used, only 256 colors can be used at
once. Therefore, it is not possible to import two 256-colors GIF
files into the same drawing unless the colors are somehow reduced to
fit in the 256-colors colormap. This can be done through dithering
which is described in the IMPORT RASTER GRAPHICS section below.
IMPORT RASTER GRAPHICS
The native raster graphics formats that tgif supports are the XBM and
XPM formats. In order to import color raster graphics file of another
format, tgif can work with external tools that can convert non-XPM
format files to an XPM files. A popular raster format conversion
toolkit is the pbmplus(1) (also known as the netpbm(1)) toolkit. It
can convert a GIF file (e.g., "foo.gif") to an XPM file (e.g.,
"foo.xpm") with the following command (giftopnm is in netpbm; an
earlier version of it called giftoppm exists in pbmplus):
giftopnm foo.gif | ppmtoxpm > foo.xpm
When working with tgif, a GIF file name will be supplied by tgif and
the output of ppmtoxpm will be directly read by tgif through a pipe;
therefore, the previous sequence is replaced by an X default
containing the following form (which happens to be the default setting
for the Tgif.GifToXpm X default):
giftopnm %s | ppmtoxpm
The "%s" is to be replaced by a GIF file name. The above is referred
to as a filter.
To be able to import other types of raster graphics files, one can use
Tgif.MaxImportFilters and Tgif.ImportFilter# X defaults to specify
additional filters. The following example adds a JPEG filter:
Tgif.MaxImportFilters: 1
Tgif.ImportFilter0: \n\
JPEG-222 jpg;jpeg \n\
djpeg -gif -colors 222 %s | \n\
giftopnm | ppmtoxpm
- 19 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
The "JPEG-222" above is the name given to the filter (must not contain
any space character). The "jpg;jpeg" are possible file extensions
separated by semicolons. The rest is the filter specification. The
djpeg(1) program is part of the libjpeg distribution. It can convert
a JPEG file to a GIF file. The above filter also restrict the output
to have a maximum of 222 colors. (The 222 is chosen arbitrarily.
Many XPM files use some ``standard'' 32 colors, so one may want to
leave room form them.)
To invoke a filter, one can select ImportOtherFile() or BrowseOther()
commands from the File Menu. This will bring up a dialogbox listing
the available filters by their names (e.g., "JPEG-222"). After
selecting a filter, tgif continues in a similar manner as with
invoking ImportXPixmap() or BrowseXPixmap() commands from the File
Menu.
The above example is not suitable for the BrowseOther() command
because only 256 colors can be used in a drawing (as explained in the
COLORS AND COLORMAPS section above). In order for BrowseOther() to
work well, one can use dithering to represent an image with a dithered
image that only uses a set of standard colors. The example below uses
ppmdither from the pbmplus/netpbm toolkit:
Tgif.MaxImportFilters: 2
Tgif.ImportFilter0: \n\
JPEG-222 jpg;jpeg \n\
djpeg -gif -colors 222 %s | \n\
giftopnm | ppmtoxpm
Tgif.ImportFilter1: \n\
JPEG-dithered jpg;jpeg \n\
djpeg -gif %s | \n\
giftopnm | ppmdither | ppmtoxpm
If one is working with one JPEG image, one can select
ImportOtherFile() then select "JPEG-222" to get as many as 222 colors.
If one is browsing for JPEG images, one can select BrowseOther() then
select "JPEG-dithered".
OBJECT NAMES
If an object contains an attribute (please see the ATTRIBUTES sections
below for details) whose name is the string "name" (case-sensitive),
the value part of the attribute is the name of the object. Subobject
of a composite object can be named using a path, e.g.,
<t>!<s1>!<s2>!..., where <t> is the name of a top-level object which
directly contains <s1> which directly contains <s2>, etc. !* refers
to the currently selected object (if more than one object is selected,
the top-most object in the stacking order is used). !*<s1>!<s2> names
the <s2> subject of the <s1> subject of the currently selected object.
The following is not fully supported, yet (only the #<page> form is
supported at this time). Every object in a tgif file can be uniquely
- 20 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
named using the notation #<page>!<path>, where <page> can be a string
that specifies the name of a page or #<number> which specifies a page
number. The <path> is described in the previous paragraph. If an
object o1 is referenced by another object o2 within the same file (no
file name or URL is specified before #) and <page> is omitted, then o1
must be on the same page as o2. If a file name or URL is specified
before # and <page> is omitted, then o1 must be on the first page.
ATTRIBUTES
Attributes are text strings of the form name=value or value which are
attached to either the current drawing or any non-text objects. An
attribute attached to the current drawing is called a file attribute;
otherwise, it is a regular attribute. Attributes can be attached and
detached from these objects except in the following case:
Attributes appearing in the symbol object in a building-block
object file can not be detached when the building-block object is
instantiated. These attributes are considered to be the
``inherited'' attributes of the icon object. (If it is really
necessary to detach inherited attributes of an icon object, the
icon object can be ``de-iconified'' by using UnMakeIconic() in
the Special Menu to make it a grouped object; then the attributes
can be detached.)
A file attribute is always invisible. For a regular attribute, the
user has control over which part of the attribute is displayed. An
entire attribute can be made invisible, or only its name can be made
invisible (accomplished through the commands under the special menu,
such as #m, #n, #j, #-, and ^#h).
TELEPORT/HYPERJUMP
Tgif provides the mechanism to travel between .obj and .sym files. If
the middle mouse button is clicked on an object with the <Shift> key
held down (or double-clicking such an object), tgif looks for an
attribute named warp_to (by default) or href of that object. The only
difference between warp_to and href is that ".obj" is automatically
appended to the value of a warp_to attribute while the value of a href
attribute is taken as is. (Please note that warp_to is obsolete now.
It is still supported for the sake of compatibility.) If such an
attribute is found, the value part of the attribute is interpreted as
the name of a .obj file to travel to. (If tgif is in the hyperspace
mode, then clicking the left mouse button has the same effect.) If
there are multiple href attributes on the object, but are in different
colors, tgif will use the one that has the same color as the current
color appearing in the Choice Window. If the current file is
modified, the user is prompted to save the file before traveling to
the next file. If the value part of the href attribute starts with
the '/' character, the value is treated as an absolute file name;
otherwise, it is treated as a relative file name.
- 21 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
HYPERSPACE
Tgif provides a hyperspace mode to facilitate traveling between .obj
files. The hyperspace mode is entered when GoHyperSpace() is selected
from the Navigate Menu. In hyperspace mode, the little window below
the Message Window will show a little space ship. The hyperspace mode
is also automatically entered when a remote URL is opened (unless the
Tgif.AutoHyperSpaceOnRemote X default is set to false).
In the hyperspace mode, certain objects are considered hot-links.
When the cursor is placed on top of these object, it will change from
a pointer to a hand to indicate that clicking on the left mouse button
will invoke some actions. An object is a hot-link if it contains an
attribute described in either the TELEPORT/HYPERJUMP, LAUNCH
APPLICATIONS, or INTERNAL COMMANDS section.
The hyperspace mode is exited when the drawing mode is changed or the
LeaveHyperSpace() is selected from the Navigate Menu.
LAUNCH APPLICATIONS
Tgif provides the mechanism to launch applications. If the middle
mouse button is clicked on an object with the <Shift> key held down
(or double-clicking such an object), tgif looks for an attribute named
launch (by default) of that object. If such an attribute is found,
the value part of the attribute is interpreted as a sh(1) command to
execute. Same color rule applies as described in the
TELEPORT/HYPERJUMP section above. If the command ends with the '&'
character, tgif forks itself (what actual happens depends on whether
the _BACKGROUND_DONT_FORK compiler flag is defined or not at compile
time) and the command is executed by the child process; otherwise,
popen() is used to execute the command (in this case, if the command
hangs, there is no way provided to terminate the command, and tgif
will not be able to recover from it). Within the command, values of
other attributes of the same object can be used. The syntax is:
$(attr), where attr is the name of another attribute.
For example, if one wants to perform a man(1) function, one can draw a
box; enter a line of text "title=tgif"; enter another line of text
"launch=xterm -rw -e man $(title)"; select all three objects using ^a
keyboard command; attach the text strings to the box using #a keyboard
command; and launch the man(1) command by clicking the middle mouse
button on the box (or the text strings) withe the <Shift> key held
down. If one wants to be more fancy, the box can be replaced by an
X11 pixmap object; the 'launch' attribute can be made invisible; and
the 'title' attribute can be center justified and with its name hidden
using the #m keyboard command.
By default, launching of an application is by default disabled in the
hyperspace mode for security considerations (this can be overridden by
the Tgif.AllowLaunchInHyperSpace X default setting). If a lunch
command is encountered in the hyperspace mode, the command is
displayed and the user is prompted to see if he/she wants to execute
- 22 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
the command.
INTERNAL COMMANDS
Tgif provides the mechanism to execute internal commands. If the
middle mouse button is clicked on an object with the <Shift> key held
down (or double-clicking such an object), tgif looks for an attribute
named exec (by default) of that object. If such an attribute is
found, the value part of the attribute is interpreted as a list of
internal commands (separated by semicolor) to execute. Same color
rule applies as described in the TELEPORT/HYPERJUMP section above. A
command usually takes the form:
<cmd_name> ( <arg1>, <arg2>, ..., <argN> )
An argument of a command can be a string argument or a numeric
argument. A string argument must be enclosed in double-quotes. A
numeric argument can be a numerical value or a string of the form
"$(x)", where x is the name of another attribute (this form is
referred as the substitution form). A string argument can also
contain substitution form. Please note that only one-level
substitution are performed (the collection of internal commands should
be viewed as a simple scripting language and not a declaration
language).
When an attribute is referenced in an internal command, the attribute
name can be in the form, <obj_name>.<string>, where <obj_name> must be
in the form specified in the OBJECT NAMES section above and <string>
contains only alphanumeric characters and the underscore ('_')
character. If the first 2 characters of an attribute name is "!.",
the rest of the attribute name names a file attribute. If the first 2
characters of an attribute name is "!*", the rest of the attribute
name names an attribute of the currently selected object (if more than
one object is selected, the top-most object in the stacking order is
used).
The following internal commands are supported:
launch(<attr_name>)
The value of the attribute specified by <attr_name> is
interpreted as a sh(1) command to execute. Please see the LAUNCH
APPLICATIONS section above for more details.
exec(<attr_name>)
The value of the attribute specified by <attr_name> is
interpreted as an internal command to execute. This is similar
to a subroutine call. Please note that the internal command is
executed in the context of the top-level which contain the
attribute.
mktemp(<str>,<attr_name>)
This command makes a unique file name. The <str> argument is a
- 23 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
template string, e.g., "/tmp/TgifXXXXXX". The result of mktemp
is stored as the value of the attribute specified by <attr_name>.
Please see the man pages of the C library function on mktemp for
more details.
create_file_using_simple_template(<template>,<output>,<str>,<attr_name>)
The file specified by <template> is scanned for a line that
matches <str>. When such a line is found, that line is replaced
by the value of the attribute specified by <attr_name>. The
result is put into the file specified as <output>.
update_eps_child(<eps_file_name>)
This only works if the object being executed is a composite
object. If the object has a component which is an imported EPS
(Encapsulated PostScript) object, it is replaced by the EPS file
specified by <eps_file_name>. If the object does not contain an
EPS subobject, an EPS subobject is created.
update_xbm_child(<xbm_file_name>)
This only works if the object being executed is a composite
object. If the object has a component which is an imported XBM
(X11 bitmap) object, it is replaced by the XBM file specified by
<xbm_file_name>. If the object does not contain an XBM
subobject, an XBM subobject is created.
update_xpm_child(<xpm_file_name>)
This only works if the object being executed is a composite
object. If the object has a component which is an imported XPM
(X11 pixmap) object, it is replaced by the XPM file specified by
<xpm_file_name>. If the object does not contain an XPM
subobject, an XPM subobject is created.
delete_eps_child(<obj_name>)
This only works if the object named <obj_name> is a composite
object. If the object has a component which is an EPS
(Encapsulated PostScript) object, it is deleted. If the object
does not contain an EPS subobject, no operation is performed.
delete_xbm_child(<obj_name>)
This only works if the object named <obj_name> is a composite
object. If the object has a component which is an XPM (X11
pixmap) object, it is deleted. If the object does not contain an
XPM subobject, no operation is performed.
delete_xpm_child(<obj_name>)
This only works if the object named <obj_name> is a composite
object. If the object has a component which is an XBM (X11
bitmap) object, it is deleted. If the object does not contain an
XBM subobject, no operation is performed.
- 24 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
flip_deck(<times>,<frames_per_second>,<style>)
This only works if the object being executed is a composite
object and all subobjects of the composite object are X11 bitmap
or X11 pixmap objects and have identical positions and sizes.
The <times> argument specifies the number of times the deck is
flipped. It can be a number or the string "infinite". The
<frames_per_second> argument must be a number between 1 and 60.
The <style> argument can be either "linear" or "ping_pong". When
this command is being executed, any mouse button click or key
click aborts command execution.
read_file_into_attr(<file_name>,<attr_name>)
This command reads a file into an attribute. The <file_name>
argument names a file, e.g., "/tmp/foo". The content of the file
is read as the value of the attribute specified by <attr_name>.
If the file can not be opened for read, the attribute's value is
set to an empty string.
write_attr_into_file(<attr_name>,<file_name>)
This command writes the value of an attribute into a file. The
<file_name> argument names a file, e.g., "/tmp/foo". The value
of the attribute specified by <attr_name> is written into
<file_name>.
append_attr_into_file(<attr_name>,<file_name>)
This command appends the value of an attribute into a file. The
<file_name> argument names a file, e.g., "/tmp/foo". The value
of the attribute specified by <attr_name> is appended into
<file_name>.
select_obj_by_name(<obj_name>)
This command silently (no highlighting handles) selects an object
named <obj_name>. Please see the OBJECT NAMES section above for
the specification of object names.
select_top_obj()
This command silently (no highlighting handles) selects the top
object. This command fails if there is no object in the current
page.
delete_selected_obj()
This command deletes all selected objects. This command fails if
no object is selected.
unselect_all_obj()
This command de-selects all selected objects. If the
select_obj_by_name() command is used, this command must be used
eventually.
move_selected_obj_relative(<dx>,<dy>)
This command moves the selected object by <dx> absolute units in
- 25 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
the x direction and <dy> absolute units in the y direction.
repeat(<cmd_attr_name>,<times>)
This command executes the internal command in the <cmd_attr_name>
attribute <times> times.
hyperjump(<attr_name>)
This command teleports to the file name or URL name found in the
<attr_name> attribute.
make_cgi_query(<dest_attr_name>,<url_name>,<list_attr_name>)
This command constructs an URL in the Common Gateway Interface
(CGI) format in the <dest_attr_name> attribute. <url_name> names
the CGI server script and <list_attr_name> names an attribute
whose value are comma-separated attribute names. For example, if
an object has the following attributes:
attr_list=last_name,first_name
last_name=Cheng
first_name=Bill
final_url=
exec=make_cgi_query(final_url,
http://bourbon.cs.umd.edu:8001/cgi-bin/test-cgi,
attr_list)
Executing this object will construct the following string in
final_url:
http://bourbon.cs.umd.edu:8001/cgi-bin/test-
cgi?last_name=Cheng&first_name=Bill
An subsequent hyperjump(final_url) command can be invoked to
execute the corresponding "test-cgi" CGI server script with the
last_name and first_name arguments.
For a detailed description of CGI scripts, the reader is referred
to [2].
wait_click(<cursor_name>,<grab>,<attr_name>)
This command displays the <cursor_name> cursor and waits for the
user to click a mouse button. If <cursor_name> is the string
NULL (case-sensitive), the cursor will not change. If <Btn1> is
clicked, the command terminates and 1 is placed in <attr_name>.
If <Btn2> is clicked, 2 is placed in <attr_name>, etc. If <grab>
set to TRUE (case-sensitive), then the mouse is grabbed by tgif.
Valid <cursor_name> can be found in <X11/cursorfont.h> (without
the XC_ prefix).
sleep(<cursor_name>,<ms_interval>)
This command displays the <cursor_name> cursor and waits for
<ms_interval> milliseconds to elapse. If <cursor_name> is the
- 26 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
string NULL (case-sensitive), the cursor will not change. This
command can be interrupted (and aborted) by any mouse clicks or
key strokes. Valid <cursor_name> can be found in
<X11/cursorfont.h> (without the XC_ prefix).
begin_animate()
This command is used to start an animation sequence. By default,
tgif prepares for undo/redo. For a long animation sequence, the
undo/redo records may take up a lot of memory. In this case,
disable_undo() (described below) should be used before this
command.
end_animate()
This command is used to terminate an animation sequence.
set_redraw(<true_or_false>)
This command is used to temporarily disable redraw if
<true_or_false> is FALSE (case-sensitive). If a
shuffle_obj_to_top() command is used before a move command,
set_redraw(FALSE) and set_redraw(TRUE) should be used immediately
before and immediately after, respectively, the
shuffle_obj_to_top() command.
set_selected_obj_color(<color_str>)
This command changes the color of the selected object to
<color_str>. If no object is selected, the current color will be
changed to <color_str>.
set_selected_obj_fill(<fill_index>)
This command changes the fill pattern of the selected object to
<fill_index>, which must be between 0 (for no fill) and 31. If
no object is selected, the current fill pattern will be changed
to <fill_index>.
set_selected_obj_pen(<pen_index>)
This command changes the pen of the selected object to
<pen_index>, which must be between 0 (for no pen) and 31. If no
object is selected, the current pen will be changed to
<pen_index>.
set_selected_obj_line_width(<width>,<arrow_w>,<arrow_h>)
This command changes the line width, arrow width, and arrow
height of the selected object to <width>, <arrow_w>, and
<arrow_h>, respectively. If <arrow_w> or <arrow_h> is -1, the
arrow width or arrow height, respectively, is not changed. If no
object is selected, the current line width will be changed to the
one that matches <width>, <arrow_w>, and <arrow_h> most closely.
(Closeness is measured such that the difference is width is
counted 10 times the diffference in arrow width and arrow
height.)
- 27 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
set_selected_obj_spline(<spline_type>)
This command changes the spline type of the selected object to
<spline_type>, which can be straight, spline, or interpolated.
If no object is selected, the current spline type will be changed
to <spline_type>.
set_selected_obj_arrow(<arrow_type>)
This command changes the arrow type of the selected object to
<arrow_type>, which can be none, right, left, or double. If no
object is selected, the current arrow type will be changed to
<arrow_type>.
set_selected_obj_dash(<dash_index>)
This command changes the dash type of the selected object to
<dash_index>, which must be between 0 (solid) and 8. If no
object is selected, the current dash type will be changed to
<dash_index>.
set_selected_obj_trans_pat(<trans_pat>)
This command changes selected object to have opaque pattern if
<trans_pat> is 0; it changes selected object to have transparent
pattern if <trans_pat> is any other numeric value. If no object
is selected, the current fill and pen pattern will be opaque if
<trans_pat> is 0 and will be transparent if <trans_pat> is any
other numeric value.
set_selected_obj_rcb_radius(<rcb_radius>)
This command changes the rcbox radius of the selected object to
<rcb_radius>, which must be greater or equal to 4. If no object
is selected, the current rcbox radius will be changed to
<rcb_radius>.
set_selected_text_vspace(<vspace>)
This command changes the text vspace of the selected object to
<vspace>. If no object is selected, the current text vspace will
be changed to <vspace>.
set_selected_text_just(<justification>)
This command changes the text justification of the selected
object to <justification>, which can be left, center, or right.
If no object is selected, the current text justification will be
changed to <justification>.
set_selected_text_font(<ps_font_name>)
This command changes the font and text style of the selected
object to match <ps_font_name>. Examples of valid <ps_font_name>
can be found when one selects CopyProperties() from the
Properties Menu. The item listed under text font is a valid
<ps_font_name>. If no object is selected, the current font and
text style will be changed to match <ps_font_name>. This command
fails if no match can be found,
- 28 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
set_selected_text_size(<size>)
This command changes the text size of the selected object to
<size>. If <size> ends with the substring "pt", then point size
is used instead of text size. If such as size cannot be found in
the Size Menu, the closest size in the Size Menu will be used.
If no object is selected, the current text size will be changed
to <size> or the closest size.
set_selected_text_underline(<underline>)
This command removes text underline from the selected object if
<underline> is 0; it underlines text in the selected object if
<underline> is any other numeric value. If no object is
selected, the current text underline will be changed accordingly.
inc(<attr_name>,<expr>)
This command increment <attr_name> by the expression <expr>.
Both the value of <attr_name> and <expr> must be integers.
Please see the ARITHMETIC EXPRESSIONS section below for details
about expressions.
dec(<attr_name>,<expr>)
This command decrement <attr_name> by <expr>. Both the value of
<attr_name> and <expr> must be integers.
shuffle_obj_to_top(<obj_name>)
This command move <obj_name> to the top. If <obj_name> is a
subobject, it is raised to the top, relative to its siblings.
This command is useful in animation where a selected frame
(subobject) can be raised to the top.
disable_undo()
This command cleans up the undo/redo records and disable undo
(and stop recording undo/redo information). The original history
depth is saved away. This command should be used before a long
animation sequence.
enable_undo()
This command restores the history depth saved away by the
disable_undo() command and enables undo/redo. This command
should be eventually used after disable_undo() is called.
get_drawing_area(<ltx_attr>,<lty_attr>,<rbx_attr>,<rby_attr>)
This command stores the absolute coordinate of the current
drawing area in the specified attributes. <ltx_attr> stores the
left-top X coordinate, <lty_attr> stores the left-top Y
coordinate, <rbx_attr> stores the right-bottom X coordinate, and
<rby_attr> stores the right-bottom Y coordinate.
get_selected_obj_bbox(<ltx_attr>,<lty_attr>,<rbx_attr>,<rby_attr>)
This command stores the absolute coordinate of the bounding box
of the selected object in the specified attributes. <ltx_attr>
- 29 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
stores the left-top X coordinate, <lty_attr> stores the left-top
Y coordinate, <rbx_attr> stores the right-bottom X coordinate,
and <rby_attr> stores the right-bottom Y coordinate. The
bounding box is computed assuming that all lines are of width 0.
get_named_obj_bbox(<obj_name>,<ltx_attr>,<lty_attr>,<rbx_attr>,<rby_attr>)
This command stores the absolute coordinate of the bounding box
of the object named <obj_name> in the specified attributes.
<ltx_attr> stores the left-top X coordinate, <lty_attr> stores
the left-top Y coordinate, <rbx_attr> stores the right-bottom X
coordinate, and <rby_attr> stores the right-bottom Y coordinate.
The bounding box is computed assuming that all lines are of width
0.
move_selected_obj_absolute(<ltx>,<lty>)
This command moves left-top corner of the selected object to
(<ltx>,<lty>).
assign(<attr_name>,<expr>)
This command assigns <expr> to the attribute specified by
<attr_name>. <expr> must be evaluated to a numeric value.
strcpy(<attr_name>,<string>)
This command copies <string> into the attribute specified by
<attr_name>.
copy_string_to_cut_buffer(<string>)
This command copies <string> into the cut buffer.
strcat(<attr_name>,<string>)
This command appends <string> to the attribute specified by
<attr_name>.
while(<expr>,<cmd_attr_name>)
This command keeps executing the internal command in
<cmd_attr_name> until <expr> evaluates to 0.
if(<expr>,<then_cmd_attr_name>,<else_cmd_attr_name>)
If <expr> evaluates to 0, the internal command in
<else_cmd_attr_name> is executed; otherwise, the internal command
in <then_cmd_attr_name> is executed. <then_cmd_attr_name> or
<else_cmd_attr_name> can be the string NULL (case-sensitive); in
this case, no corresponding action is taken.
get_current_file(<attr_name>)
This command stores the full path name of the current file in
<attr_name>.
get_current_export_file(<attr_name>)
This command stores the full path name of the output
(print/export) file in <attr_name>.
- 30 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
get_current_dir(<attr_name>)
This command stores the current directory in <attr_name>.
getenv(<attr_name>,<env_var_name>)
This command stores the environment variable named <env_var_name>
in <attr_name>.
strlen(<attr_name>,<string>)
This command assigns the number of characters in <string> to
<attr_name>.
substr(<attr_name>,<string>,<start_index>,<length>)
This command copies <length> characters, starting from the
character index <start_index>, of <string> into <attr_name>. The
<start_index> is zero-based.
strstr(<attr_name>,<string>,<sub_string>)
This command finds the first occurrence of <sub_string> in
<string> and copies <sub_string> and the rest of the string into
<attr_name>.
strrstr(<attr_name>,<string>,<sub_string>)
This command finds the last occurrence of <sub_string> in
<string> and copies <sub_string> and the rest of the string into
<attr_name>.
unmake_selected_obj_iconic()
This command has the same effect as selecting UnMakeIconic() from
the Special Menu except that at least one object must be selected
already.
hyperjump_then_exec(<attr_name>,<attr_name_to_exec>)
This command teleports to the file name or URL name found in the
<attr_name> attribute then executes the internal command
specified by the <attr_name_to_exec> attribute in the new file.
show_attr(<attr_name>)
This command makes the <attr_name> attribute visible.
hide_attr(<attr_name>)
This command makes the <attr_name> attribute invisible.
show_attr_name(<attr_name>)
This command makes the name part of the <attr_name> attribute
visible.
hide_attr_name(<attr_name>)
This command makes the name part of the <attr_name> attribute
invisible.
- 31 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
show_value(<attr_value>)
This command makes the attribute whose name is empty and whose
value is <attr_value> visible.
hide_value(<attr_value>)
This command makes the attribute whose name is empty and whose
value is <attr_value> invisible.
get_attr_bbox(<ltx_attr>,<lty_attr>,<rbx_attr>,<rby_attr>,<attr_name>)
This command stores the absolute coordinate of the bounding box
of the <attr_name> attribute in the specified attributes.
<ltx_attr> stores the left-top X coordinate, <lty_attr> stores
the left-top Y coordinate, <rbx_attr> stores the right-bottom X
coordinate, and <rby_attr> stores the right-bottom Y coordinate.
The bounding box is computed assuming that all lines are of width
0.
size_selected_obj_absolute(<abs_w>,<abs_h>)
This command stretches the right-bottom corner of the selected
object so that its width becomes <abs_w> and height becomes
<abs_h>.
size_named_obj_absolute(<obj_name>,<abs_w>,<abs_h>)
This command stretches the right-bottom corner of the object
named <obj_name> so that its width becomes <abs_w> and height
becomes <abs_h>.
message_box(<attr_name>,<msg>,<title>,<style>)
This command displays a messagebox with <title> as the title and
<msg> as the message. <style> can be the string "info", "ync",
"yn", or "stop". The messagebox display an OK button for the
"info" or "stop" styles, YES/NO/CANCEL buttons for the "ync"
style, YES/NO buttons for the "yn" style. When the user click a
button in the messagebox, the name of the button will be placed
in <attr_name>. If the user cancels the messagebox by typing the
<ESC> key, <attr_name> will be set to the string "CANCEL". If
<attr_name> is the string NULL (case-sensitive), the information
about which button is clicked is not written anywhere. If
<title> is the string NULL, Tgif will be the title for the
messagebox.
get_user_input(<attr_name>,<msg1>,<msg2>)
This command displays a dialogbox with <msg1> in the first line
and <msg2> in the second line. If <msg2> is the string
"USE_CURRENT_DIR", the second line displays the current
directory. The user can type in a line in the dialogbox which
get placed in <attr_name>. If the user cancels the dialog by
typing the <ESC> key, <attr_name> will be set to the empty
string.
- 32 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
add_attr_to_selected_obj(<attr_name>,<attr_value>,<abs_x>,<abs_y>)
This command adds <attr_name>=<attr_value> to a selected object
and place the attribute at (<abs_x>,<abs_y>). If <attr_name> is
the string NULL (case-sensitive), the attribute's name will be
the empty string. If <abs_x> and <abs_y> are both NULL (case-
sensitive), the attribute will be placed below the lower left
corner or the object. If <attr_name> starts with "!.", a file
attribute will be added.
delete_attr_from_selected_obj(<attr_name>)
This command deletes an attribute named <attr_name> from a
selected object. If <attr_name> starts with "!.", a file
attribute will be deleted.
user_end_an_edge(<attr_name>,<abs_x>,<abs_y>)
This command starts a polyline/open-spline at (<abs_x>,<abs_y>),
switches the drawing mode to the draw polyline/open-spline, and
lets the user finishes the polyline/open-spline. If the endpoint
falls in an object having an attribute type=port, that object's
name will be placed in <attr_name>, if <attr_name> is not the
string NULL (case-sensitive).
user_draw_an_edge(<start_attr_name>,<end_attr_name>)
This command switches the drawing mode to the draw
polyline/open-spline and lets the user draw a polyline/open-
spline. If the first endpoint falls in an object having an
attribute type=port, that object's name will be placed in
<start_attr_name>, if <attr_name> is not the string NULL (case-
sensitive). If the last endpoint falls in an object having an
attribute type=port, that object's name will be placed in
<end_attr_name>, if <attr_name> is not the string NULL (case-
sensitive).
get_a_poly_vertex_absolute(<x_attr_name>,<y_attr_name>,<obj_name>,<index>)
This command stores the absolute coordinate of the <index>th
vertex of <obj_name> in attributes specified by <x_attr_name> and
<y_attr_name>. The object specified by <obj_name> must be either
a poly/open-spline or a polygon/closed-spline object.
move_a_poly_vertex_absolute(<obj_name>,<index>,<abs_x>,<abs_y>)
This command moves the <index>th vertex of <obj_name> to the
absolute coordinate (<abs_x>,<abs_y>). The object specified by
<obj_name> must be either a poly/open-spline or a
polygon/closed-spline object.
post_attr_and_get_cgi_result(<url_attr>,<query_attr>,<result_attr>)
This command makes an HTTP request using the POST method.
<url_attr> names the attribute that contains the URL (which
usually names a CGI server script). <query_attr> names the
attribute whose value is the data to be posted. <result_attr>
names the attribute for receiving the results. For example, if
- 33 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
an object has the following attributes:
url=http://bourbon.cs.umd.edu:8001/cgi-bin/echo-post
query=Hello World!
result=
exec=post_attr_and_get_cgi_result(url,query,result)
Executing this object will post "Hello World!" to the specified
CGI script. In this case, the result of executing the script
just echoes "Hello World!" back (along with some other
bookkeeping information).
navigate_back()
This command performs the same operation as if the NavigateBack()
is selected from the Navigate Menu.
stop()
This command stops the execution of all internal commands.
sqrt(<attr_name>,<expr>)
This command assigns the square-root of <expr> to <attr_name>.
<expr> must be evaluated to a non-negative numeric value.
random(<attr_name>)
This command assigns a random integer to <attr_name> using the C
library function rand(). 0 is used as a seed for the random
number generator.
srand48(<use_cur_time_as_seed>)
This command seeds the random generator used by the C library
function drand48(). If <use_cur_time_as_seed> is 0, 0 will be
used as a seed. Otherwise, the current time will be used as a
seed.
drand48(<attr_name>)
This command assigns a floating pointer number between 0.0 and
1.0 to <attr_name> using the C library function drand48().
round(<attr_name>,<expr>)
This command assigns the round of <expr> to <attr_name>.
redraw_obj(<obj_name>)
This command redraws the area occupied by <obj_name>.
redraw_drawing_area()
This command redraws the whole drawing area (visible through the
Canvas Window).
itox(<attr_name>,<digits>,<expr>)
This command assigns <attr_name> to be the hex value of <expr>.
<digits> (which must be between 1 and 8, inclusive) is the final
- 34 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
width of the hex value (zeroes are added on the left).
for_i(<attr_name>,<min_val>,<max_val>,<increment>,<cmd_attr_name>)
This command is the same as the following sequence of commands:
assign(<attr_name>,<min_val>);
while($(<attr_name>) <= <max_val>,loop)
where loop has the following value:
exec(<cmd_attr_name>);
inc(<attr_name>,<increment>)
Please note that <min_val>, <max_val>, and <increment> are only
evaluated once prior the execution of this command.
set_file_not_modified()
This command sets the file modified flag to false.
new_id(<attr_name>)
This command generates an object ID, which is (unique in the
current drawing, and stores it in <attr_name>.
rotate_selected_obj(<angle>)
This command rotates the selected object by <angle> degrees.
Positive angle is clockwise.
call_simple_shortcut(<shortcut_name>)
This command calls a shortcut named <shortcut_name> which takes
no arguments. Please see the SHORTCUTS section for a description
of shortcuts.
call_one_arg_shortcut(<shortcut_name>,<arg>)
This command calls a shortcut named <shortcut_name> that takes
one argument and pass <arg> to it. Please see the SHORTCUTS
section for a description of shortcuts.
substitute_attr(<attr_name>,<src_attr_name>,<replace_attr_name>,<pattern_str>)
This command replaces occurrances of <pattern_str> in the value
part of the attribute specified by <src_attr_name> by the value
of the attribute specified by <replace_attr_name> and write the
result into the attribute specified by <attr_name>.
get_file_size(<attr_name>,<file_name>)
This command puts the size of file specified by <file_name> in
the attribute specified by <attr_name>.
is_file(<attr_name>,<file_name>)
This command puts a "1" in the attribute specified by <attr_name>
if the file specified by <file_name> exists. It puts a "0"
otherwise.
- 35 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
index(<attr_name>,<string>,<sub_string>)
This command finds the first occurrence of <sub_string> in
<string> and copies the zero-based index into <attr_name>.
rindex(<attr_name>,<string>,<sub_string>)
This command finds the last occurrence of <sub_string> in
<string> and copies the zero-based index into <attr_name>.
get_number_of_lines_in_attr(<result_attr>,<attr_name>)
This command counts the number of lines in the attribute
specified by <attr_name> and writes the count into <result_attr>.
get_line_in_attr(<result_attr>,<attr_name>,<line_number>)
This command copies the nth line of the attribute specified by
<attr_name> into <result_attr>, where n is a zero-based index
specified by <line_number>.
trim(<attr_name>)
This command removes leading and trailing blank characters from
the attribute specified by <attr_name>.
is_attr(<result_attr>,<attr_name>)
This command writes a "1" into <result_attr> if the attribute
specified by <attr_name> exists. It writes a "0" into
<result_attr> otherwise.
find_obj_names(<result_attr>,<obj_name>,<attr_name_value>)
This command finds all objects that are direct sub-objects of the
object specified by <obj_name> and writes their names into
<result_attr>. If <obj_name> is an empty string, all top-level
objects are scanned.
<attr_name_value> specifies a filter for the objects. If
<attr_name_value> is the empty string, all qualifying objects are
selected. If <attr_name_value> is of the form "<string>=*", an
object is selected if it has an attribute named <string>. If
<attr_name_value> is of the form "<string>=<value>", an object is
selected if it has an attribute named <string> and its
corresponding value is <value>. If <attr_name_value> does not
contain the '=' character, an object is selected if it has an
attribute whose name is empty and the corresponding value is
identical to <attr_name_value>.
If n objects are matched, the attribute specified by
<result_attr> is updated with n+1 lines. The value of the zeroth
line becomes n and the object names becomes lines 1 through n of
<result_attr>. The get_line_in_attr() internal command can be
used to retrieve the object names.
tokenize(<result_attr>,<string>,<separator>)
This command breaks <string> into tokens which are separated by
- 36 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
the <separator> character and writes the tokens (in the same
fashion as in the find_obj_names command above) into
<result_attr>. <separator> must be a string of length of 1 and
it must not be the space character, the single-quote character,
or the double-quote character. If a token contains the separator
character, the token can be surrounded by a pair of single-quotes
or double-quotes which are automatically removed when this
command is executed.
If n tokens are found, the attribute specified by <result_attr>
is updated with n+1 lines. The value of the zeroth line becomes
n and the tokens becomes lines 1 through n of <result_attr>. The
get_line_in_attr() internal command can be used to retrieve the
tokens.
move_attr_relative(<attr_name>,<dx>,<dy>)
This command moves the attribute whose name is <attr_name> by
<dx> absolute units in the x direction and <dy> absolute units in
the y direction.
get_number_of_vertices(<result_attr>,<obj_name>)
This command copies the number of vertices of the object
specified by <obj_name> into <result_attr>. The specified object
must be a polyline (open-spline) or a polygon (closed-spline).
is_obj_transformed(<result_attr>,<obj_name>)
This command writes a "1" into <result_attr> if the object
specified by <obj_name> is transformed (rotated or sheared). It
writes a "0" into <result_attr> otherwise.
make_selected_obj_iconic(<sym_path>)
This command works like the MakeIconic() command from the Special
Menu, except that the user is not prompted for the name of the
icon. Instead, <sym_path> is used to specify the full path name
of the icon.
get_tgif_version(<major_attr,minor_attr,patchlevel_attr,build_attr>)
This command writes tgif's major version number, minor version
number, patchlevel, and build information into <major_attr>,
<minor_attr>, <patchlevel_attr> and <build_attr>, respectively.
If an argument is the string NULL (case-sensitive), that
information is skipped.
get_tgif_dir(<result_attr>)
This command writes "$HOME/.Tgif" into <result_attr> where $HOME
is the home directory of the user.
get_profile_string(<result_attr>,<section>,<key>,<def_value>,<ini_path>)
This command gets the value associated with the key specified by
<key> from the section specified by <section> in the file
specified by the full path <ini_path> and stores it into the
- 37 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
attribute specified by <result_attr>. If there is not value
associated with the specified key, <def_value> is stored into
<result_attr>. If <key> is an empty string, all the key names in
<section> of <ini_path> will be written (in the same fashion as
in the find_obj_names command above) into <result_attr>. If
<section> is an empty string, all the section names in <ini_path>
will be written (in the same fashion as in the find_obj_names
command above) into <result_attr>.
write_profile_string(<section>,<key>,<value>,<ini_path>)
This command sets the value associated with the key specified by
<key> of the section specified by <section> in the file specified
by the full path <ini_path> to be <value>. If <key> is an empty
string, all key/value pairs in <section> of <ini_path> will be
cleared. <section> should not be an empty string.
select_additional_obj(<obj_name>)
This command silently (no highlighting handles) selects an
additional object named <obj_name>. Please see the OBJECT NAMES
section above for the specification of object names.
open_file(<file_number>,<file_name>,<file_mode>)
This command opens the file specified by <file_name> in the mode
specified by <file_mode> and assigns the opened file a file
reference number of <file_number>. <file_number> must be 0 or
between 3 and 15. Opening file 0 rewinds the standard input.
Examples of modes are "r" for reading, "w" for writing, and "a"
for appending. A file is always opened in text (non-binary)
mode.
close_file(<file_number>)
This command closes the file associated with file reference
number <file_number>. <file_number> must be 0 or between 3 and
15.
read_file(<file_number>,<result_attr>)
This command reads a line from the file associated with file
reference number <file_number> and put the line in the attribute
specified by <result_attr>. <file_number> must be between 0 (for
standard input) or between 3 and 15.
write_file(<file_number>,<string>)
This command writes <string> to the file associated with file
reference number <file_number>. <file_number> must be between 1
and 15. Numbers 1 and 2 are for standard output and standard
error files.
flush_file(<file_number>)
This command flushes the file associated with file reference
number <file_number>. <file_number> must be between 1 and 15.
Numbers 1 and 2 are for standard output and standard error files.
- 38 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
append_file(<dest_file_name>,<src_file_name>)
This command appends the file specified by <src_file_name> to the
file specified by <dest_file_name>.
set_output_format(<format>,<color_output>)
This command sets the output format to <format>. If
<color_output> is 0, black and white output (printing) mode will
be used; otherwise, color output (printing) mode will be used.
Please see the Tgif.WhereToPrint X default for a list of possible
formats.
set_export_clip_rect(<ltx>,<lty>,<rbx>,<rby>)
This command sets the export clipping rectangle to be a
rectangular region with left-top corner at (<ltx>,<lty>) and
right-bottom corner at (<rbx>,<rby>). <ltx> must be strickly
less than <rbx> and <lty> must be strickly less than <rby>.
import_file(<file_name>,<format>,<ltx>,<lty>)
This command imports the file specified by <file_name> and place
it at (<ltx>,<lty>). The file is expected to be in the format
specified by <format>, which can be "XBM", "XPM", "GIF", "PNG",
"JPEG", and names specified by the Tgif.ImportFilter# X defaults.
set_xpm_output_version(<version_number>)
This command sets the XPM version number when outputting in the
X11 pixmap format to be <version_number>. <version_number> can
take on values 1 or 3.
edit_ini_section(<attr_name>,<title>,<section>,<ini_path>)
This command brings up a dialogbox to edit the section specified
by <section> in the file specified by the full path <ini_path>.
If the user press the OK button in the dialogbox, the section is
cleared and the content of the dialogbox is written back into the
file, and "OK" is placed in the attribute specified by
<attr_name>. If the user press the CANCEL button in the
dialogbox, the file is unmodified, and "CANCEL" is placed in the
attribute specified by <attr_name>.
select_from_ini_section(<attr_name>,<title>,<section>,<ini_path>)
This command brings up a list to select an entry from the section
specified by <section> in the file specified by the full path
<ini_path>. If nothing is selected, the attribute specified by
<attr_name> will be cleared. Otherwise, the selected entry will
be written into the attribute specified by <attr_name>.
append_line_into_attr(<attr_name>,<string>)
This command appends the line specified by <string> to the
attribute specified by <attr_name>.
insert_line_into_attr(<attr_name>,<string>,<line_number>)
This command inserts the line specified by <string> as the nth
- 39 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
line of the attribute specified by <attr_name>, where n is a
zero-based index specified by <line_number>. n must be at least
1. If n is larger the number of lines in the attribute, blank
lines are automatically inserted.
clear_attr(<attr_name>)
This command clears the attribute value of the attribute
specified by <attr_name> and deletes all other lines of the
attribute if the attribute contains multiple lines.
create_text_obj(<abs_x>,<abs_baseline_y>,<string>)
This command creates a text object at the location
(<abs_x>,<abs_baseline_y>) with the text specified by <string>.
create_box_obj(<abs_ltx>,<abs_lty>,<abs_rbx>,<abs_rby>)
This command creates a rectangle defined by (<abs_ltx>,<abs_lty>)
and (<abs_rbx>,<abs_rby>).
create_corner_oval_obj(<abs_ltx>,<abs_lty>,<abs_rbx>,<abs_rby>)
This command creates a corner oval defined by
(<abs_ltx>,<abs_lty>) and (<abs_rbx>,<abs_rby>).
create_center_oval_obj(<abs_x>,<abs_y>,<radius>)
This command creates a center oval centered at (<abs_x>,<abs_y>)
with radius specified by <radius>.
create_edge_oval_obj(<abs_ltx>,<abs_lty>,<abs_rbx>,<abs_rby>)
This command creates an edge circle defined by
(<abs_ltx>,<abs_lty>) and (<abs_rbx>,<abs_rby>).
create_rcbox_obj(<abs_ltx>,<abs_lty>,<abs_rbx>,<abs_rby>)
This command creates a rounded-corner rectangle defined by
(<abs_ltx>,<abs_lty>) and (<abs_rbx>,<abs_rby>).
create_arc_obj(<abs_x>,<abs_y>,<radius>,<dir>,<angle1>,<angle2>)
This command creates an arc centered at (<abs_x>,<abs_y>) with
radius, direction, start angle, and end angle specified by
<radius>, <dir>, <angle1>, and <angle2>, respectively. The
<radius>, <dir>, <angle1>, and <angle2> are specified in the same
way as they are specified in the SpecifyAnArc() command under the
CreateObject Submenu of the Edit Menu. <dir> can be "+" or "-"
where "+" is clockwise. <angle1> and <angle2> are in degrees
with 0 degree at the 12 o'clock position.
create_first_vertex(<abs_x>,<abs_y>)
This command is used in conjunction with the create_next_vertex()
and create_poly_obj() commands to create a polyline/open-spline
object. It can also be used in conjunction with the
create_next_vertex() and create_polygon_obj() commands to create
a polygon/closed-spline object. This command sets the starting
point of the polyline/open-spline object or the polygon/closed-
- 40 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
spline object to be at (<abs_x>,<abs_y>).
create_next_vertex(<abs_x>,<abs_y>)
This command is used in conjunction with the
create_first_vertex() and create_poly_obj() commands to create a
polyline/open-spline object. It can also be used in conjunction
with the create_first_vertex() and create_polygon_obj() commands
to create a polygon/closed-spline object. This command sets the
next vertex of the polyline/open-spline object or the
polygon/closed-spline object to be at (<abs_x>,<abs_y>).
create_poly_obj()
This command is used in conjunction with the
create_first_vertex() and create_next_vertex() commands to create
a polyline/open-spline object.
create_polygon_obj()
This command is used in conjunction with the
create_first_vertex() and create_next_vertex() commands to create
a polygon/closed-spline object.
start_create_group_obj()
This command is used in conjunction with the create_group_obj()
command to create a grouped object. This command marks the
beginning of the group.
create_group_obj()
This command is used in conjunction with the
start_create_group_obj() command to create a grouped object.
This command groups all objects created since the last
start_create_group_obj() call into a grouped object.
set_allow_interrupt(<true_or_false>)
If <true_or_false> is FALSE (case-sensitive), this command is
used to temporarily disable an user interrupt when tgif is
executing internal commands. If a user interrupt is received
when interrupt is disabled, it will be queued and will interrupt
the execution of internal commands when set_allow_interrupt() is
called again with <true_or_false> being TRUE (case-sensitive).
select_each_obj_and_exec(<attr_name_to_exec>)
This command first unselects any object that is selected. It
then selects each object in the current drawing in turn and
executes the internal command specified by the
<attr_name_to_exec> attribute.
ARITHMETIC EXPRESSIONS
Certain internal commands allow arithmetic expressions as arguments.
Infix notation is used. Supported operators (and their precedences)
are listed below.
- 41 - Formatted: November 6, 2008
tgif(n) Tgif tgif(n)
Version 4.1 Patchlevel 34 and Above
? 1 if-then-else, e.g. <rel> ? <iftrue> : <else>
: 2 if-then-else, e.g. <rel> ? <iftrue> : <else>
|| 3 logical OR
&& 4 logical AND
| 5 bit-wise OR
^ 5 bit-wise XOR
& 5 bit-wise AND
== 6 equal
!= 6 not-equal
> 7 greater than
< 7 less than
>= 7 greater than or equal to
<= 7 less t |
