diagram(n) Documentation toolbox diagram(n) ______________________________________________________________________________
NAME
diagram - Diagram drawing
SYNOPSIS
package require Tcl 8.5
package require Tk 8.5
package require diagram 1
::diagram objectName canvas ?script?
diagramObject new direction name ?key value...?
diagramObject new element name attributes cmdprefix
diagramObject new alias name cmdprefix
diagramObject new command name arguments body
diagramObject new attribute name ?key value...?
diagramObject unknown attribute cmdprefix
diagramObject draw script
arc attr...
arrow attr...
--> attr...
<--> attr...
<--> attr...
block script attr...
box attr...
circle attr...
O attr...
diamond attr...
<> attr...
drum attr...
ellipse attr...
line attr...
-- attr...
move attr
spline attr...
text attr...
west
w
left
l
south
s
down
bottom
bot
b
east
e
right
r
north
n
up
top
t
northwest
nw
up-left
upleft
leftup
northeast
ne
up-right
upright
rightup
southwest
sw
down-left
downleft
leftdown
southeast
se
down-right
downright
rightdown
number cm
number mm
number inch
number pt
number number
by distance direction
point1 + point2
point1 - point2
point by distance direction
point1 | point2
n between poin1 point2
intersect elem1 elem2
element names ?pattern?
element corner
element corner1 corner2...
element ?corner1... ?names ?pattern??]?
nth ?corner?
nth last ?corner?
nth shape ?corner?
nth last shape ?corner?
last ?corner?
last shape ?corner?
1st
2nd
3rd
_________________________________________________________________
DESCRIPTION
Welcome to diagram, a package for the easy construction of diagrams
(sic), i.e. 2D vector graphics, sometimes also called pictures. Note
that this package is not a replacement for Tk's canvas, but rather a
layer sitting on top of it, to make it easier to use. In other words,
using the canvas as the core graphics engine diagram abstracts away
from the minutiae of handling coordinates to position and size the
drawn elements, allowing the user to concentrate on the content of the
diagram instead.
This is similar to Brian Kernighan's PIC language for troff, which is
the spiritual ancestor of this package.
This document contains the reference to the API and drawing (language)
commands. Its intended audience are users of the package wishing to
refresh their memory. Newcomers should read the Diagram Language Tuto-
rial first. Developers wishing to work on the internals of the package
and its supporting packages should look at section Diagram Classes
first, and then the comments in the sources of the packages itself.
In the remainder of the document we first describe the APIs of the dia-
gram class and its instances, followed by the language reference for
the drawing language itself.
API
CLASS API
The package exports the API described here.
::diagram objectName canvas ?script?
The command creates a new instance of a diagram controller and
returns the fully qualified name of the object command as its
result. The new instance is connected to the specified canvas
object, which is used as the diagrams graphics engine. This is
usually an instance of Tk's canvas, however any object which is
API compatible to Tk's canvas can be used here.
The API of this object command is described in the following
section, Object API. It may be used to invoke various operations
on the object.
If the script argument is specified then method draw will be
invoked on it.
OBJECT API
Instances of the diagram class support the following methods:
diagramObject new direction name ?key value...?
This method defines a new named direction and its attributes.
The latter is given through the key/value pairs coming after the
name.
Users are mostly free to specify arbitrary attributes with what-
ever meaning they desire. The exception are the names angle and
opposite. They are special to the diagram package and have a
fixed meaning.
angle This attribute specifies the angle of the direction in
degrees, where 0 points east (to the right) and 90 points
north (up).
opposite
This attribute specifies the name of the direction which
should be considered as complementary to the named one.
diagramObject new element name attributes cmdprefix
This method defines a new graphics element for the drawing lan-
guage. I.e. name will become a new command in the language, and
the specified command prefix (cmdprefix) will be called to per-
form the actual drawing.
attributes specifies the set of attributes for which data has to
be available. I.e. the system will run the See the method new
attribute for more information on attribute definitions.
The command prefix is expected to conform to the following sig-
nature:
cmdprefix canvas attributes
Where canvas is the handle of the canvas widget to draw
to, and attributes is a dictionary holding the attributes
for the element, be they user-specified, or defaults.
The results of the command has to be a list containing at
least two and at most four items. These are, in order:
[1] The list of canvas items the drawn element con-
sists of.
[2] The dictionary of named locations in the element,
its corners.
[3] An optional mode, either "relative" or "absolute".
When not returned "relative" is assumed. In the
case of a relative element position the attributes
"with" and "at" are used to determine the final
position of the new element.
[4] An optional name of a direction. If not the empty
string this is handed to the automatic layouter as
the new direction to follow.
diagramObject new alias name cmdprefix
This method defines a new command for the drawing language. I.e.
name will become a new command in the language, and the speci-
fied command prefix (cmdprefix) will be called on use of this
new command. Any arguments given to the command are simply
passed to the prefix. There is no fixed siganture.
Note that the prefix is run in the context of the drawing lan-
guage, allowing the direct use of any existing commands.
diagramObject new command name arguments body
This is like new alias except that the new command is defined as
a procedure in the language's context, with regular argument
list and body.
diagramObject new attribute name ?key value...?
This method defines a new named attribute which can be used by
graphical elements. The handling of the attribute by the proces-
sor is declared through the key/value pairs coming after the
name.
The accepted keys and their meanings are:
key The value of this key is the name of the key under which
the attribute's value shall be stored in the attribute
dictionary given to the drawing command after attribute
processing is complete.
This key is optional. If it is not specified it defaults
to the name of the attribute.
get The value of this key is a command prefix which will be
invoked to retrieve the attribute's argument(s) from the
command line.
This key is optional. If it is not specified a default is
used which takes the single word after the attribute name
as the attribute's value.
The signature of the command prefix is
cmdprefix wordqueue
Where wordqueue is the handle of a queue object
conforming to the API of the queues provided by
package struct::queue. This queue contains the
not-yet-processed part of the attribute defini-
tions, with one entry per word, with the first
entry the word after name of the attribute. In
other words, the attribute's name has already been
removed from the queue.
The result of the command is the value of the
attribute, which may have been taken from the
queue, or not.
transform
The value of this key is a command prefix which will be
invoked to transform the retrieved value (See get) into
their final form.
This key is optional. If it is not specified no transfor-
mation is done. The signature of the command prefix is
cmdprefix value
Where value is the value to transform.
The result of the command is the final value of
the attribute.
type The value of this key is a command prefix which will be
invoked to validate the attribute's argument(s).
This key is optional. If it is not specified no valida-
tion is done.
The signature of the command prefix is that of snit vali-
dation types. See the documentation of the snit package.
merge The value of this key is a command prefix which will be
invoked to insert the transformed and validated attribute
value into the dictionary of collected attributes.
This key is optional. If it is not specified a default
merge is chosen, based on the data for key aggregate, see
below. The signature of the command prefix is
cmdprefix value dict
Where value is the value to insert, and dict the
dictionary of attributes and values collected so
far.
The result of the command is the new dictionary of
attributes.
aggregate
The value of this key is a boolean flag. It has an effect
if and only if the key merge was not specified. This key
is optional. If it is not specified it defaults to False.
If the key is effective, the value of False means that
the attribute's value is set into the dictionary using
the value of key key (see above) as index, overwriting
any previously specified value.
If the key is effective, the value of True means that the
attribute's value is added to the dictionary using the
value of key key (see above) as index, extending any pre-
viously specified value. This means that the final value
of the attribute as seen after processing will be a list
of the collected values.
default
The value of this key is a command prefix which will be
invoked after collection of attributes has been completed
and this attribute is in the list of required attributes
for the drawing element (See argument attributes of
method new element).
Note that the connection is made through the value of key
key, not through the attribute name per se.
Further note that this command prefix is invoked even if
a user specified attribute value is present. This allows
the command to go beyond simply setting defaults, it can
calculate and store derived values as well.
This key is optional. If an element requires this
attribute, but default is not specified then nothing will
be done.
The signature of the command prefix is
cmdprefix init
This method is run when the attribute is defined,
its responsibility is to initialize anything in
the language namespace for the attribute and
default processing.
The result of this method is ignored.
cmdprefix fill varname
This method is run to put defaults, or derived
values into the attribute dictionary named by var-
name. This variable will be found in the calling
context.
The result of this method is ignored.
cmdprefix set name value
This method is run to push current a attribute
value into the language namespace, to make it the
new default.
The result of this method is ignored.
linked This key is effective if and only if key default is not
specified. In that case is supplies a default handling
for default, linking the attribute to a variable in the
language context.
The value for this key is a 2-element list containing the
name of the variable to link to, and its initial value,
in this order.
diagramObject unknown attribute cmdprefix
This method registers the command prefix with the subsystem pro-
cessing the attributes for element commands, telling it to call
it when it encounters an attribute it is unable to handle on its
on.
It is allowed to register more than callback, these will be
called in order of registration (i.e. first to last), until one
of the callbacks accepts the current input. The command prefix
is expected to conform to the following signature:
cmdprefix wordqueue
Where wordqueue is the handle of a queue object conform-
ing to the API of the queues provided by package
struct::queue. This queue contains the not-yet-processed
part of the attribute definitions, with one entry per
word, with the first entry the name of the attribute
which could not be processed.
The results of the command has to be a boolean value
where True signals that this callback has accepted the
attribute, processed it, and the new state of the
wordqueue is where the general processing shall continue.
Given the signature the command has basically two ways of
handling (rewriting) the attributes it recognizes:
[1] Replace the attribute (and arguments) with a dif-
ferent attribute and arguments.
[2] Push additional words in front to get the general
processing unstuck.
diagramObject draw script
This method runs the given script in the context of the drawing
language definitions. See section Language Reference for
details on the available commands.
Note that script is trusted. It is executed in the current
interpreter with access to its full abilities. For the execu-
tion of untrusted diagram scripts this interpreter should be a
safe one.
LANGUAGE REFERENCE
ELEMENTS
This section lists the commands for the predefined drawing elements,
aka shapes. These commands are all defined in the language's context.
All commands of this section return the handle of the newly created
element as their result. This handle also exists as a command which can
be used to query the element for its corners (names, values). See sec-
tion Miscellaneous Commands. IMAGE: figure-02-basic-shapes
arc attr...
IMAGE: figure-02-arc An open element with the corresponding cor-
ners, i.e. "start", "end", and "center". Note however that it
also has the compass rose of closed elements as its corners,
with the center of the arc's circle as the center of the compass
and the other points on the circle the arc is part of. It han-
dles the attributes
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
the text which is to be placed at the element's center,
by name. I.e. this attribute defines the text's position
relative to the element's center. The value is ignored
if no text was specified for the element. If not speci-
fied the system falls back to the value taken from the
language variable anchor, which itself defaults to cen-
ter. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAn-
chor.htm]. The commands without arguments are all short-
hands with the anchor implied. Note that they do not com-
bine, only the last is used. For comined directions the
main attribute command, anchor has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
clockwise
cw Specifies the direction of the arc element, here going
clockwise. The complementary attribute is counterclock-
wise. If not specified the system falls back to the
value taken from the language variable clockwise, which
itself defaults to false, for counter-clockwise direc-
tion.
color spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linecolor, which itself defaults to black.
counterclockwise
ccw Specifies the direction of the arc element, here counter-
clockwise. The complementary attribute is clockwise. If
not specified the system falls back to the value taken
from the language variable clockwise, which itself
defaults to false, for counter-clockwise direction.
fillcolor spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the inside of the element. If not specified the
system falls back to the value taken from the language
variable fillcolor, which itself defaults to the empty
string, signaling "no filling".
from location
Specifies the location where the arc element begins.
Defaults to the current location as maintained by the
layouting system.
justify left|center|right
Specifies how multi-line text associated with the element
is positioned within its box. The value is ignored if no
text was specified for the element. If not specified the
system falls back to the value taken from the language
variable justify, which itself defaults to left. The
legal values are left, right, and center.
radius length
Specifies the radius of the arc element, or rather, the
radius of the circle the shown arc is a part of. If not
specified the system falls back to the value taken from
the language variable arcradius, which itself defaults to
the pixel equivalent of 1 cm.
stroke width
IMAGE: figure-20-style-stroke Specifies the width of the
lines drawn for the the element, in pixels. If not spec-
ified the system falls back to the value taken from the
language variable linewidth, which itself defaults to 1.
style spec
IMAGE: figure-18-style-dash Specifies the style used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linestyle, which itself defaults to solid lines.
The legal values are all those accepted by Tk_GetDash
[http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-
dot", and "dash-dot-dot" are all accepted as shorthands for the
style command using them as argument.
text string
Specifies the text to associate with the element.
Defaults to nothing. When specified multiple times the
actually shown text is the concatenation of the individ-
ual strings, vertically stacked, with the first string
specified being the topmost element.
textcolor spec
Specifies the color used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textcolor, which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textfont, which itself defaults to Helvetica
12pt.
to location
Specifies the location where the arc element ends.
Defaults to a location such that a 90-degree arc is drawn
in the chosen direction, starting at from.
arrow attr...
--> attr...
<--> attr...
<--> attr...
IMAGE: figure-02-arrow An alias for the line element (see
below), with the attribute arrowhead preset to ->, <->, or <-.
The arrow is equivalent to -->.
block script attr...
A closed element with the corresponding corners, i.e. the eight
directions of the compass rose, and "center". The main effect
is the aggregration of all elements created by the script into
one element. This also means that while the elements created by
the script are visible in the element history while the script
is executing, afterward the history contains only the block
itself, and not the elements it is composed of.
The script has access to the current state of all variables in
the language context. Any changes to the variables will be
reverted after execution of the block. However, also, any vari-
ables set in the script will be exported as corners of the ele-
ment, allowing users to define their own named locations in the
block.
Regarding the layout mechanism any changes made by the script
are reverted after the element is done. In other words, a block
is an implicit group.
Blocks handle all attributes, propgating their settings into the
script as the default values active during script execution.
box attr...
IMAGE: figure-02-box A closed element with the corresponding
corners, i.e. the eight directions of the compass rose, and
"center". It handles the attributes
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
the text which is to be placed at the element's center,
by name. I.e. this attribute defines the text's position
relative to the element's center. The value is ignored
if no text was specified for the element. If not speci-
fied the system falls back to the value taken from the
language variable anchor, which itself defaults to cen-
ter. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAn-
chor.htm]. The commands without arguments are all short-
hands with the anchor implied. Note that they do not com-
bine, only the last is used. For comined directions the
main attribute command, anchor has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
at location
Specifies the location of the element's corner named by
the attribute with. Defaults to the current location as
maintained by the layouting system.
color spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linecolor, which itself defaults to black.
fillcolor spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the inside of the element. If not specified the
system falls back to the value taken from the language
variable fillcolor, which itself defaults to the empty
string, signaling "no filling".
height length
ht length
Specifies the height of the element. If not specified
the system falls back to the value taken from the lan-
guage variable boxheight, which itself defaults to the
pixel equivalent of 2 cm.
justify left|center|right
Specifies how multi-line text associated with the element
is positioned within its box. The value is ignored if no
text was specified for the element. If not specified the
system falls back to the value taken from the language
variable justify, which itself defaults to left. The
legal values are left, right, and center.
slant angle
Specifies the angle by which the box element is slanted,
in degrees. If not specified the system falls back to
the value taken from the language variable slant, which
itself defaults to 90, i.e. vertical, no slant. 0
degrees is slanting straight east, pointing to the right.
90 degrees is slanting to the north, pointing straight
up.
stroke width
IMAGE: figure-20-style-stroke Specifies the width of the
lines drawn for the the element, in pixels. If not spec-
ified the system falls back to the value taken from the
language variable linewidth, which itself defaults to 1.
style spec
IMAGE: figure-18-style-dash Specifies the style used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linestyle, which itself defaults to solid lines.
The legal values are all those accepted by Tk_GetDash
[http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-
dot", and "dash-dot-dot" are all accepted as shorthands for the
style command using them as argument.
text string
Specifies the text to associate with the element.
Defaults to nothing. When specified multiple times the
actually shown text is the concatenation of the individ-
ual strings, vertically stacked, with the first string
specified being the topmost element.
textcolor spec
Specifies the color used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textcolor, which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textfont, which itself defaults to Helvetica
12pt.
width length
wid length
Specifies the width of the element. If not specified the
system falls back to the value taken from the language
variable boxwidth, which itself defaults to the pixel
equivalent of 2 cm.
with corner
Specifies the corner of the element to place at the loca-
tion given by the attribute at. Defaults to the current
corner as maintained by the layouting system, except if
the value for at was specified by the user. In that case
it defaults to center.
circle attr...
O attr...
IMAGE: figure-02-circle A closed element with the corresponding
corners, i.e. the eight directions of the compass rose, and
"center". It handles the attributes
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
the text which is to be placed at the element's center,
by name. I.e. this attribute defines the text's position
relative to the element's center. The value is ignored
if no text was specified for the element. If not speci-
fied the system falls back to the value taken from the
language variable anchor, which itself defaults to cen-
ter. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAn-
chor.htm]. The commands without arguments are all short-
hands with the anchor implied. Note that they do not com-
bine, only the last is used. For comined directions the
main attribute command, anchor has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
at location
Specifies the location of the element's corner named by
the attribute with. Defaults to the current location as
maintained by the layouting system.
color spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linecolor, which itself defaults to black.
diameter length
diam length
Specifies the diameter of the circle element, as an
alternative way to specify its radius. Effective if and
only if the radius was not specified. I.e. if both diame-
ter and radius are specified then the radius infomration
has precendence. This attribute has no default, because
the defaults are taken from the radius.
fillcolor spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the inside of the element. If not specified the
system falls back to the value taken from the language
variable fillcolor, which itself defaults to the empty
string, signaling "no filling".
justify left|center|right
Specifies how multi-line text associated with the element
is positioned within its box. The value is ignored if no
text was specified for the element. If not specified the
system falls back to the value taken from the language
variable justify, which itself defaults to left. The
legal values are left, right, and center.
radius length
rad length
Specifies the radius of the circle element. If not spec-
ified the system falls back to the value taken from the
language variable circleradius, which itself defaults to
the pixel equivalent of 1 cm.
stroke width
IMAGE: figure-20-style-stroke Specifies the width of the
lines drawn for the the element, in pixels. If not spec-
ified the system falls back to the value taken from the
language variable linewidth, which itself defaults to 1.
style spec
IMAGE: figure-18-style-dash Specifies the style used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linestyle, which itself defaults to solid lines.
The legal values are all those accepted by Tk_GetDash
[http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-
dot", and "dash-dot-dot" are all accepted as shorthands for the
style command using them as argument.
text string
Specifies the text to associate with the element.
Defaults to nothing. When specified multiple times the
actually shown text is the concatenation of the individ-
ual strings, vertically stacked, with the first string
specified being the topmost element.
textcolor spec
Specifies the color used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textcolor, which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textfont, which itself defaults to Helvetica
12pt.
with corner
Specifies the corner of the element to place at the loca-
tion given by the attribute at. Defaults to the current
corner as maintained by the layouting system, except if
the value for at was specified by the user. In that case
it defaults to center.
diamond attr...
<> attr...
IMAGE: figure-02-diamond A closed element with the corresponding
corners, i.e. the eight directions of the compass rose, and
"center". It handles the attributes
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
the text which is to be placed at the element's center,
by name. I.e. this attribute defines the text's position
relative to the element's center. The value is ignored
if no text was specified for the element. If not speci-
fied the system falls back to the value taken from the
language variable anchor, which itself defaults to cen-
ter. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAn-
chor.htm]. The commands without arguments are all short-
hands with the anchor implied. Note that they do not com-
bine, only the last is used. For comined directions the
main attribute command, anchor has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
aspect number
Specifies the aspect ratio, i.e ratio of width to height,
of the diamond element. The manner in which a default is
calculated when not specified also depends on the speci-
fications of the attributes width and height, if any.
If both width, and height are specified then any specifi-
cation of aspect is ignored, as it is implicitly defined
in the width and height as well, and this takes prece-
dence. A missing specification is ignored in that case
well, i.e. no defaults are required.
If the aspect is specified, and one of the attributes
width or height, then the missing attribute is calculated
from the two which are specified. No defaults are
required for these cases either.
If only one of the attributes width or height is speci-
fied then the system uses a fallback for the aspect, the
value taken from the language variable diamondaspect,
which itselfs defaults to 2.
If none of of the attributes width or height is specified
then the system uses a fallback for the width, the value
taken from the language variable boxwidth, which itselfs
defaults to the pixel equivalent of 2 cm. For the aspect
it uses either the user-specified value or the default
taken as described in the previous paragraph.
at location
Specifies the location of the element's corner named by
the attribute with. Defaults to the current location as
maintained by the layouting system.
color spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linecolor, which itself defaults to black.
fillcolor spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the inside of the element. If not specified the
system falls back to the value taken from the language
variable fillcolor, which itself defaults to the empty
string, signaling "no filling".
height length
Specifies the height of the diamond element. The manner
in which a default is calculated when not specified also
depends on the specifications of the attributes aspect
and width, if any.
If both width, and height are specified then any specifi-
cation of aspect is ignored, as it is implicitly defined
in the width and height as well, and this takes prece-
dence. A missing specification is ignored in that case
well, i.e. no defaults are required.
If the aspect is specified, and one of the attributes
width or height, then the missing attribute is calculated
from the two which are specified. No defaults are
required for these cases either.
If only one of the attributes width or height is speci-
fied then the system uses a fallback for the aspect, the
value taken from the language variable diamondaspect,
which itselfs defaults to 2.
If none of of the attributes width or height is specified
then the system uses a fallback for the width, the value
taken from the language variable boxwidth, which itselfs
defaults to the pixel equivalent of 2 cm. For the aspect
it uses either the user-specified value or the default
taken as described in the previous paragraph.
justify left|center|right
Specifies how multi-line text associated with the element
is positioned within its box. The value is ignored if no
text was specified for the element. If not specified the
system falls back to the value taken from the language
variable justify, which itself defaults to left. The
legal values are left, right, and center.
stroke width
IMAGE: figure-20-style-stroke Specifies the width of the
lines drawn for the the element, in pixels. If not spec-
ified the system falls back to the value taken from the
language variable linewidth, which itself defaults to 1.
style spec
IMAGE: figure-18-style-dash Specifies the style used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linestyle, which itself defaults to solid lines.
The legal values are all those accepted by Tk_GetDash
[http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-
dot", and "dash-dot-dot" are all accepted as shorthands for the
style command using them as argument.
text string
Specifies the text to associate with the element.
Defaults to nothing. When specified multiple times the
actually shown text is the concatenation of the individ-
ual strings, vertically stacked, with the first string
specified being the topmost element.
textcolor spec
Specifies the color used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textcolor, which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textfont, which itself defaults to Helvetica
12pt.
width length
Specifies the width of the diamond element. The manner
in which a default is calculated when not specified also
depends on the specifications of the attributes aspect
and height, if any.
If both width, and height are specified then any specifi-
cation of aspect is ignored, as it is implicitly defined
in the width and height as well, and this takes prece-
dence. A missing specification is ignored in that case
well, i.e. no defaults are required.
If the aspect is specified, and one of the attributes
width or height, then the missing attribute is calculated
from the two which are specified. No defaults are
required for these cases either.
If only one of the attributes width or height is speci-
fied then the system uses a fallback for the aspect, the
value taken from the language variable diamondaspect,
which itselfs defaults to 2.
If none of of the attributes width or height is specified
then the system uses a fallback for the width, the value
taken from the language variable boxwidth, which itselfs
defaults to the pixel equivalent of 2 cm. For the aspect
it uses either the user-specified value or the default
taken as described in the previous paragraph.
with corner
Specifies the corner of the element to place at the loca-
tion given by the attribute at. Defaults to the current
corner as maintained by the layouting system, except if
the value for at was specified by the user. In that case
it defaults to center.
drum attr...
IMAGE: figure-02-drum A closed element with the corresponding
corners, i.e. the eight directions of the compass rose, and
"center". It handles the attributes
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
the text which is to be placed at the element's center,
by name. I.e. this attribute defines the text's position
relative to the element's center. The value is ignored
if no text was specified for the element. If not speci-
fied the system falls back to the value taken from the
language variable anchor, which itself defaults to cen-
ter. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAn-
chor.htm]. The commands without arguments are all short-
hands with the anchor implied. Note that they do not com-
bine, only the last is used. For comined directions the
main attribute command, anchor has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
aspect number
Specifies the aspect ratio, i.e ratio of width to height,
of the ellipses which are used to draw the top and bottom
of the drum element. If not specified the system falls
back to the value taken from the language variable dru-
maspect, which itself defaults to 0.35.
at location
Specifies the location of the element's corner named by
the attribute with. Defaults to the current location as
maintained by the layouting system.
color spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linecolor, which itself defaults to black.
fillcolor spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the inside of the element. If not specified the
system falls back to the value taken from the language
variable fillcolor, which itself defaults to the empty
string, signaling "no filling".
height length
ht length
Specifies the height of the element. If not specified
the system falls back to the value taken from the lan-
guage variable boxheight, which itself defaults to the
pixel equivalent of 2 cm.
justify left|center|right
Specifies how multi-line text associated with the element
is positioned within its box. The value is ignored if no
text was specified for the element. If not specified the
system falls back to the value taken from the language
variable justify, which itself defaults to left. The
legal values are left, right, and center.
stroke width
IMAGE: figure-20-style-stroke Specifies the width of the
lines drawn for the the element, in pixels. If not spec-
ified the system falls back to the value taken from the
language variable linewidth, which itself defaults to 1.
style spec
IMAGE: figure-18-style-dash Specifies the style used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linestyle, which itself defaults to solid lines.
The legal values are all those accepted by Tk_GetDash
[http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-
dot", and "dash-dot-dot" are all accepted as shorthands for the
style command using them as argument.
text string
Specifies the text to associate with the element.
Defaults to nothing. When specified multiple times the
actually shown text is the concatenation of the individ-
ual strings, vertically stacked, with the first string
specified being the topmost element.
textcolor spec
Specifies the color used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textcolor, which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textfont, which itself defaults to Helvetica
12pt.
width length
wid length
Specifies the width of the element. If not specified the
system falls back to the value taken from the language
variable boxwidth, which itself defaults to the pixel
equivalent of 2 cm.
with corner
Specifies the corner of the element to place at the loca-
tion given by the attribute at. Defaults to the current
corner as maintained by the layouting system, except if
the value for at was specified by the user. In that case
it defaults to center.
ellipse attr...
IMAGE: figure-02-ellipse A closed element with the corresponding
corners, i.e. the eight directions of the compass rose, and
"center". It handles the attributes
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
the text which is to be placed at the element's center,
by name. I.e. this attribute defines the text's position
relative to the element's center. The value is ignored
if no text was specified for the element. If not speci-
fied the system falls back to the value taken from the
language variable anchor, which itself defaults to cen-
ter. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAn-
chor.htm]. The commands without arguments are all short-
hands with the anchor implied. Note that they do not com-
bine, only the last is used. For comined directions the
main attribute command, anchor has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
at location
Specifies the location of the element's corner named by
the attribute with. Defaults to the current location as
maintained by the layouting system.
color spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linecolor, which itself defaults to black.
fillcolor spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the inside of the element. If not specified the
system falls back to the value taken from the language
variable fillcolor, which itself defaults to the empty
string, signaling "no filling".
height length
ht length
Specifies the height of the element. If not specified
the system falls back to the value taken from the lan-
guage variable boxheight, which itself defaults to the
pixel equivalent of 2 cm.
justify left|center|right
Specifies how multi-line text associated with the element
is positioned within its box. The value is ignored if no
text was specified for the element. If not specified the
system falls back to the value taken from the language
variable justify, which itself defaults to left. The
legal values are left, right, and center.
stroke width
IMAGE: figure-20-style-stroke Specifies the width of the
lines drawn for the the element, in pixels. If not spec-
ified the system falls back to the value taken from the
language variable linewidth, which itself defaults to 1.
style spec
IMAGE: figure-18-style-dash Specifies the style used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linestyle, which itself defaults to solid lines.
The legal values are all those accepted by Tk_GetDash
[http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-
dot", and "dash-dot-dot" are all accepted as shorthands for the
style command using them as argument.
text string
Specifies the text to associate with the element.
Defaults to nothing. When specified multiple times the
actually shown text is the concatenation of the individ-
ual strings, vertically stacked, with the first string
specified being the topmost element.
textcolor spec
Specifies the color used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textcolor, which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textfont, which itself defaults to Helvetica
12pt.
width length
wid length
Specifies the width of the element. If not specified the
system falls back to the value taken from the language
variable boxwidth, which itself defaults to the pixel
equivalent of 2 cm.
with corner
Specifies the corner of the element to place at the loca-
tion given by the attribute at. Defaults to the current
corner as maintained by the layouting system, except if
the value for at was specified by the user. In that case
it defaults to center.
line attr...
-- attr...
IMAGE: figure-02-line An open element with the corresponding
corners, i.e. "start", "end", and "center". It handles the
attributes
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
the text which is to be placed at the element's center,
by name. I.e. this attribute defines the text's position
relative to the element's center. The value is ignored
if no text was specified for the element. If not speci-
fied the system falls back to the value taken from the
language variable anchor, which itself defaults to cen-
ter. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAn-
chor.htm]. The commands without arguments are all short-
hands with the anchor implied. Note that they do not com-
bine, only the last is used. For comined directions the
main attribute command, anchor has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
arrowhead spec
IMAGE: figure-19-style-arrowheads Specifies where to draw
arrowheads on the line element, at the beginning or end,
at both ends, or none. If not specified the system falls
back to the value taken from the language variable arrow-
head, which itself defaults to none. The legal values
are
none, -
Draw no arrowheads, at neither end of the line.
start, first, <-
Draw an arrowhead at the beginning of the line,
but not at its end.
end, last, ->
Draw an arrowhead at the end of the line, but not
at its beginning.
both, <->
Draw arrowheads at both ends of the line.
Note that the values "start", "end", "-", "->", "<-", and "<->"
are all accepted as shorthands for the arrowhead command using
them as argument.
at location
Line elements are normally positioned absolutely, using
the locations specified through the attributes from,
then, and to. If at is specified however then these
positions are translated a last time, moving the line's
corner named by the attribute with to the location given
by this attribute.
chop ?length?
Specifies the length of the line element to remove from
the beginning and/or end. Defaults to nothing. If spec-
ified once the chopping applies to both beginning and end
of the line. If specified twice or more the last two
specifications are used, and applied to beginning and end
of the line, in this order. Whenever the attribute is
specified without an explicit length, the system falls
back to the value taken from the language variable cir-
cleradius, which itself defaults to the pixel equivalent
of 1 cm
color spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linecolor, which itself defaults to black.
fillcolor spec
IMAGE: figure-21-style-colors Specifies the color used to
draw the inside of the element. If not specified the
system falls back to the value taken from the language
variable fillcolor, which itself defaults to the empty
string, signaling "no filling".
from location
Specifies the location where the line element begins.
Defaults to the current location as maintained by the
layouting system.
justify left|center|right
Specifies how multi-line text associated with the element
is positioned within its box. The value is ignored if no
text was specified for the element. If not specified the
system falls back to the value taken from the language
variable justify, which itself defaults to left. The
legal values are left, right, and center.
noturn Specifies that the direction of line element at its end
is not propagated to the layout management. If not spec-
ified the direction of the line becomes the new direction
the layout.
smooth Specifies the use of bezier splines for the line element.
If not specified lines are drawn exactly through the
specified waypoints, without any smooth curves.
stroke width
IMAGE: figure-20-style-stroke Specifies the width of the
lines drawn for the the element, in pixels. If not spec-
ified the system falls back to the value taken from the
language variable linewidth, which itself defaults to 1.
style spec
IMAGE: figure-18-style-dash Specifies the style used to
draw the lines of the element. If not specified the sys-
tem falls back to the value taken from the language vari-
able linestyle, which itself defaults to solid lines.
The legal values are all those accepted by Tk_GetDash
[http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-
dot", and "dash-dot-dot" are all accepted as shorthands for the
style command using them as argument.
text string
Specifies the text to associate with the element.
Defaults to nothing. When specified multiple times the
actually shown text is the concatenation of the individ-
ual strings, vertically stacked, with the first string
specified being the topmost element.
textcolor spec
Specifies the color used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textcolor, which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textfont, which itself defaults to Helvetica
12pt.
then location
then (<direction> ?length?)...
(<direction> ?length?)...
This attribute specifies an intermediate location the
line element has to go through. It can be specified mul-
tiple times, with each use adding one additional location
to the series which the line will go through. These loca-
tion will be traversed in the order they were specified.
The location can be given explicitly, or as a series of
directions with distances. In the latter case the names
of all known directions are accepted for the direction
part. If no distance is specified for a direction the
system falls back to the value taken from the language
variable movelength, which itself defaults to the pixel
equivalent of 2 cm. The whole set of direction,distance
pairs is treated as a series of translations which are
added up to provide the final translation specifying the
intermediate point (relative to the preceding point).
The last named direction is propagated to the layout sys-
tem as the direction to follow. The use of noturn is not
able to overide this behaviour.
At last, the names of the registered directions also
serve as attribute commands, with an implicit attribute
then in front of them.
If no intermediate or last location is specified for the
line the system falls back to a point movelength pixels
away from the starting location, in the current direction
as maintained by the layouting system
to location
Specifies the location where the line element ends. This
attribute has no default. The default is handled by the
attribute then, which makes it appear as if to has a
default when not specified.
with corner
Line elements are normally positioned absolutely, using
the locations specified through the attributes from,
then, and to. If at is specified however then these
positions are translated a last time, moving the line's
corner named by the attribute with to the location given
by this attribute. This means that with is effective if
and only if the attribute at was specified as well for
the line.
move attr
An open element with the corresponding corners, i.e. "start",
"end", and "center". A move element is in essence an invisible
line. While the main effect we are interested in is the change
it makes to the layout system, it is an actual element, i.e. it
has the same corners as an ordinary line, and shows up in the
history as well, allowing future references to all the places it
touched. It handles the same attibutes as line elements.
spline attr...
IMAGE: figure-02-spline An alias for the line element (see
above), with the attribute smooth preset.
text attr...
IMAGE: figure-02-text A closed element with the corresponding
corners, i.e. the eight directions of the compass rose, and
"center". It handles the attributes
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
the text which is to be placed at the element's center,
by name. I.e. this attribute defines the text's position
relative to the element's center. The value is ignored
if no text was specified for the element. If not speci-
fied the system falls back to the value taken from the
language variable anchor, which itself defaults to cen-
ter. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAn-
chor.htm]. The commands without arguments are all short-
hands with the anchor implied. Note that they do not com-
bine, only the last is used. For comined directions the
main attribute command, anchor has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
at location
Specifies the location of the element's corner named by
the attribute with. Defaults to the current location as
maintained by the layouting system.
height length
Specifies the height of the text element. Defaults to
the natural height of its text.
justify left|center|right
Specifies how multi-line text associated with the element
is positioned within its box. The value is ignored if no
text was specified for the element. If not specified the
system falls back to the value taken from the language
variable justify, which itself defaults to left. The
legal values are left, right, and center.
text string
Specifies the text to associate with the element.
Defaults to nothing. When specified multiple times the
actually shown text is the concatenation of the individ-
ual strings, vertically stacked, with the first string
specified being the topmost element.
textcolor spec
Specifies the color used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textcolor, which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element
with. Ignored if there is no text. If not specified the
system falls back to the value taken from the language
variable textfont, which itself defaults to Helvetica
12pt.
width length
Specifies the width of the text element. Defaults to the
natural width of its text.
with corner
Specifies the corner of the element to place at the loca-
tion given by the attribute at. Defaults to the current
corner as maintained by the layouting system, except if
the value for at was specified by the user. In that case
it defaults to center.
ATTRIBUTES
The set of all attributes supported by all the element commands is
shown below. While we speak of them as commands, and provide a syntax,
they are not truly available as actual commands, but only as part of
the arguments for an element command.
Note that some of the attribute names are overloaded, i.e. have multi-
ple, different, definitions. During processing of attributes for an
element the actual definition used is chosen based on the type of the
element the processing is for.
Further, as a catch-all clause, any attribute which could not be pro-
cessed according to the definitions below will be treated as the argu-
ment of an implicit text attribute.
anchor name
ljust
rjust
above
below IMAGE: figure-22-text-anchoring-3 Specifies the anchor of the
text which is to be placed at the element's center, by name.
I.e. this attribute defines the text's position relative to the
element's center. The value is ignored if no text was specified
for the element. If not specified the system falls back to the
value taken from the language variable anchor, which itself
defaults to center. The legal values are all those accepted by
Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the
anchor implied. Note that they do not combine, only the last is
used. For comined directions the main attribute command, anchor
has to be used.
ljust "anchor west"
rjust "anchor east"
above "anchor south"
below "anchor north"
arrowhead spec
IMAGE: figure-19-style-arrowheads Specifies where to draw arrow-
heads on the line element, at the beginning or end, at both
ends, or none. If not specified the system falls back to the
value taken from the language variable arrowhead, which itself
defaults to none. The legal values are
none, -
Draw no arrowheads, at neither end of the line.
start, first, <-
Draw an arrowhead at the beginning of the line, but not
at its end.
end, last, ->
Draw an arrowhead at the end of the line, but not at its
beginning.
both, <->
Draw arrowheads at both ends of the line.
Note that the values "start", "end", "-", "->", "<-", and "<->" are all
accepted as shorthands for the arrowhead command using them as argu-
ment.
aspect number
Specifies the aspect ratio, i.e ratio of width to height, of the
diamond element. The manner in which a default is calculated
when not specified also depends on the specifications of the
attributes width and height, if any.
If both width, and height are specified then any specification
of aspect is ignored, as it is implicitly defined in the width
and height as well, and this takes precedence. A missing speci-
fication is ignored in that case well, i.e. no defaults are
required.
If the aspect is specified, and one of the attributes width or
height, then the missing attribute is calculated from the two
which are specified. No defaults are required for these cases
either.
If only one of the attributes width or height is specified then
the system uses a fallback for the aspect, the value taken from
the language variable diamondaspect, which itselfs defaults to
2.
If none of of the attributes width or height is specified then
the system uses a fallback for the width, the value taken from
the language variable boxwidth, which itselfs defaults to the
pixel equivalent of 2 cm. For the aspect it uses either the
user-specified value or the default taken as described in the
previous paragraph.
aspect number
Specifies the aspect ratio, i.e ratio of width to height, of the
ellipses which are used to draw the top and bottom of the drum
element. If not specified the system falls back to the value
taken from the language variable drumaspect, which itself
defaults to 0.35.
at location
Specifies the location of the element's corner named by the
attribute with. Defaults to the current location as maintained
by the layouting system.
at location
Line elements are normally positioned absolutely, using the
locations specified through the attributes from, then, and to.
If at is specified however then these positions are translated a
last time, moving the line's corner named by the attribute with
to the location given by this attribute.
chop ?length?
Specifies the length of the line element to remove from the
beginning and/or end. Defaults to nothing. If specified once
the chopping applies to both beginning and end of the line. If
specified twice or more the last two specifications are used,
and applied to beginning and end of the line, in this order.
Whenever the attribute is specified without an explicit length,
the system falls back to the value taken from the language vari-
able circleradius, which itself defaults to the pixel equivalent
of 1 cm
clockwise
cw Specifies the direction of the arc element, here going clock-
wise. The complementary attribute is counterclockwise. If not
specified the system falls back to the value taken from the lan-
guage variable clockwise, which itself defaults to false, for
counter-clockwise direction.
color spec
IMAGE: figure-21-style-colors Specifies the color used to draw
the lines of the element. If not specified the system falls
back to the value taken from the language variable linecolor,
which itself defaults to black.
counterclockwise
ccw Specifies the direction of the arc element, here counter-clock-
wise. The complementary attribute is clockwise. If not speci-
fied the system falls back to the value taken from the language
variable clockwise, which itself defaults to false, for counter-
clockwise direction.
diameter length
diam length
Specifies the diameter of the circle element, as an alternative
way to specify its radius. Effective if and only if the radius
was not specified. I.e. if both diameter and radius are speci-
fied then the radius infomration has precendence. This
attribute has no default, because the defaults are taken from
the radius.
fillcolor spec
IMAGE: figure-21-style-colors Specifies the color used to draw
the inside of the element. If not specified the system falls
back to the value taken from the language variable fillcolor,
which itself defaults to the empty string, signaling "no fill-
ing".
from location
Specifies the location where the line element begins. Defaults
to the current location as maintained by the layouting system.
from location
Specifies the location where the arc element begins. Defaults
to the current location as maintained by the layouting system.
height length
ht length
Specifies the height of the element. If not specified the sys-
tem falls back to the value taken from the language variable
boxheight, which itself defaults to the pixel equivalent of 2
cm.
height length
Specifies the height of the diamond element. The manner in
which a default is calculated when not specified also depends on
the specifications of the attributes aspect and width, if any.
If both width, and height are specified then any specification
of aspect is ignored, as it is implicitly defined in the width
and height as well, and this takes precedence. A missing speci-
fication is ignored in that case well, i.e. no defaults are
required.
If the aspect is specified, and one of the attributes width or
height, then the missing attribute is calculated from the two
which are specified. No defaults are required for these cases
either.
If only one of the attributes width or height is specified then
the system uses a fallback for the aspect, the value taken from
the language variable diamondaspect, which itselfs defaults to
2.
If none of of the attributes width or height is specified then
the system uses a fallback for the width, the value taken from
the language variable boxwidth, which itselfs defaults to the
pixel equivalent of 2 cm. For the aspect it uses either the
user-specified value or the default taken as described in the
previous paragraph.
height length
Specifies the height of the text element. Defaults to the natu-
ral height of its text.
justify left|center|right
Specifies how multi-line text associated with the element is
positioned within its box. The value is ignored if no text was
specified for the element. If not specified the system falls
back to the value taken from the language variable justify,
which itself defaults to left. The legal values are left,
right, and center.
noturn Specifies that the direction of line element at its end is not
propagated to the layout management. If not specified the
direction of the line becomes the new direction the layout.
radius length
rad length
Specifies the radius of the circle element. If not specified
the system falls back to the value taken from the language vari-
able circleradius, which itself defaults to the pixel equivalent
of 1 cm.
radius length
Specifies the radius of the arc element, or rather, the radius
of the circle the shown arc is a part of. If not specified the
system falls back to the value taken from the language variable
arcradius, which itself defaults to the pixel equivalent of 1
cm.
slant angle
Specifies the angle by which the box element is slanted, in
degrees. If not specified the system falls back to the value
taken from the language variable slant, which itself defaults to
90, i.e. vertical, no slant. 0 degrees is slanting straight
east, pointing to the right. 90 degrees is slanting to the
north, pointing straight up.
smooth Specifies the use of bezier splines for the line element. If
not specified lines are drawn exactly through the specified way-
points, without any smooth curves.
stroke width
IMAGE: figure-20-style-stroke Specifies the width of the lines
drawn for the the element, in pixels. If not specified the sys-
tem falls back to the value taken from the language variable
linewidth, which itself defaults to 1.
style spec
IMAGE: figure-18-style-dash Specifies the style used to draw the
lines of the element. If not specified the system falls back to
the value taken from the language variable linestyle, which
itself defaults to solid lines. The legal values are all those
accepted by Tk_GetDash [http://www.tcl.tk/man/tcl8.5/TkLib/Get-
Dash.htm], and additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the style command
using them as argument.
text string
Specifies the text to associate with the element. Defaults to
nothing. When specified multiple times the actually shown text
is the concatenation of the individual strings, vertically
stacked, with the first string specified being the topmost ele-
ment.
textcolor spec
Specifies the color used to draw the text of an element with.
Ignored if there is no text. If not specified the system falls
back to the value taken from the language variable textcolor,
which itself defaults to black.
textfont spec
Specifies the font used to draw the text of an element with.
Ignored if there is no text. If not specified the system falls
back to the value taken from the language variable textfont,
which itself defaults to Helvetica 12pt.
then location
then (<direction> ?length?)...
(<direction> ?length?)...
This attribute specifies an intermediate location the line ele-
ment has to go through. It can be specified multiple times,
with each use adding one additional location to the series which
the line will go through. These location will be traversed in
the order they were specified.
The location can be given explicitly, or as a series of direc-
tions with distances. In the latter case the names of all known
directions are accepted for the direction part. If no distance
is specified for a direction the system falls back to the value
taken from the language variable movelength, which itself
defaults to the pixel equivalent of 2 cm. The whole set of
direction,distance pairs is treated as a series of translations
which are added up to provide the final translation specifying
the intermediate point (relative to the preceding point).
The last named direction is propagated to the layout system as
the direction to follow. The use of noturn is not able to
overide this behaviour.
At last, the names of the registered directions also serve as
attribute commands, with an implicit attribute then in front of
them.
If no intermediate or last location is specified for the line
the system falls back to a point movelength pixels away from the
starting location, in the current direction as maintained by the
layouting system
to location
Specifies the location where the line element ends. This
attribute has no default. The default is handled by the
attribute then, which makes it appear as if to has a default
when not specified.
to location
Specifies the location where the arc element ends. Defaults to
a location such that a 90-degree arc is drawn in the chosen
direction, starting at from.
width length
wid length
Specifies the width of the element. If not specified the system
falls back to the value taken from the language variable
boxwidth, which itself defaults to the pixel equivalent of 2 cm.
width length
Specifies the width of the diamond element. The manner in which
a default is calculated when not specified also depends on the
specifications of the attributes aspect and height, if any.
If both width, and height are specified then any specification
of aspect is ignored, as it is implicitly defined in the width
and height as well, and this takes precedence. A missing speci-
fication is ignored in that case well, i.e. no defaults are
required.
If the aspect is specified, and one of the attributes width or
height, then the missing attribute is calculated from the two
which are specified. No defaults are required for these cases
either.
If only one of the attributes width or height is specified then
the system uses a fallback for the aspect, the value taken from
the language variable diamondaspect, which itselfs defaults to
2.
If none of of the attributes width or height is specified then
the system uses a fallback for the width, the value taken from
the language variable boxwidth, which itselfs defaults to the
pixel equivalent of 2 cm. For the aspect it uses either the
user-specified value or the default taken as described in the
previous paragraph.
width length
Specifies the width of the text element. Defaults to the natu-
ral width of its text.
with corner
Specifies the corner of the element to place at the location
given by the attribute at. Defaults to the current corner as
maintained by the layouting system, except if the value for at
was specified by the user. In that case it defaults to center.
with corner
Line elements are normally positioned absolutely, using the
locations specified through the attributes from, then, and to.
If at is specified however then these positions are translated a
last time, moving the line's corner named by the attribute with
to the location given by this attribute. This means that with
is effective if and only if the attribute at was specified as
well for the line.
CORNERS
Corners are named values for in elements, usually locations.
o The closed elements define corners for the compass rose, includ-
ing the "center", and their "width" and "height".
IMAGE: figure-27-corners-closed
o block elements additionally export all variables which were set
during their definition as corners.
o The open elements on the other hand define "start", "end", and
"center". The first two map to the locations originally provided
through the attributes from and to of the element.
IMAGE: figure-28-corners-open
o The center of line and move elements is the location halfway
between "start" and "end" corners, this is regardless of any
intermediate locations the element may have.
o The line and move elements additionally name all their locations
as corners using numbers as names, starting from 1 (equivalent
to "start"), in order of traversal.
IMAGE: figure-15-spline-1
o The center of arc elements is the center of the circle the arc
is part off.
o The arc elements additionally define the compass rose of closed
elements as well.
NAMED DIRECTIONS
The named directions are commands which tell the layout system in which
direction to go when placing the next element without an explicit posi-
tion specification. They can also be used as arguments to the
attribute then, and the command by for relative points, see there for
the relevant syntax.
The diagram core defines the directions of the compass rose, plus a
number of aliases. See below for the full list.
IMAGE: figure-27-corners-closed
This overlaps with the pre-defined corners for closed elements. This is
used by the layout system, when are going in direction X the name of
the opposite direction is the name of the corner at which the new ele-
ment will be attached to the current position, and if this corner does
not exist the nearest actual corner by angle is used.
west
w
left
l
south
s
down
bottom
bot
b
east
e
right
r
north
n
up
top
t
northwest
nw
up-left
upleft
leftup
northeast
ne
up-right
upright
rightup
southwest
sw
down-left
downleft
leftdown
southeast
se
down-right
downright
rightdown
MISCELLANEOUS COMMANDS
number cm
number mm
number inch
number pt
These commands allow the specification of distances and coordi-
nates in metric and imperial units, returning the equivalent
distance or coordinate in pixels, which is the unit used inter-
nally for all calculations.
The conversion factors are based on the result of tk scaling and
are computed once, at the time the package is sourced, future
changes of the tk scaling factor have no effect.
number number
IMAGE: figure-50-point-cons-absolute
This command takes the x and y coordinates of a location and
returns the absolute point for it.
by distance direction
IMAGE: figure-51-point-cons-relative
This command takes a distance and direction (angle in degress,
or registered direction name) and returns the relative point for
it, i.e. the delta or translation it represents.
Note also the (dis)similarities to the directional specifica-
tions for the attribute then of line and move elements. Where
we say here
by 50 east
for the attribute we say
or just
point1 + point2
IMAGE: figure-48-point-vectoradd
This command interprets two points as vectors and adds them
together. If at least one of the points is absolute the result
is absolute as well. The result is a relative point if and only
if both points are relative.
point1 - point2
IMAGE: figure-49-point-vectorsub
This command interprets two points as vectors and subtracts the
second from the first. If at least one of the points is abso-
lute the result is absolute as well. The result is a relative
point if and only if both points are relative.
point by distance direction
This command is a more convenient, or at least shorter, form of
[$point + [by $distance $direction]]
point1 | point2
IMAGE: figure-31-point-projection
This command calculates the projection of two points, i.e. the
result is the point having the x-coordinate of point1 and the y-
coordinate of point2.
n between poin1 point2
IMAGE: figure-29-point-interpolation-1
This command computes the point which is n*100 percent of the
way between point1 and point2, and returns it as its result.
This means that for
n == 0 The result is point1.
n == 1 The result is point2.
n == 0.5
The result is half way between the two points.
etc. Note that it is allowed to use values < 0 and > 1 for n
intersect elem1 elem2
IMAGE: figure-32-point-intersection
This command takes two open elements, computes the lines going
through their "start"- and "end"-corners, and returns the point
where these two lines intersect. The command throws an error if
the lines do not intersect, or are coincident.
element names ?pattern?
This command returns a list containing the names of all corners
for the element. If a pattern is specified then only the names
matching it (via string match are returned. Otherwise all names
are returned (equivalent to a default pattern of *).
element corner
This command returns the value for the corner of the element.
This can be anything, including points and elements.
element corner1 corner2...
This is a convenience shorthand for
[[[$elem $corner1] $corner2] ...]
assuming that the value for
[$elem $corner1]
again an element.
element ?corner1... ?names ?pattern??]?
This is a convenience shorthand for
[[[$elem $corner1] ...] names ?pattern?]
assuming that the value for
[$elem $corner1]
again an element.
nth ?corner?
This command asks the diagram history for the nth element
created, searching from the beginning of the history (counting from 1)
and returns it as its result.
If the corner is specified then the value for this corner is
returned instead.
nth last ?corner?
This command asks the diagram history for the nth element
created, searching from the end of the history and returns it as its
result.
If the corner is specified then the value for this corner is
returned instead.
nth shape ?corner?
This command asks the diagram history for the nth element
created, of the given shape, searching from the beginning of the
history (counting from 1) and returns it as its result.
If the corner is specified then the value for this corner is
returned instead.
nth last shape ?corner?
This command asks the diagram history for the nth element
created, of the given shape, searching from the end of the
history and returns it as its result.
If the corner is specified then the value for this corner is
returned instead.
last ?corner?
last shape ?corner?
Convenience commands mapping to "1st last"
and "1st last shape".
1st
2nd
3rd
Aliases for 1th, 2th, and 3th, for readability,
usable whereever nth can ocur.
VARIABLES
The language context contains a number of predefined variables which
hold the default values for various attributes. These variables, their
uses, and values are:
anchor
The default value for the attribute anchor.
Initialized to center.
The legal values are all those accepted by Tk_GetAnchor
[http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
arcradius
The default value for the attribute radius of arc elements.
Initialized to the pixel equivalent of 1 cm.
arrowhead
The default value for the attribute arrowhead.
Initialized to none.
The legal values are
none, -
Draw no arrowheads, at neither end of the line.
start, first, <-
Draw an arrowhead at the beginning of the line, but not
at its end.
end, last, ->
Draw an arrowhead at the end of the line, but not at its
beginning.
both, <->
Draw arrowheads at both ends of the line.
boxheight
The default value for the attribute height of box, diamond and
ellipse elements.
Initialized to the pixel equivalent of 2 cm.
boxwidth
The default value for the attribute width of box, diamond and
ellipse elements.
Initialized to the pixel equivalent of 2 cm.
clockwise
The default value for the attributes clockwise and counterclock-
wise of arc elements.
Initialized to False, for counter-clockwise direction.
circleradius
The default value for the attribute radius of circle elements,
and also the default for the attribute chop, when specified
without an explicit length.
Initialized to the pixel equivalent of 1 cm.
drumaspect
The default value for the attribute aspect of drum elements.
Initialized to 0.35.
fillcolor
The default value for the attribute fillcolor of all elements
which can be filled.
Initialized to the empty string, signaling that the element is
not filled.
justify
The default value for the attribute justify.
Initialized to left.
The legal values are left, right, and center.
linecolor
The default value for the attribute color of all elements having
to draw lines (all but text).
Initialized to black.
linestyle
The default value for the attribute style of all elements having
to draw some line.
Initialized to solid.
The legal values are all those accepted by Tk_GetDash
[http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
solid, empty string
Draw solid line.
dash, dashed, -
Draw a dashed line.
dot, dotted, .
Draw a dotted line.
dash-dot, -.
Draw a dash-dotted line
dash-dot-dot, -..
Draw a dash-dot-dotted line.
linewidth
The default value for the attribute stroke of all elements hav-
ing to draw some line.
Initialized to 1 (pixels).
movelength
The default value for the directional specification of interme-
diate locations by the attribute then of line and move elements.
Initialized to the pixel equivalent of 2 cm.
slant
The default value for the attribute slant of box elements.
Initialized to 90 degrees, i.e. slant straight up.
textcolor
The default value for the attribute textcolor of all elements
having to draw some text.
Initialized to black.
textfont
The default value for the attribute textfont of all elements
having to draw some text.
Initialized to Helvetica 12pt.
DIAGRAM CLASSES The intended audience of this section are developers wishing
to work
on the internals of the diagram package.
Regular users of diagram can skip this section without missing any-
thing.
The main information seen here is the figure below, showing the hierar-
chy of the classes implementing diagram.
IMAGE: figure-00-dependencies
At the bottom, all at the same level are the supporting packages like
snit, etc. These can all be found in Tcllib.
Above them is the set of diagram classes implementing the various
aspects of the system, i.e.:
diagram
The main class, that which is seen by the user.
diagram::core
The core engine, itself distributed over four helper classes.
diagram::basic
The implementation of the standard shapes, like box, circle,
etc., based on the extension features of the core.
diagram::element
Core support class, the database of created elements. It also
keeps the history, i.e. the order in which elements were cre-
ated.
diagram::attribute
Core support class, the generic handling of definition and pro-
cessing of attributes.
diagram::direction
Core support class, the database of named directions.
diagram::navigation
Core support class, the state of layout engine, i.e. current
position and directin, and operations on it.
diagram::point
General support class handling various vector operations.
REFERENCES
KEYWORDS
2D geometry, arc, arrow, box, canvas, circle, diagram, diamond, draw-
ing, drum, ellipse, image, interpolation, intersection, line, move,
picture, plane geometry, plotting, point, raster image, spline, text,
vector
CATEGORY
Documentation tools
diagrams 0.3 diagram(n)
Mac OS X 10.8 - Generated Thu Sep 6 05:54:16 CDT 2012