Tk Library Source Code

Documentation
Login
Bounty program for improvements to Tcl and certain Tcl packages.


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

diagram - Diagram drawing

Table Of Contents

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??]?
__n__th ?corner?
__n__th last ?corner?
__n__th shape ?corner?
__n__th 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.

Object API

Instances of the diagram class support the following methods:

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.

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.

Corners

Corners are named values for in elements, usually locations.

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.

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

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:

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.

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

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