diagram(3tk)

📦

version 0.9 · 2 versions

0.9 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
0.8~20230222 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 diagram(3tk) — Documentation toolbox 🦋

okay so bestie, welcome to the diagram manual page, but make it cute. This is part 1, and there are more parts coming, so don't go anywhere. 💖

🎀 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, bestie! It's a package for the easy construction of diagrams (sic), i.e. 2D vector graphics, sometimes also called pictures. 💅

Not me being a whole layer on top of Tk's canvas... but no cap, this package is not a replacement for Tk's canvas. It's 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. Iconic behavior, honestly. ✨

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

::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 diagram's 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:

The list of canvas items the drawn element consists of.
The dictionary of named locations in the element, its corners.
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.
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 signature.

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 is the dictionary of attributes and values collected so far 🫶

The result of the command is the new dictionary of attributes. Slay.

aggregate — this key is a boolean flag, and it only does anything if and only if the key merge was not specified. It's optional, and if you don't specify it, it defaults to False ✨

If the key is effective, then False means the attribute's value gets set into the dictionary using the value of key key (see above 👆) as its index — overwriting anything that was specified before. Rip to the old value 💀

If the key is effective, then True means the attribute's value gets added to the dictionary using the value of key key (again, see above) as its index, extending any previously specified value. Which means the final value of the attribute, as seen after processing, will be a list of all the collected values. It's giving collector energy 🌈

default — the value of this key is a command prefix that gets invoked after collection of attributes has been completed and this attribute is in the list of required attributes for the drawing element (peep the 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. Important distinction bestie, don't skip it.

Further note: this command prefix is invoked even if a user specified attribute value is present. That's on purpose — it lets the command go beyond just setting defaults, it can calculate and store derived values too. Iconic, honestly 👑

This key is optional. If an element requires this attribute but default is not specified, then nothing will be done. Nothing. Nada. Moving on 💅

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 the current 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 the key default is not specified. In that case it supplies a default handling for default, linking the attribute to a variable in the language context. Mutual besties, basically 🫂

The value for this key is a 2-element list containing the name of the variable to link to, and its initial value — in that order. Order matters, don't freestyle it.

🦋 `diagramObject unknown attribute cmdprefix`

This method registers the command prefix with the subsystem that processes the attributes for element commands, telling it to call it when it encounters an attribute it's unable to handle on its own. Like "hey bestie, I literally can't, you take this one" 😭

You're allowed to register more than one 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 — and the first entry is the name of the attribute which could not be processed 👀

The result of the command has to be a boolean value, where True signals that this callback has accepted the attribute, processed it, and that the new state of the wordqueue is where the general processing shall continue. No cap.

Given the signature, the command has basically two ways of handling (rewriting) the attributes it recognizes:

Replace the attribute (and arguments) with a different attribute and arguments.
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 the 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. Yes this is a whole security thing, do not play with it 🔥

✨ 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 you can use 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. Double corners, double the fun, I don't make the rules 💅

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 one is used 😭 For combined directions you have to use the main attribute command, anchor.
- 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. Yes, that's the same fallback as the clockwise one. That's just how it is, bestie 🙈
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". Empty string = no vibe inside 🌫️
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. So specific, love that for it 💖
stroke width — IMAGE: figure-20-style-stroke Specifies the width of the lines drawn for 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, - — draws a dashed line.
- dot, dotted, . — draws a dotted line.
- dash-dot, -. — draws a dash-dotted line.
- dash-dot-dot, -.. — draws a dash-dot-dotted line.

bestie, quick note: 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 the argument. slay.

text string — the text you wanna stick on the element. defaults to nothing (crickets). when you specify it multiple times, what actually shows up is the concatenation of the individual strings, stacked vertically, and the first string you specified is the topmost element. top-to-bottom vibes, fr fr.
textcolor spec — the color used to draw the text of an element with. ignored if there's no text (like, why would it matter). if you don't specify it, the system falls back to the value from the language variable textcolor, which itself defaults to black.
textfont spec — the font used to draw the text of an element with. ignored if there's no text. if not specified, the system falls back to the language variable textfont, which itself defaults to Helvetica 12pt.
to 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...

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 — plus center. the main effect here is the aggregation of all the elements created by the script into one single element. which 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's 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, which lets users define their own named locations in the block. cute, right?

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, propagating 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 these 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 one is used. for combined directions you gotta use the main attribute command, anchor.
- ljust — that's anchor west
- rjust — that's anchor east
- above — that's anchor south
- below — that's anchor north
at location — specifies the location of the element's corner named by the attribute with. defaults to the current location as maintained by the layouting system.
color spec — IMAGE: figure-21-style-colors specifies the color used to draw the lines of the element. if not specified, the system falls back to the value taken from the language variable linecolor, which itself defaults to black.
fillcolor spec — IMAGE: figure-21-style-colors specifies the color used to draw the inside of the element. if not specified, the system falls back to the value taken from the language variable fillcolor, which itself defaults to the empty string, signaling "no filling". so like, hollow, mysterious, iconic.
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.
justify left|center|right — specifies how multi-line text associated with the element is positioned within its box. the value is ignored if no text was specified for the element. if not specified, the system falls back to the value taken from the language variable justify, which itself defaults to left. the legal values are left, right, and center.
slant angle — specifies the angle by which the box element is slanted, in degrees. if not specified, the system falls back to the value taken from the language variable slant, which itself defaults to 90, i.e. vertical, no slant. 0 degrees is slanting straight east, pointing to the right. 90 degrees is slanting to the north, pointing straight up.
stroke width — IMAGE: figure-20-style-stroke specifies the width of the lines drawn for the 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 of these listed below:
- solid, empty string — draw a 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.

also: 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. periodt.

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.
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 these 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 one is used. for combined directions the main attribute command, anchor, has to be used.
- ljust — that's anchor west
- rjust — that's anchor east
above — shorthand for "anchor south", that's it, that's the whole vibe 💅
- below — and this one is "anchor north", no cap ✨

at location — says where to put the corner of the element that the with attribute names. Don't specify it? It defaults to whatever the current location is, as the layouting system keeps track of it. 💖
color spec — (IMAGE: figure-21-style-colors) the color used to draw the element's lines. If you don't specify it, the system falls back to the value from the language variable linecolor, which itself defaults to black. 🖤
diameter length
diam length — the diameter of the circle element, which is a whole alternate 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 info has precedence. This attribute has no default, because the defaults are taken from the radius. 🎀
fillcolor spec — (IMAGE: figure-21-style-colors) the color used to draw the inside of the element. Not specified? Then the system falls back to the language variable fillcolor, which itself defaults to the empty string — which signals "no filling". 🫙
justify left|center|right — how multi-line text associated with the element is positioned within its box. This value is ignored if no text was specified for the element. If you don't specify it, the system falls back to the language variable justify, which itself defaults to left. Legal values are left, right, and center. 📐
radius length
rad length — the radius of the circle element. If not specified, the system falls back to the language variable circleradius, which itself defaults to the pixel equivalent of 1 cm. 🌸
stroke width — (IMAGE: figure-20-style-stroke) the width of the lines drawn for the element, in pixels. If not specified, the system falls back to the language variable linewidth, which itself defaults to 1. 🖊️
style spec — (IMAGE: figure-18-style-dash) the style used to draw the element's lines. If not specified, the system falls back to the language variable linestyle, which itself defaults to solid lines. The legal values are all of the ones accepted by Tk_GetDash [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], plus every one listed below, bestie:
- solid, empty string — draws a solid line.
- dash, dashed, - — draws a dashed line.
- dot, dotted, . — draws a dotted line.
- dash-dot, -. — draws a dash-dotted line.
- dash-dot-dot, -.. — draws 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 — the text to associate with the element. Defaults to nothing. When you specify it multiple times, the text actually shown is the concatenation of the individual strings, vertically stacked, with the first string specified being the topmost element. 📚
textcolor spec — the color used to draw the text of an element. Ignored if there is no text. If not specified, the system falls back to the language variable textcolor, which itself defaults to black. 🖤
textfont spec — the font used to draw the text of an element. Ignored if there is no text. If not specified, the system falls back to the language variable textfont, which itself defaults to Helvetica 12pt. ✍️
with corner — the corner of the element to place at the location given by the at attribute. Defaults to the current corner as maintained by the layouting system — except if the value for at was specified by the user. In that case it defaults to center. 📍

diamond attr...
<> attr... — (IMAGE: figure-02-diamond) a closed element with the corresponding corners, i.e. the eight directions of the compass rose, plus "center". It handles these attributes, babes 👇
- 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 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 one is used. For combined directions, the main attribute command anchor has to be used. 🧭
  - ljust — "anchor west"
  - rjust — "anchor east"
  - above — "anchor south"
  - below — "anchor north"
- aspect number — the aspect ratio, i.e. the ratio of width to height, of the diamond element. The manner in which a default is calculated when it's not specified also depends on the specifications of the attributes width and height, if any. Here's the tea:
  - If both width and height are specified, then any specification of aspect is ignored, since it's implicitly defined in the width and height as well, and that takes precedence. A missing specification is ignored in that case as 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 itself defaults to 2.
  - If none 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 itself 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 — the location of the element's corner named by the attribute with. Defaults to the current location as maintained by the layouting system. 📍
- color spec — (IMAGE: figure-21-style-colors) the color used to draw the element's lines. If not specified, the system falls back to the value taken from the language variable linecolor, which itself defaults to black. 🖤
- fillcolor spec — (IMAGE: figure-21-style-colors) the color used to draw the inside of the element. If not specified, the system falls back to the value taken from the language variable fillcolor, which itself defaults to the empty string, signaling "no filling". 🫙
- height length — the height of the diamond element. The manner in which a default is calculated when it's not specified also depends on the specifications of the attributes aspect and width, if any. Same energy as aspect, so let's run it back:
  - If both width and height are specified, then any specification of aspect is ignored, since it's implicitly defined in the width and height as well, and that takes precedence. A missing specification is ignored in that case as 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 itself defaults to 2.
  - If none 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 itself defaults to the pixel equivalent of 2 cm. For the aspect it uses either the user-specified value or the default taken as described in the previous paragraph. 📏
- justify left|center|right — how multi-line text associated with the element is positioned within its box. The value is ignored if no text was specified for the element. If not specified, the system falls back to the value taken from the language variable justify, which itself defaults to left. The legal values are left, right, and center. 📐
stroke width — how thick are the lines of this element, in pixels? ✨ (pic: IMAGE: figure-20-style-stroke). Leave it out and the system falls back to the language variable linewidth, which itself defaults to 1.
style spec — the style the element's lines get drawn in 🎀 (pic: IMAGE: figure-18-style-dash). Leave it out and it falls back to the language variable linestyle, which defaults to solid lines. Legal values = everything Tk_GetDash accepts at http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm, plus all of these:
- 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.

Also, heads up: 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 — the text you want associated with the element. Defaults to nothing. Specify it multiple times and what actually shows is the concatenation of all the individual strings, stacked vertically, with the first string you specified sitting on top. 🫶
textcolor spec — the color the element's text gets drawn in. Ignored if there's no text. Leave it out and it falls back to the language variable textcolor, which defaults to black.
textfont spec — the font the element's text gets drawn in. Ignored if there's no text. Leave it out and it falls back to the language variable textfont, which defaults to Helvetica 12pt.
width length — the width of the diamond element. How the default gets calculated when you don't specify it also depends on the attributes aspect and height, if any. Here's the whole tea:
- If both width and height are specified, then any aspect specification is ignored, since it's implicitly defined by width and height anyway, and those take precedence. A missing specification is ignored in that case too — no defaults required, periodt.
- If aspect is specified along with one of width or height, the missing attribute is calculated from the two that are specified. No defaults required here either.
- If only one of width or height is specified, the system uses a fallback for the aspect: the value from the language variable diamondaspect, which defaults to 2.
- If none of width or height is specified, the system uses a fallback for the width: the value from the language variable boxwidth, which defaults to the pixel equivalent of 2 cm. For the aspect it uses either your value or the default described in the paragraph above.
with corner — which corner of the element gets placed 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.

🥁 `drum attr...`

A closed element with the corresponding corners, aka the eight directions of the compass rose plus "center". 🌈 (pic: IMAGE: figure-02-drum) It handles the attributes:

anchor name
ljust
rjust
above
below — 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. 🎯 (pic: IMAGE: figure-22-text-anchoring-3). 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 at 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 one is used. For combined directions you have to use the main attribute command, anchor. 💅
- ljust — "anchor west"
- rjust — "anchor east"
- above — "anchor south"
- below — "anchor north"
aspect number — the aspect ratio, i.e. ratio of width to height, of the ellipses 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 — the location of the element's corner named by the attribute with. Defaults to the current location as maintained by the layouting system.
color spec — the color used to draw the lines of the element 🎨 (pic: IMAGE: figure-21-style-colors). If not specified the system falls back to the value taken from the language variable linecolor, which itself defaults to black.
fillcolor spec — the color used to draw the inside of the element 💖 (pic: IMAGE: figure-21-style-colors). If not specified the system falls back to the value taken from the language variable fillcolor, which itself defaults to the empty string, signaling "no filling".
height length
ht length — 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.
justify left|center|right — how multi-line text associated with the element is positioned within its box. Ignored if no text was specified for the element. If not specified the system falls back to the value taken from the language variable justify, which itself defaults to left. The legal values are left, right, and center.
stroke width — the width of the lines drawn for the element, in pixels ✨ (pic: IMAGE: figure-20-style-stroke). If not specified the system falls back to the value taken from the language variable linewidth, which itself defaults to 1.
style spec — the style used to draw the lines of the element 🎀 (pic: IMAGE: figure-18-style-dash). 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 at http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm, plus all of these:
- 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.

And 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 — 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 — 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 — the font used to draw the text of an element with. Ignored if there is no text. If not specified the system falls back to the value taken from the language variable textfont, which itself defaults to Helvetica 12pt.
width length
wid length — 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 — 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.

🥚 `ellipse attr...`

A closed element with the corresponding corners — yep, the eight directions of the compass rose, and "center". 🌸 (pic: IMAGE: figure-02-ellipse) It handles the attributes:

anchor name
ljust
rjust — shorthand for "anchor east" 💅
above — shorthand for "anchor south" ⬆️
below — shorthand for "anchor north" ⬇️

(📸 IMAGE: figure-22-text-anchoring-3)

okay so let's talk about what anchor actually means, bestie. It sets the anchor of the text that's gonna sit at the element's center, and you do it by name. Which is a fancy way of saying: it decides where the text sits relative to that center point. If you didn't give the element any text, this value gets ignored — like, nothing to anchor, girl. If you don't specify it, the system falls back to the value from the language variable anchor, and that itself defaults to center. The legal values are all the ones Tk_GetAnchor accepts: http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm

And the no-argument commands up there are all just shorthands with the anchor baked in. But read this part carefully: they do not combine — only the last one you say counts. If you want a combined direction, you gotta use the main attribute command, anchor, directly. iykyk 💖

`at` location

Sets the location of the element's corner named by the with attribute. If you don't say anything, it defaults to whatever the current location is — the layouting system keeps track of that for you. 🎀

`color` spec

(📸 IMAGE: figure-21-style-colors)

The color used to draw the lines of the element. Not specified? The system falls back to the language variable linecolor, which itself defaults to black. 🖤

`fillcolor` spec

(📸 IMAGE: figure-21-style-colors)

The color used to draw the inside of the element. Not specified? Falls back to the language variable fillcolor, which itself defaults to the empty string — and that's the signal for "no filling". So like, hollow. Iconic. 💜

`height` length

`ht` length

The height of the element. Not specified? Falls back to the language variable boxheight, which itself defaults to the pixel equivalent of 2 cm. 📏

`justify` `left|center|right`

How multi-line text that's attached to the element gets positioned inside its box. Ignored if the element has no text — like, no text, nothing to justify, periodt. Not specified? Falls back to the language variable justify, which itself defaults to left. The legal values are left, right, and center. ✨

`stroke` width

(📸 IMAGE: figure-20-style-stroke)

The width of the lines drawn for the element, in pixels. Not specified? Falls back to the language variable linewidth, which itself defaults to 1. 🖊️

`style` spec

(📸 IMAGE: figure-18-style-dash)

The style used to draw the lines of the element. Not specified? Falls back to the language variable linestyle, which itself defaults to solid lines. The legal values are everything Tk_GetDash accepts: http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm — plus all the extras listed right here:

solid, empty string — draws a solid line. ➖
dash, dashed, - — draws a dashed line. 💫
dot, dotted, . — draws a dotted line. 🍓
dash-dot, -. — draws a dash-dotted line. 🌈
dash-dot-dot, -.. — draws a dash-dot-dotted line. 🦋

Also note: 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 the argument. Slay. 💅

`text` string

The text you wanna associate with the element. Defaults to nothing. And here's the fun part — when you specify it multiple times, the text that actually shows up is the concatenation of all the individual strings, stacked vertically, with the first string you specified being the topmost element. Stack 'em up bestie. 🥞

`textcolor` spec

The color used to draw the element's text. Ignored if there's no text. Not specified? Falls back to the language variable textcolor, which itself defaults to black. 🖤

`textfont` spec

The font used to draw the element's text. Ignored if there's no text. Not specified? Falls back to the language variable textfont, which itself defaults to Helvetica 12pt. 🔤

`width` length

`wid` length

The width of the element. Not specified? Falls back to the language variable boxwidth, which itself defaults to the pixel equivalent of 2 cm. 📐

`with` corner

Which corner of the element gets placed at the location given by the at attribute. Defaults to the current corner as maintained by the layouting system — except if you specified a value for at yourself. In that case it defaults to center. 🎯

`line attr...`

`-- attr...`

(📸 IMAGE: figure-02-line)

It's an open element with the matching corners, i.e. "start", "end", and "center". (And yeah, -- is just the other way to write it.) It handles these attributes:

`anchor` name

`ljust`

`rjust`

`above`

`below`

(📸 IMAGE: figure-22-text-anchoring-3)

Sets the anchor of the text that's to be placed at the element's center, by name. Translation: 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 you don't specify it, the system falls back to the value from the language variable anchor, which itself defaults to center. Legal values are all the ones Tk_GetAnchor accepts: 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 one is used. For combined 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)

Where to draw arrowheads on the line element: at the beginning or end, at both ends, or none at all. Not specified? Falls back to the language variable arrowhead, which itself defaults to none. Legal values:

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

And note: the values "start", "end", "-", "->", "<-", and "<->" are all accepted as shorthands for the arrowhead command using them as the argument. 🏹

`at` location

Line elements are normally positioned absolutely, using the locations specified through the attributes from, then, and to. But if at is specified, then those positions get translated one last time — moving the line's corner named by the with attribute to the location given by this attribute. 🎀

`chop` ?length?

The length of the line element to remove from the beginning and/or end. Defaults to nothing. If you specify it once, the chopping applies to both beginning and end of the line. If you specify it twice or more, the last two specifications are used, and they get applied to the beginning and end of the line, in that order. Whenever the attribute is specified without an explicit length, the system falls back to the value from the language variable circleradius, which itself defaults to the pixel equivalent of 1 cm ✂️

`color` spec

(📸 IMAGE: figure-21-style-colors)

The color used to draw the lines of the element. Not specified? Falls back to the language variable linecolor, which itself defaults to black. 🖤

`fillcolor` spec

(📸 IMAGE: figure-21-style-colors)

The color used to draw the inside of the element. Not specified? Falls back to the language variable fillcolor, which itself defaults to the empty string, signaling "no filling". 💜

`from` location

Where the line element begins. Defaults to the current location as maintained by the layouting system. 🚩

`justify` `left|center|right`

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. Not specified? Falls back to the language variable justify, which itself defaults to left. Legal values are left, right, and center. ✨

`noturn`

Says that the direction of the line element at its end is not propagated to the layout management. If it's not specified, the direction of the line becomes the new direction the layout. 🌪️

smooth — bestie this one turns ON bezier splines for the line element 💅 skip it and the lines get drawn exactly through the waypoints you specified, zero smooth curves, no cap.
stroke width — IMAGE: figure-20-style-stroke — how wide (in pixels) the lines drawn for the element are. Don't specify it and the system falls back to whatever linewidth says, and linewidth itself defaults to 1.
style spec — IMAGE: figure-18-style-dash — the style used to draw the element's lines. Not specified? Then it falls back to the language variable linestyle, which itself defaults to solid lines. Legal values are everything Tk_GetDash accepts (http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm), plus all of these:
- solid, empty string — draw a 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.

Heads up bestie: solid, dot(ted), dash(ed), dash-dot, and dash-dot-dot are all accepted as shorthands for the style command when you pass them as an argument. 🎀

text string — the text to associate with the element. Defaults to nothing at all 🙈. When you specify it multiple times, the text that actually shows up is the concatenation of the individual strings, vertically stacked, with the first string you specified being the topmost element.
textcolor spec — the color used to draw an element's text with. Ignored if there's no text. Not specified? Falls back to the language variable textcolor, which itself defaults to black.
textfont spec — the font used to draw an element's text with. Ignored if there's no text. Not specified? Falls back to 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. You can specify it multiple times, and each use adds one more location to the series the line will go through. These locations get traversed in the order you specified them, fr fr.

The location can be given explicitly, or as a series of directions with distances. In that second case, the names of all known directions are accepted for the direction part. If you don't give a distance 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 get added up to give 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. Using noturn is not able to override this behaviour. 💀

And lastly, the names of the registered directions also serve as attribute commands, with an implicit attribute then in front of them. iykyk.

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 where the line element ends. This attribute has no default. The default is handled by the attribute then, which makes it look like to has a default when you don't specify it.
with corner — line elements are normally positioned absolutely, using the locations specified through the attributes from, then, and to. But if at is specified, then those positions get translated one last time, moving the line's corner named by the attribute with to the location given by this attribute. Which means with is effective if and only if the attribute at was specified for the line as well. 👑

🫥 `move attr`

An open element with the corresponding corners, i.e. "start", "end", and "center". A move element is basically an invisible line. The main effect we care about is the change it makes to the layout system, but it's a real element — same corners as an ordinary line, and it shows up in the history too, so future references can point at all the places it touched. It handles the same attributes as line elements.

🌊 `spline attr...`

IMAGE: figure-02-spline — an alias for the line element (see above), with the attribute smooth preset. Obsessed. ✨

📝 `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 these 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. So like, 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. Not specified? Falls back to the language variable anchor, which itself defaults to center. The legal values are all those Tk_GetAnchor accepts (http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm). The commands with no arguments are all shorthands with the anchor implied. Note that they do not combine — only the last one is used. For combined directions you have to use the main attribute command, anchor.
- 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 — the height of the text element. Defaults to the natural height of its text.
justify left|center|right — 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. Not specified? Falls back to the language variable justify, which itself defaults to left. Legal values: left, right, and center.
text string — the text to associate with the element. Defaults to nothing. When specified multiple times, the text that actually shows up is the concatenation of the individual strings, vertically stacked, with the first string specified being the topmost element.
textcolor spec — the color used to draw an element's text with. Ignored if there is no text. Not specified? Falls back to the language variable textcolor, which itself defaults to black.
textfont spec — the font used to draw an element's text with. Ignored if there is no text. Not specified? Falls back to the language variable textfont, which itself defaults to Helvetica 12pt.
width length — the width of the text element. Defaults to the natural width of its text.
with corner — 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.

🌈 ATTRIBUTES ✨

The set of all attributes supported by all the element commands is shown below. And yeah, we call them commands and give you a syntax, but they're not truly available as actual commands — they only exist as part of the arguments for an element command. 🤫

Note that some of the attribute names are overloaded, i.e. they have multiple, different definitions. When attributes are being processed for an element, the actual definition used is chosen based on the type of the element the processing is for.

And 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 tells the system which anchor point of the text gets parked at the element's center — like, by name. Basically: this is where the text sits relative to the center of the element. If the element has no text, this whole thing gets ignored, no cap. And if you don't set it? It falls back to the value of the language variable anchor, which itself defaults to center. The legal values are literally all the ones Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm] accepts. The argument-less commands below are all just shorthands with the anchor baked in — and bestie, they do not stack. Only the last one you use counts. Want to combine directions? You gotta use the main attribute command anchor for that. Periodt.
- ljust — same as "anchor west"
- rjust — same as "anchor east"
- above — same as "anchor south"
- below — same as "anchor north"
arrowhead spec — IMAGE: figure-19-style-arrowheads says where arrowheads go on the line element: at the start, the end, both ends, or nowhere at all. If you don't specify, it falls back to the language variable arrowhead, which itself defaults to none. The legal values are:
- none, - — draw no arrowheads, neither end. Nothing. Silence. 💀
- start, first, <- — arrowhead at the beginning of the line only, not the end.
- end, last, -> — arrowhead at the end of the line only, not the beginning.
- both, <-> — arrowheads at both ends. Main character energy at every edge. ✨

And note: the values "start", "end", "-", "->", "<-", and "<->" are all accepted as shorthands for the arrowhead command, just passed in as its argument.

aspect number — sets the aspect ratio (that's width-to-height, btw) of the diamond element. How a default gets worked out when you don't specify one also depends on whether you set width and height. Here's the tea:
- If both width and height are specified, then any aspect you set is ignored — it's already implied by width and height, and that takes precedence. A missing spec is also just ignored in that case, so no defaults needed at all.
- If aspect is specified and one of width or height is too, the missing one gets calculated from the two you did give. Again, no defaults required for this case.
- If only one of width or height is specified, the system uses a fallback for aspect: the value of the language variable diamondaspect, which itself defaults to 2.
- If neither width nor height is specified, the system uses a fallback for the width — the language variable boxwidth, which itself defaults to the pixel equivalent of 2 cm. For the aspect it uses either your value or the default described in the previous paragraph.
aspect number — this one sets the aspect ratio (width to height again) of the ellipses used to draw the top and bottom of the drum element. If you don't specify it, the system falls back to the language variable drumaspect, which itself defaults to 0.35.
at location — sets the location of the element's corner named by the with attribute. Defaults to the current location as maintained by the layouting system.
at location — okay so line elements are normally positioned absolutely, using the locations given through the from, then, and to attributes. But if at is specified, those positions get translated one last time, moving the line's corner named by with to the location given by this attribute. Sneaky little final nudge. 🦋
chop ?length? — sets how much length of the line element to remove from the beginning and/or end. Defaults to nothing. Specify it once and the chopping applies to both beginning and end. Specify it twice or more and the last two specifications are used — applied to beginning and end, in that order. Whenever you use the attribute without an explicit length, the system falls back to the language variable circleradius, which itself defaults to the pixel equivalent of 1 cm.
clockwise, cw — sets the direction of the arc element, here going clockwise. The complementary attribute is counterclockwise. If not specified, the system falls back to the language variable clockwise, which itself defaults to false — meaning counter-clockwise direction.
color spec — IMAGE: figure-21-style-colors sets the color used to draw the lines of the element. If not specified, the system falls back to the language variable linecolor, which itself defaults to black. Classic. Iconic. 🖤
counterclockwise, ccw — sets the direction of the arc element, here going counter-clockwise. The complementary attribute is clockwise. If not specified, the system falls back to the language variable clockwise, which itself defaults to false, for counter-clockwise direction.
diameter length, diam length — sets the diameter of the circle element, as an alternate way to give its radius. It's effective if and only if the radius wasn't specified — so if both diameter and radius are set, the radius info wins, periodt. This attribute has no default, because the defaults are taken from radius.
fillcolor spec — IMAGE: figure-21-style-colors sets the color used to draw the inside of the element. If not specified, the system falls back to the language variable fillcolor, which itself defaults to the empty string — that's the signal for "no filling". Empty string = stay hollow, bestie. 🫶
from location — sets the location where the line element begins. Defaults to the current location as maintained by the layouting system.
from location — sets the location where the arc element begins. Defaults to the current location as maintained by the layouting system.
height length, ht length — sets the height of the element. If not specified, the system falls back to the language variable boxheight, which itself defaults to the pixel equivalent of 2 cm.
height length — sets the height of the diamond element. How a default gets calculated when you skip it also depends on whether you set aspect and width. So, buckle up:
- If both width and height are specified, any aspect you set is ignored — it's implicitly defined by width and height, and that takes precedence. A missing spec is ignored in that case too, so no defaults needed.
- If aspect is specified and one of width or height is, the missing attribute is calculated from the two that are specified. No defaults required here either.
- If only one of width or height is specified, the system uses a fallback for aspect: the language variable diamondaspect, which itself defaults to 2.
- If neither width nor height is specified, the system uses a fallback for the width — the language variable boxwidth, which itself defaults to the pixel equivalent of 2 cm. For the aspect it uses either your value or the default from the previous paragraph.
height length — sets the height of the text element. Defaults to the natural height of its text. It just knows its own size, okay? 💅
justify left|center|right — sets how multi-line text attached to the element is positioned inside its box. Ignored entirely if there's no text on the element. If not specified, the system falls back to the language variable justify, which itself defaults to left. Legal values are left, right, and center.
noturn — says that the direction of the line element at its end is not propagated to the layout management. If not specified, the direction of the line becomes the new direction of the layout.
radius length, rad length — sets the radius of the circle element. If not specified, the system falls back to the language variable circleradius, which itself defaults to the pixel equivalent of 1 cm.
radius length — sets the radius of the arc element — or rather, the radius of the circle that the shown arc is a piece of. If not specified, the system falls back to the language variable arcradius, which itself defaults to the pixel equivalent of 1 cm.
slant angle — sets the angle by which the box element is slanted, in degrees. If not specified, the system falls back to the language variable slant, which itself defaults to 90 — that's vertical, no slant. 0 degrees slants straight east, pointing right. 90 degrees slants north, pointing straight up. 📐
smooth — turns on bezier splines for the line element. If not specified, lines get drawn exactly through the specified waypoints, no smooth curves anywhere.
stroke width — IMAGE: figure-20-style-stroke sets the width of the lines drawn for the element, in pixels. If not specified, the system falls back to the language variable linewidth, which itself defaults to 1.
style spec — IMAGE: figure-18-style-dash sets the style used to draw the lines of the element. If not specified, the system falls back to the language variable linestyle, which itself defaults to solid lines. The legal values are all the ones accepted by Tk_GetDash [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], plus everything listed below:
solid, empty string — Draws a solid line. Periodt. 💅
dash, dashed, - — Draws a dashed line.
dot, dotted, . — Draws a dotted line.
dash-dot, -. — Draws a dash-dotted line.
dash-dot-dot, -.. — Draws 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. ✨ No cap.

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 locations 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 override 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 as 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 itself defaults to 2. 🔢

If none 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 itself 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 of. ⭕
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 degrees, 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

okay so this command computes the point that's n*100 percent of the way between point1 and point2, and hands it back to you as its result. Which means, for real:

n == 0 — the result is point1. That's it, that's the whole point. 💅
n == 1 — the result is point2.
n == 0.5 — the result is half way between the two points. dead center, main character position ✨
etc. — and bestie, note that it's totally allowed to use values < 0 and > 1 for n. no gatekeeping here.

intersect elem1 elem2 — this one takes two open elements, computes the lines going through their "start"- and "end"-corners, and returns the point where those two lines intersect. the command throws an error if the lines do not intersect, or are coincident — so no parallel-line nonsense, it will absolutely call you out. 😭

IMAGE: figure-32-point-intersection

element names ?pattern? — returns a list with the names of all corners for the element. If a pattern is specified then only the names matching it (via string match) come back. Otherwise all names come back (which is the same as a default pattern of *). so basically: ask for everything or ask for your faves 🎀
element corner — returns the value for the corner of the element. And that value can be anything, including points and elements. it's giving chaotic range, love that for it 💜
element corner1 corner2... — a convenience shorthand for

[[[$elem $corner1] $corner2] ...]

assuming that the value for

[$elem $corner1]

is again an element.

element ?corner1... ?names ?pattern??]? — a convenience shorthand for

[[[$elem $corner1] ...] names ?pattern?]

assuming that the value for

[$elem $corner1]

is again an element.

nth ?corner? — this asks the diagram history for the *n*th 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. counting from one, like a civilized little index 🦋
nth last ?corner? — same idea, but it asks the diagram history for the *n*th 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? — asks the diagram history for the *n*th 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. filtering by shape, we love a specific queen 💅
nth last shape ?corner? — asks the diagram history for the *n*th 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". because typing less is self care, fr fr 🌸
1st
2nd
3rd — aliases for 1th, 2th, and 3th, for readability, usable wherever nth can occur. iconic naming choices, no notes 👑

💖 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. (that's you, bestie — you can scroll, no shame 🫶)

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. the face of the operation 💅
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 direction, and operations on it.
diagram::point — general support class handling various vector operations.

🦋 REFERENCES 🦋

this heading is just vibing here with absolutely nothing under it in the original. no references listed, no cap. moving on 💜

💀 BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. yes, they said it themselves, bestie — the bugs are canon. Please report such in the category diagram of the Tklib Trackers (http://core.tcl.tk/tklib/reportlist). Please also report any ideas for enhancements you may have for either package and/or documentation. they want your ideas, they're literally asking 🙈

✨ 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

🎀 CATEGORY 🎀

Documentation tools

and that's the whole page, bestie!! this one came from tklib version 0.3, and you were reading the diagram(3tk) page — go draw something iconic with it 🌸💖✨🦋👑

📦 where this page comes from

debian trixie: tklib 0.9-1
ubuntu questing: tklib 0.9-1
ubuntu resolute: tklib 0.9-1build1
ubuntu stonking: tklib 0.9-1build1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

diagram(3tk)

🦋 diagram(3tk) — Documentation toolbox 🦋

🎀 NAME 🎀

✨ SYNOPSIS ✨

🌸 DESCRIPTION 🌸

🌈 API 🌈

👑 CLASS API 👑

💖 OBJECT API 💖

🦋 diagramObject unknown attribute cmdprefix

🎀 diagramObject draw script

✨ LANGUAGE REFERENCE ✨

🌸 ELEMENTS

🦋 arc attr...

arrow attr...

--> attr...

<--> attr...

<--> attr...

block script attr...

box attr...

circle attr...

O attr...

🥁 drum attr...

🥚 ellipse attr...

at location

color spec

fillcolor spec

height length

ht length

justify left|center|right

stroke width

style spec

text string

textcolor spec

textfont spec

width length

wid length

with corner

line attr...

-- attr...

anchor name

ljust

rjust

above

below

arrowhead spec

at location

chop ?length?

color spec

fillcolor spec

from location

justify left|center|right

noturn

🫥 move attr

🌊 spline attr...

📝 text attr...

🌈 ATTRIBUTES ✨

✨ CORNERS ✨

✨ NAMED DIRECTIONS ✨

✨ MISCELLANEOUS COMMANDS ✨

💖 VARIABLES 💖

🌈 DIAGRAM CLASSES 🌈

🦋 REFERENCES 🦋

💀 BUGS, IDEAS, FEEDBACK 💀

✨ KEYWORDS ✨

🎀 CATEGORY 🎀

🦋 `diagramObject unknown attribute cmdprefix`

🎀 `diagramObject draw script`

🦋 `arc attr...`

`arrow` attr...

`-->` attr...

`<-->` attr...

`<-->` attr...

`block` script attr...

`box` attr...

`circle` attr...

`O` attr...

🥁 `drum attr...`

🥚 `ellipse attr...`

`at` location

`color` spec

`fillcolor` spec

`height` length

`ht` length

`justify` `left|center|right`

`stroke` width

`style` spec

`text` string

`textcolor` spec

`textfont` spec

`width` length

`wid` length

`with` corner

`line attr...`

`-- attr...`

`anchor` name

`ljust`

`rjust`

`above`

`below`

`arrowhead` spec

`at` location

`chop` ?length?

`color` spec

`fillcolor` spec

`from` location

`justify` `left|center|right`

`noturn`

🫥 `move attr`

🌊 `spline attr...`

📝 `text attr...`