Scroll to navigation

diagram(3tk) Documentation toolbox diagram(3tk) 





NAME


diagram - Diagram drawing






SYNOPSIS


package require Tcl 8.5


package require Tk 8.5


package require diagram 1


::diagram objectName canvas
  ?script?


diagramObject new direction name ?key
    value...?


diagramObject new element name
    attributes cmdprefix


diagramObject new alias name
  cmdprefix


diagramObject new command name
    arguments body


diagramObject new attribute name ?key
    value...?


diagramObject unknown attribute cmdprefix


diagramObject draw script


arc attr...


arrow attr...


--> attr...


<--> attr...


<--> attr...


block script attr...


box attr...


circle attr...


O attr...


diamond attr...


<> attr...


drum attr...


ellipse attr...


line attr...


-- attr...


move attr


spline attr...


text attr...


west


w


left


l


south


s


down


bottom


bot


b


east


e


right


r


north


n


up


top


t


northwest


nw


up-left


upleft


leftup


northeast


ne


up-right


upright


rightup


southwest


sw


down-left


downleft


leftdown


southeast


se


down-right


downright


rightdown


number cm


number mm


number inch


number pt


number number


by distance direction


point1 + point2


point1 - point2


point by distance direction


point1 | point2


n between poin1 point2


intersect elem1 elem2


element names ?pattern?


element corner


element corner1 corner2...


element ?corner1... ?names
    ?pattern??]?


nth ?corner?


nth last ?corner?


nth shape ?corner?


nth last shape ?corner?


last ?corner?


last shape ?corner?


1st


2nd


3rd










DESCRIPTION


Welcome to diagram, a package for the easy construction of
    diagrams (sic), i.e. 2D vector graphics, sometimes also called
    pictures. Note that this package is not a replacement for Tk's
    canvas, but rather a layer sitting on top of it, to make it easier to use.
    In other words, using the canvas as the core graphics engine diagram
    abstracts away from the minutiae of handling coordinates to position and
    size the drawn elements, allowing the user to concentrate on the content of
    the diagram instead.


This is similar to Brian Kernighan's PIC language for troff, which
    is the spiritual ancestor of this package.


This document contains the reference to the API and drawing
    (language) commands. Its intended audience are users of the package wishing
    to refresh their memory. Newcomers should read the Diagram Language
    Tutorial first. Developers wishing to work on the internals of the
    package and its supporting packages should look at section Diagram
    Classes first, and then the comments in the sources of the packages
    itself.


In the remainder of the document we first describe the APIs of the
    diagram class and its instances, followed by the language reference for the
    drawing language itself.






API




CLASS API


The package exports the API described here.



  
::diagram objectName canvas ?script?

  
The command creates a new instance of a diagram controller and returns the
      fully qualified name of the object command as its result. The new instance
      is connected to the specified canvas object, which is used as the
      diagrams graphics engine. This is usually an instance of Tk's canvas,
      however any object which is API compatible to Tk's canvas can be used
      here.
    
The API of this object command is described in the following
        section, Object API. It may be used to invoke various operations
        on the object.

    
If the script argument is specified then method
        draw will be invoked on it.

  








OBJECT API


Instances of the diagram class support the following methods:



  

  
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.

  







  

  
This attribute specifies the angle of the direction in degrees, where 0
      points east (to the right) and 90 points north (up).

  

  
This attribute specifies the name of the direction which should be
      considered as complementary to the named one.







  

  
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:

  







  

  
Where canvas is the handle of the canvas widget to draw to, and
      attributes is a dictionary holding the attributes for the element,
      be they user-specified, or defaults.
    
The results of the command has to be a list containing at
        least two and at most four items. These are, in order:

  







  
[1]

  
The list of canvas items the drawn element consists of.

  
[2]

  
The dictionary of named locations in the element, its corners.

  
[3]

  
An optional mode, either "relative" or "absolute".
      When not returned "relative" is assumed. In the case of a
      relative element position the attributes "with" and
      "at" are used to determine the final position of the new
      element.

  
[4]

  
An optional name of a direction. If not the empty string this is handed to
      the automatic layouter as the new direction to follow.









  

  
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.

  

  

  
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.

  

  
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:

  







  

  
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.

  

  

  
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

  







  

  
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.

  







  

  
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

  







  

  
Where value is the value to transform.
    
The result of the command is the final value of the
      attribute.

  







  

  
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.

  

  

  
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

  







  

  
Where value is the value to insert, and dict the dictionary
      of attributes and values collected so far.
    
The result of the command is the new dictionary of
      attributes.

  







  

  
The value of this key is a boolean flag. It has an effect if and only if
      the key merge was not specified. This key is optional. If it is not
      specified it defaults to False.
    
If the key is effective, the value of False means that
        the attribute's value is set into the dictionary using the value
        of key key (see above) as index, overwriting any
        previously specified value.

    
If the key is effective, the value of True means that
        the attribute's value is added to the dictionary using the value
        of key key (see above) as index, extending any previously
        specified value. This means that the final value of the attribute as
        seen after processing will be a list of the collected values.

  

  

  
The value of this key is a command prefix which will be invoked after
      collection of attributes has been completed and this attribute is in the
      list of required attributes for the drawing element (See argument
      attributes of method new element).
    
Note that the connection is made through the value of key
        key, not through the attribute name per se.

    
Further note that this command prefix is invoked even if a
        user specified attribute value is present. This allows the command to go
        beyond simply setting defaults, it can calculate and store derived
        values as well.

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

    
The signature of the command prefix is

  







  

  
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.

  

  

  
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.

  

  

  
This method is run to push current a attribute value into the language
      namespace, to make it the new default.
    
The result of this method is ignored.

  







  

  
This key is effective if and only if key default is not specified.
      In that case is supplies a default handling for default, linking
      the attribute to a variable in the language context.
    
The value for this key is a 2-element list containing the name
        of the variable to link to, and its initial value, in this order.

  







  

  
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:

  







  

  
Where wordqueue is the handle of a queue object conforming to the
      API of the queues provided by package struct::queue. This queue
      contains the not-yet-processed part of the attribute definitions, with one
      entry per word, with the first entry the name of the attribute which could
      not be processed.
    
The results of the command has to be a boolean value where
        True signals that this callback has accepted the attribute,
        processed it, and the new state of the wordqueue is where the
        general processing shall continue.

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

  







  
[1]

  
Replace the attribute (and arguments) with a different attribute and
      arguments.

  
[2]

  
Push additional words in front to get the general processing unstuck.









  

  
This method runs the given script in the context of the drawing
      language definitions. See section Language Reference for details on
      the available commands.
    
Note that script is trusted. It is
        executed in the current interpreter with access to its full abilities.
        For the execution of untrusted diagram scripts this interpreter should
        be a safe one.

  










LANGUAGE REFERENCE




ELEMENTS


This section lists the commands for the predefined drawing
    elements, aka shapes. These commands are all defined in the language's
    context. All commands of this section return the handle of the newly created
    element as their result. This handle also exists as a command which can be
    used to query the element for its corners (names, values). See section
    Miscellaneous Commands. IMAGE: figure-02-basic-shapes



  

  
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







  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  

  

  
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.

  

  
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.

  

  

  

  
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.

  

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

  

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

  

  
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.

  

  
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.

  

  
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.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
Note that the values "solid", "dot(ted)",
      "dash(ed)", "dash-dot", and "dash-dot-dot"
      are all accepted as shorthands for the style command using them as
      argument.





  

  
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.

  

  
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.

  

  
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.

  

  
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.







  

  

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

  

  
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.

  

  

  
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







  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  
Specifies the location of the element's corner named by the attribute
      with. Defaults to the current location as maintained by the
      layouting system.

  

  
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.

  

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

  

  

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
Note that the values "solid", "dot(ted)",
      "dash(ed)", "dash-dot", and "dash-dot-dot"
      are all accepted as shorthands for the style command using them as
      argument.





  

  
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.

  

  
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.

  

  
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.

  

  

  

  
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.

  

  
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.







  

  

  

  
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







  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  
Specifies the location of the element's corner named by the attribute
      with. Defaults to the current location as maintained by the
      layouting system.

  

  
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.

  

  

  

  
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.

  

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

  

  
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.

  

  

  

  
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.

  

  
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.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
Note that the values "solid", "dot(ted)",
      "dash(ed)", "dash-dot", and "dash-dot-dot"
      are all accepted as shorthands for the style command using them as
      argument.





  

  
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.

  

  
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.

  

  
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.

  

  
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.







  

  

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







  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  
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.

  

  

  
Specifies the location of the element's corner named by the attribute
      with. Defaults to the current location as maintained by the
      layouting system.

  

  
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.

  

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

  

  
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.

  

  

  
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.

  

  
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.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
Note that the values "solid", "dot(ted)",
      "dash(ed)", "dash-dot", and "dash-dot-dot"
      are all accepted as shorthands for the style command using them as
      argument.





  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  

  
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.







  

  
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







  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  
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.

  

  
Specifies the location of the element's corner named by the attribute
      with. Defaults to the current location as maintained by the
      layouting system.

  

  
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.

  

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

  

  

  

  
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.

  

  
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.

  

  
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.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
Note that the values "solid", "dot(ted)",
      "dash(ed)", "dash-dot", and "dash-dot-dot"
      are all accepted as shorthands for the style command using them as
      argument.





  

  
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.

  

  
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.

  

  
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.

  

  

  

  
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.

  

  
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.







  

  
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







  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  
Specifies the location of the element's corner named by the attribute
      with. Defaults to the current location as maintained by the
      layouting system.

  

  
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.

  

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

  

  

  

  
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.

  

  
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.

  

  
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.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
Note that the values "solid", "dot(ted)",
      "dash(ed)", "dash-dot", and "dash-dot-dot"
      are all accepted as shorthands for the style command using them as
      argument.





  

  
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.

  

  
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.

  

  
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.

  

  

  

  
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.

  

  
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.







  

  

  

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







  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  
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







  

  
Draw no arrowheads, at neither end of the line.

  

  
Draw an arrowhead at the beginning of the line, but not at its end.

  

  
Draw an arrowhead at the end of the line, but not at its beginning.

  

  
Draw arrowheads at both ends of the line.







  

  
Note that the values "start", "end", "-",
      "->", "<-", and "<->" are all
      accepted as shorthands for the arrowhead command using them as
      argument.





  

  
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.

  

  
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

  

  
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.

  

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

  

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

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
Note that the values "solid", "dot(ted)",
      "dash(ed)", "dash-dot", and "dash-dot-dot"
      are all accepted as shorthands for the style command using them as
      argument.





  

  
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.

  

  
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.

  

  
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.

  

  

  

  

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

  

  

  
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.

  

  
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.







  

  
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.

  

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

  

  
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







  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  
Specifies the location of the element's corner named by the attribute
      with. Defaults to the current location as maintained by the
      layouting system.

  

  
Specifies the height of the text element. Defaults to the natural
      height of its text.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

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

  

  
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.










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.



  

  

  

  

  

  

  

  

  

  
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.







  

  
"anchor west"

  

  
"anchor east"

  

  
"anchor south"

  

  
"anchor north"







  

  
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







  

  
Draw no arrowheads, at neither end of the line.

  

  
Draw an arrowhead at the beginning of the line, but not at its end.

  

  
Draw an arrowhead at the end of the line, but not at its beginning.

  

  
Draw arrowheads at both ends of the line.







  

  
Note that the values "start", "end", "-",
      "->", "<-", and "<->" are all
      accepted as shorthands for the arrowhead command using them as
      argument.





  

  
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.

  

  

  
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.

  

  
Specifies the location of the element's corner named by the attribute
      with. Defaults to the current location as maintained by the
      layouting system.

  

  
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.

  

  
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

  

  

  

  
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.

  

  
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.

  

  

  

  
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.

  

  

  

  
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.

  

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

  

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

  

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

  

  

  

  
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.

  

  
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.

  

  

  
Specifies the height of the text element. Defaults to the natural
      height of its text.

  

  
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.

  

  
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.

  

  

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
Note that the values "solid", "dot(ted)",
      "dash(ed)", "dash-dot", and "dash-dot-dot"
      are all accepted as shorthands for the style command using them as
      argument.





  

  
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.

  

  
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.

  

  
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.

  

  

  

  

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

  

  

  
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.

  

  
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.

  

  

  

  
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.

  

  
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.

  

  

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

  

  
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.

  

  
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.



  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  
  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  








MISCELLANEOUS COMMANDS



  

  

  

  

  

  

  

  
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.

  

  

  

    
IMAGE: figure-50-point-cons-absolute

    
This command takes the x and y coordinates of a location and
        returns the absolute point for it.

  

  

  

    
IMAGE: figure-51-point-cons-relative

    
This command takes a distance and direction
        (angle in degress, or registered direction name) and returns the
        relative point for it, i.e. the delta or
        translation it represents.

    
Note also the (dis)similarities to the directional
        specifications for the attribute then of line and
        move elements. Where we say here

  






by 50 east





  

  
for the attribute we say






... then east 50 ...





  

  
or just






... then east ...





  

  

    
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.

  

  

  

    
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.

  

  

  
This command is a more convenient, or at least shorter, form of








    [$point + [by $distance $direction]]






  

  

    
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.

  

  

  

    
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

  







  

  
The result is point1.

  

  
The result is point2.

  

  
The result is half way between the two points.







  

  
etc. Note that it is allowed to use values < 0 and > 1 for
      n





  

  

    
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.

  

  

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

  

  
This command returns the value for the corner of the
      element. This can be anything, including points and elements.

  

  
This is a convenience shorthand for






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






  

  
assuming that the value for








 [$elem $corner1]




again an element.



  

  
This is a convenience shorthand for






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






  

  
assuming that the value for








 [$elem $corner1]



again an element.


  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  

  

  
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:



  

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

  

  
The default value for the attribute radius of arc elements.
      Initialized to the pixel equivalent of 1 cm.

  

  
The default value for the attribute arrowhead. Initialized to
      none. The legal values are







  

  
Draw no arrowheads, at neither end of the line.

  

  
Draw an arrowhead at the beginning of the line, but not at its end.

  

  
Draw an arrowhead at the end of the line, but not at its beginning.

  

  
Draw arrowheads at both ends of the line.







  

  
The default value for the attribute height of box,
      diamond and ellipse elements. Initialized to the pixel
      equivalent of 2 cm.

  

  
The default value for the attribute width of box,
      diamond and ellipse elements. Initialized to the pixel
      equivalent of 2 cm.

  

  
The default value for the attributes clockwise and
      counterclockwise of arc elements. Initialized to
      False, for counter-clockwise direction.

  

  
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.

  

  
The default value for the attribute aspect of drum elements.
      Initialized to 0.35.

  

  
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.

  

  
The default value for the attribute justify. Initialized to
      left. The legal values are left, right, and
      center.

  

  
The default value for the attribute color of all elements having to
      draw lines (all but text). Initialized to black.

  

  
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:







  

  
Draw solid line.

  

  
Draw a dashed line.

  

  
Draw a dotted line.

  

  
Draw a dash-dotted line

  

  
Draw a dash-dot-dotted line.







  

  
The default value for the attribute stroke of all elements having
      to draw some line. Initialized to 1 (pixels).

  

  
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.

  

  
The default value for the attribute slant of box elements.
      Initialized to 90 degrees, i.e. slant straight up.

  

  
The default value for the attribute textcolor of all elements
      having to draw some text. Initialized to black.

  

  
The default value for the attribute textfont of all elements having
      to draw some text. Initialized to Helvetica 12pt.










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


on the internals of the diagram package. Regular users of
    diagram can skip this section without missing anything.


The main information seen here is the figure below, showing the
    hierarchy of the classes implementing diagram.


IMAGE: figure-00-dependencies


At the bottom, all at the same level are the supporting packages
    like snit, etc. These can all be found in Tcllib.


Above them is the set of diagram classes implementing the various
    aspects of the system, i.e.:



  

  
The main class, that which is seen by the user.

  

  
The core engine, itself distributed over four helper classes.

  

  
The implementation of the standard shapes, like box, circle, etc., based
      on the extension features of the core.

  

  
Core support class, the database of created elements. It also keeps the
      history, i.e. the order in which elements were created.

  

  
Core support class, the generic handling of definition and processing of
      attributes.

  

  
Core support class, the database of named directions.

  

  
Core support class, the state of layout engine, i.e. current position and
      directin, and operations on it.

  

  
General support class handling various vector operations.








REFERENCES






BUGS, IDEAS, FEEDBACK


This document, and the package it describes, will undoubtedly
    contain bugs and other problems. 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.






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







  

    0.3
    tklib