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.

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 See the method new attribute for more information on attribute definitions.

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

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:

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:

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.

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

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

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

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

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

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

line attr...

-- attr...

IMAGE: figure-02-line An open element with the corresponding corners, i.e. "start", "end", and "center". It handles the attributes

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

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.

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

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:

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

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

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

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

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:

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.