NAME

Diagrams -
User documentation of the Diagrams package

SYNOPSIS

package require Tcl 8.4
package require Tk 8.4
package require Diagrams 0.3
::Diagrams::drawin canvas
::Diagrams::saveps filename
::Diagrams::direction newdir
::Diagrams::currentpos pos
::Diagrams::getpos anchor obj
::Diagrams::position xcoord ycoord
::Diagrams::box text width height
::Diagrams::plaintext text width height
::Diagrams::circle text radius
::Diagrams::slanted text width height angle
::Diagrams::diamond text width height
::Diagrams::drum text width height
::Diagrams::arrow text length heads
::Diagrams::line args
::Diagrams::bracket dir dist begin end
::Diagrams::attach anchor
::Diagrams::color name
::Diagrams::fillcolor name
::Diagrams::textcolor name
::Diagrams::usegap use
::Diagrams::xgap value
::Diagrams::ygap value
::Diagrams::textfont name
::Diagrams::linewidth pixels
::Diagrams::linestyle style
::Diagrams::pushstate 
::Diagrams::popstate 
::Diagrams::computepos 
::Diagrams::boxcoords x1 y1 x2 y2
::Diagrams::moveobject obj

DESCRIPTION

The Diagrams package is meant to help drawing diagrams, like flowcharts. The philosophy is that you should be concentrating on the contents of the diagram, rather than the exact positioning and sizing of all items within it. The Diagrams package uses a few simple rules to layout the items:

• Each item (or object) in the diagram has a number of "anchors" - places where arrows and lines can be connected to.
• You can draw an arrow or a line from an object in a preset direction
• Sizing and positioning should be done as automatic as possible: this is achieved for instance by drawing boxes and circles with text, rather than first drawing a rectangle and then drawing the text inside it or vice versa.

The commands within this package can be split up in several categories. Each category is described in a separate section.

GENERAL COMMANDS FOR POSITIONING AND SETUP

::Diagrams::drawin canvas

Set the canvas widget in which to draw

Type	Name	Mode
widget	canvas
	Widget to draw in

::Diagrams::saveps filename

Save the drawing in a PostScript file

Type	Name	Mode
filename	string
	Name of the file to save the drawing in

::Diagrams::direction newdir

Set the direction for moving the current position. The direction is one of: north northeast east southeast south southwest west northwest N NE E SE S SW W NW up up-right left down-right down down-left left up-left centre center C

Type	Name	Mode
newdir	string
	New direction

::Diagrams::currentpos pos

Set the current position explicitly (argument must be a position "object")

Type	Name	Mode
pos	list
	New position (retrieve via getpos for instance)

::Diagrams::getpos anchor obj

Get the position of a particular "anchor" point of an object anchor should be one of the direction strings

Type	Name	Mode
anchor	string
	Name of the anchor (one of the directions - see the direction command
obj	list
	The object in question

::Diagrams::position xcoord ycoord

Create a position "object"

Type	Name	Mode
xcoord	float
	X-coordinate of the position
ycoord	float
	Y-coordinate of the position

DRAWING OBJECTS

::Diagrams::box text width height

Draw a box from the current position (width and height are both optional; if not given, the text determines the width and height)

Type	Name	Mode
string	text
	Text to be shown inside the box
float	width
	Width (if any) of the box in pixels
float	height
	Height (if any) of the box in pixels

::Diagrams::plaintext text width height

Draw plain text from the current position (width and height are both optional; if not given, the text determines the width and height)

Type	Name	Mode
string	text
	Text to be shown
float	width
	Width (if any) of the (invisible) box in which to position the text
float	height
	Height (if any) of the box

::Diagrams::circle text radius

Draw a circle from the current position (the radius is optional)

Type	Name	Mode
string	text
	Text to be shown inside the circle
float	radius
	Radius (if any) of the circle in pixels

::Diagrams::slanted text width height angle

Draw a slanted box from the current position (width, height and angle are optional)

Type	Name	Mode
string	text
	Text to be shown inside the box
float	width
	Width (if any) of the box in pixels
float	height
	Height (if any) of the box in pixels
float	angle
	Angle of the slanted box

::Diagrams::diamond text width height

Draw a diamond-shaped box from the current position (width and height are both optional; if not given, the text determines the width and height)

Type	Name	Mode
string	text
	Text to be shown inside the diamond
float	width
	Width (if any) of the diamond in pixels
float	height
	Height (if any) of the diamond in pixels

::Diagrams::drum text width height

Draw a drumshaped item from th ecurrent position (width and height are both optional; if not given, the text determines the width and height)

Type	Name	Mode
string	text
	Text to be shown inside the drum
float	width
	Width (if any) of the drum in pixels
float	height
	Height (if any) of the drum in pixels

::Diagrams::arrow text length heads

Draw an arrow from the current position to the next. The text is drawn next to the arrow, the length (in pixels) is optional. If not given the gap parameters are used.

Type	Name	Mode
string	text
	Text to be shown along the arrow
float	length
	Length of the arrow in pixels
float	heads
	Which arrow heads to draw (first, last or both - defaults to last)

::Diagrams::line args

Draw a line specified via positions or via line segments The arguments are either position or length-angle pairs

Type	Name	Mode
list	args
	List of positions or of length-angle pairs

::Diagrams::bracket dir dist begin end

Draw an arrow consisting of three lines from one item to another. The first argument gives the direction in which the arrow "bulges" away from the items, the second argument gives the distance over which it bulges.

Type	Name	Mode
string	dir
	Direction of "bulging" - one of north, south, east or west.
float	dist
	Length of the two end pieces of the arrow
list	begin
	Description of the item where the arrow begins as (returned by one of the item creation procedures, box, circle ...)
list	end
	Ditto for the item where the arrow points to

ATTRIBUTES

(Note: attributes are persistent)

::Diagrams::attach anchor

Set the anchor point for attaching arrows to

Type	Name	Mode
string	anchor
	Any one of the valid anchor (e.g. N or North)

::Diagrams::color name

Set the color for the outline of a box etc.

Type	Name	Mode
color	name
	Name of the colour to be used

::Diagrams::fillcolor name

Set the color to fill the objects

Type	Name	Mode
color	name
	Name of the colour to be used

::Diagrams::textcolor name

Set the color to draw the text in

Type	Name	Mode
color	name
	Name of the colour to be used

::Diagrams::usegap use

Turn the gap on (1) or off (0). Note: usually a small gap is used when positioning objects.

Type	Name	Mode
boolean	use
	Use the gap to compute the position of the next object or not

::Diagrams::xgap value

Size of the gap in horizontal direction (in pixels)

Type	Name	Mode
integer	value
	Gap width in pixels

::Diagrams::ygap value

Size of the gap in vertical direction (in pixels)

Type	Name	Mode
integer	value
	Gap height in pixels

::Diagrams::textfont name

Set the name of the font to use

Type	Name	Mode
string	name
	Name of a text font

::Diagrams::linewidth pixels

Set the width of the lines (in line objects and arrows and the outline of boxes and other objects)

Type	Name	Mode
integer	pixels
	Number of pixels the lines are wide

::Diagrams::linestyle style

Set the style of the lines and arrows and of the outline of boxes and other objects. The predefined line styles are: solid, dot, dash, dash-dot, dash-dot-dot (these are the distinguishable line styles on Windows). You can also use the style patterns from the canvas directly.

Type	Name	Mode
string	style
	Name of a valid line style

COMMANDS FOR IMPLEMENTING NEW OBJECTS

Note: it is best to study how for instance box objects are implemented first.

::Diagrams::pushstate

Save the current global settings Used when defining an object that is composed of other objects

::Diagrams::popstate

Restore the previously saved global settings

::Diagrams::computepos

Compute the current position

::Diagrams::boxcoords x1 y1 x2 y2

Compute the anchor coordinates for a box-like object (this is merely a convenience routine. In general, you will have to compute the list of coordinates yourself - see for instance the diamond object)

Type	Name	Mode
float	x1
	X coordinate of upper-left corner
float	y1
	Y coordinate of upper-left corner
float	x2
	X coordinate of lower-right corner
float	y2
	Y coordinate of lower-right corner

::Diagrams::moveobject obj

Move the object to the right position and return the new information

Type	Name	Mode
list	obj
	List of data representing the object

KEYWORDS

diagrams, drawing