Ubuntu Manpage: diagram - Diagram drawing

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  Tutorial  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 diagram 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 whatever 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 language. I.e. name will
become a new command in the language, and the specified command prefix (cmdprefix)
will be called to perform the actual drawing.

attributes specifies the set of attributes for which data has to be available. I.e.
the system will run the ...-callbacks for these attributes. See the method new
attribute for more information on attribute definitions.

The command prefix is expected to conform to the following signature:

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 consists 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 specified 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 language, 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 processor 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 definitions, 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 transformation 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 validation is done.

The signature of the command prefix is that of snit validation 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 previously 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 varname. 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 processing 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 conforming 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 different 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 execution 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
section Miscellaneous Commands. IMAGE: figure-02-basic-shapes

arc attr...
IMAGE: figure-02-arc An open element with the corresponding corners, 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 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 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"

clockwise

cw Specifies the direction of the arc element, here going clockwise. The
complementary attribute is counterclockwise. 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.

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-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 specified 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 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/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 individual 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 variables set in the script will be exported as corners
of the element, 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

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

ht length
Specifies the height of the element. If not specified the system falls back
to the value taken from the language variable boxheight, which itself
defaults to the pixel equivalent of 2 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.

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.

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 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.

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

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.

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 specified then the radius infomration
has precendence. This attribute has no default, because the defaults are
taken from the radius.

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 variable circleradius, which
itself defaults to the pixel equivalent of 1 cm.

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.

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

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 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 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 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.

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 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 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.

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.

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 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.

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

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 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.

height length

ht length
Specifies the height of the element. If not specified the system falls back
to the value taken from the language variable boxheight, which itself
defaults to the pixel equivalent of 2 cm.

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.

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.

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

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

ht length
Specifies the height of the element. If not specified the system falls back
to the value taken from the language variable boxheight, which itself
defaults to the pixel equivalent of 2 cm.

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.

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.

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

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 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 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 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 variable
circleradius, which itself defaults to the pixel equivalent of 1 cm

from location
Specifies the location where the line element begins. Defaults to the
current location as maintained by the layouting system.

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.

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.

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.

then location

then (<direction> ?length?)...

(<direction> ?length?)...
This attribute specifies an intermediate location the line element 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 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 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.

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

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.

width length
Specifies the width of the text element. Defaults to the natural width of
its text.

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 multiple, 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 processed according to
the definitions below will be treated as the argument 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 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 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 argument.

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 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 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 variable circleradius, which itself defaults to the
pixel equivalent of 1 cm

clockwise

cw Specifies the direction of the arc element, here going clockwise. The
complementary attribute is counterclockwise. 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.

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-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.

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 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".

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 system 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 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 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 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.

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 variable 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 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 specified 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 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/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
individual 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 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 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 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 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 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 natural 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.

• The closed elements define corners for the compass rose, including the "center",
and their "width" and "height".

IMAGE: figure-27-corners-closed

• block elements additionally export all variables which were set during their
definition as corners.

• 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

• 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.

• 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

• The center of arc elements is the center of the circle the arc is part off.

• 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 position 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 element will be attached to the current position, and if this
corner does not exist the nearest actual corner by angle is used.

west

left

south

down

bottom

bot

east

right

north

top

northwest

up-left

upleft

leftup

northeast

up-right

upright

rightup

southwest

down-left

downleft

leftdown

southeast

down-right

downright

rightdown

MISCELLANEOUS COMMANDS
number cm

number mm

number inch

number pt
These commands allow the specification of distances and coordinates in metric and
imperial units, returning the equivalent distance or coordinate in pixels, which is
the unit used internally 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 specifications for the attribute
then of line and move elements. Where we say here

by 50 east

for the attribute we say

... then east 50 ...

or just

... then east ...

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 absolute 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 counterclockwise 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 having to draw some
line. Initialized to 1 (pixels).

movelength
The default value for the directional specification of intermediate 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 anything.

The main information seen here is the figure below, showing the hierarchy 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 created.

diagram::attribute
Core support class, the generic handling of definition and processing 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, drawing, drum, ellipse,
       image, interpolation, intersection, line, move, picture, plane geometry, plotting,  point,
       raster image, spline, text, vector

NAME

SYNOPSIS

DESCRIPTION

API

LANGUAGE REFERENCE

DIAGRAM CLASSES The intended audience of this section are developers wishing to work

REFERENCES

KEYWORDS

CATEGORY