tcldot
initially adds only two commands to tcl, namely
dotnew
and
dotread.
These commands return a handle for the graph that has just been created
and that handle can then be used as a command for further actions on the graph.
All other "commands" are of the form:
Many of the methods return further
handles of graphs, nodes of edges, which are themselves registered as commands.
The methods are described in detail below, but in summary:
Graph methods are:
-
"addedge, addnode, addsubgraph, countedges, countnodes, layout, listattributes, listedgeattributes, listnodeattributes, listnodes, listsubgraphs, render, rendergd, queryattributes, queryedgeattributes, querynodeattributes, setattributes, setedgeattributes, setnodeattributes, showname, write."
Node methods are:
-
"addedge, listattributes, listedges, listinedges, listoutedges, queryattributes, setattributes, showname."
Edge methods are:
-
"delete, listattributes, listnodes, queryattributes, setattributes, showname."
-
dotnew graphType ?attributeName attributeValue? ?...?
creates a new empty graph and returns its
graphHandle.
graphType
can be any supported by
dot(1)
namely: "graph," "digraph," "graphstrict," or "digraphstrict."
(In digraphs edges have a direction from tail to head. "Strict" graphs
or digraphs collapse multiple edges between the same pair of
nodes into a single edge.)
Following the mandatory
graphType
parameter the
dotnew
command will accept an arbitrary number of attribute name/value pairs
for the graph.
Certain special graph attributes and permitted values are described in
dot(1),
but the programmer can arbitrarily invent and assign values
to additional attributes beyond these.
In
dot
the attribute name is separated from the value by an "=" character.
In
tcldot
the "=" has been replaced by a " " (space) to be more consistent
with
tcl
syntax.
e.g.
set g [dotnew digraph rankdir LR]
-
dotread fileHandle
reads in a dot-language description of a graph from a previously opened
file identified by the
fileHandle.
The command returns the
graphHandle
of the newly read graph. e.g.
set f [open test.dot r]
set g [dotread \$f]
-
graphHandle addnode ?nodeName? ?attributeName attributeValue? ?...?
creates a new node in the graph whose handle is
graphHandle
and returns its
nodeHandle.
The handle of a node is a string like: "node0" where the integer value is
different for each node.
There can be an arbitrary number of attribute name/value pairs
for the node.
Certain special node attributes and permitted values are described in
dot(1),
but the programmer can arbitrarily invent and assign values
to additional attributes beyond these.
e.g.
set n [\$g addnode "N" label "Top\\nNode" shape triangle eggs easyover]
A possible cause of confusion in
tcldot
is the distinction between handles, names, labels, and variables.
The distinction is primarily in who owns them.
Handles are owned by tcldot and are guaranteed to be unique within
one interpreter session. Typically handles are assigned to variables,
like "n" above, for manipulation within a tcl script.
Variables are owned by the programmer.
Names are owned by the application that is using the
graph, typically names are important when reading in a graph from
an external program or file. Labels are the text that is displayed with
the node
(or edge) when the graph is displayed, labels are meaningful to the
reader of the graph. Only the handles and variables are essential to
tcldot's
ability to manipulate abstract graphs. If a name is not specified then
it defaults to the string representation of the handle, if a label is
not specified then it defaults to the name.
-
graphHandle addedge tailNode headNode ?attributeName attributeValue? ?...?
creates a new edge in the graph whose handle is
graphHandle
and returns its
edgeHandle.
tailNode
and
headNode
can be specified either by their
nodeHandle
or by their
nodeName.
e.g.
set n [\$g addnode]
set m [\$g addnode]
\$g addedge \$n \$m label "NM"
\$g addnode N
\$g addnode M
\$g addedge N M label "NM"
The argument is recognized as a handle if possible and so it is best
to avoid names like "node6" for nodes. If there is potential for conflict then use
findnode
to translate explicitly from names to handles.
e.g.
\$g addnode "node6"
\$g addnode "node99"
\$g addedge [\$g findnode "node6"] [\$g findnode "node99"]
There can be an arbitrary number of attribute name/value pairs
for the edge.
Certain special edge attributes and permitted values are described in
dot(1),
but the programmer can arbitrarily invent and assign values
to additional attributes beyond these.
-
graphHandle addsubgraph ?graphName? ?attributeName attributeValue? ?...?
creates a new subgraph in the graph and returns its
graphHandle.
If the
graphName
is omitted then the name of the subgraph defaults to it's
graphHandle.
There can be an arbitrary number of attribute name/value pairs
for the subgraph.
Certain special graph attributes and permitted values are described in
dot(1),
but the programmer can arbitrarily invent and assign values
to additional attributes beyond these.
e.g.
set sg [\$g addsubgraph dinglefactor 6]
Clusters, as described in
dot(1),
are created by giving the subgraph a name that begins with the string:
"cluster".
e.g.
set cg [\$g addsubgraph cluster_A dinglefactor 6]
-
nodeHandle addedge headNode ?attributeName attributeValue? ?...?
creates a new edge from the tail node identified by tha
nodeHandle
to the
headNode
which can be specified either by
nodeHandle
or by
nodeName
(with preference to recognizing the argument as a handle).
The graph in which this is drawn is the graph in which both nodes are
members.
There can be an arbitrary number of attribute name/value pairs
for the edge.
These edge attributes and permitted values are described in
dot(1).
e.g.
[\$g addnode] addedge [\$g addnode] label "NM"
-
graphHandle delete
-
nodeHandle delete
-
edgeHandle delete
Delete all data structures associated with the graph, node or edge
from the internal storage of the interpreter. Deletion of a node also
results in the the deletion of all subtending edges on that node.
Deletion of a graph also results in the deletion of all nodes and
subgraphs within that graph (and hence all edges too). The return from
these delete commands is a null string.
-
graphHandle countnodes
-
graphHandle countedges
Returns the number of nodes, or edges, in the graph.
-
graphHandle listnodes
-
graphHandle listsubgraphs
-
nodeHandle listedges
-
nodeHandle listinedges
-
nodeHandle listoutedges
-
edgeHandle listnodes
Each return a list of handles of graphs, nodes or edges, as appropriate.
-
graphHandle findnode nodeName
-
graphHandle findedge tailnodeName headNodeName
-
nodeHandle findedge nodeName\R
Each return the handle of the item if found, or an error if none are found.
For non-strict graphs when there are multiple edges between two nodes
findedge
will return an arbitrary edge from the set.
-
graphHandle
showname
-
nodeHandle showname
-
edgeHandle showname
Each return the name of the item. Edge names are of the form:
"a->b" where "a" and "b" are the names of the nodes and the connector
"->" indicates the tail-to-head direction of the edge. In undirected
graphs the connector "--" is used.
-
graphHandle setnodeattributes attributeName attributeValue ?...?
-
graphHandle setedgeattributes attributeName attributeValue ?...?
Set one or more default attribute name/values that are to apply to
all nodes (edges) unless overridden by subgraphs or per-node
(per-edge) attributes.
-
graphHandle listnodeattributes
-
graphHandle listedgeattributes
Return a list of attribute names.
-
graphHandle querynodeattributes attributeName ?...?
-
graphHandle queryedgeattributes attributeName ?...?
Return a list of default attribute value, one value for each of the
attribute names provided with the command.
-
graphHandle setattributes attributeName attributeValue ?...?
-
nodeHandle setattributes attributeName attributeValue ?...?
-
edgeHandle setattributes attributeName attributeValue ?...?
Set one or more attribute name/value pairs for a specific graph, node,
or edge instance.
-
graphHandle listattributes
-
nodeHandle listattributes
-
edgeHandle listattributes
Return a list of attribute names (attribute values are provided by
queryattribute
-
graphHandle queryattributes attributeName ?...?
-
nodeHandle queryattributes attributeName ?...?
-
edgeHandle queryattributes attributeName ?...?
Return a list of attribute value, one value for each of the
attribute names provided with the command.
-
graphHandle layout
Annotate the graph with layout information. This commands takes an
abstract graph add shape and position information to it according to
dot's
rules of eye-pleasing graph layout. The result of the layout is stored
as additional attributes name/value pairs in the graph, node and edges.
These attributes are indended to be interpreted by subsequent
write
or
render
commands.
(Implementation note: In a future release of
tcldot
I expect to further split the
layout
command into
placenodes
and
routeedges
so that alternate placement and routing strategies can be offered.)
-
graphHandle write fileHandle format
Write a graph (with already computed layout annotation) to the open file
represented by
fileHandle
in a specific
format.
Possible
formats
are: "ps" "mif" "hpgl" "plain" "dot" "gif" "ismap"
-
graphHandle rendergd gdHandle
Generates a rendering of a (previously layed out graph) to a new
or existing gifImage structure (see
gdTcl(1)
). Returns the
gdHandle
of the image.
-
graphHandle render
Returns a string of commands which, when evaluated, will render the
graph to a
Tk
canvas whose
canvasHandle
is available in variable
#!/usr/local/bin/wish
package require Tcldot
set c [canvas .c]
pack \$c
set g [dotnew digraph rankdir LR]
\$g setnodeattribute style filled color white
[\$g addnode Hello] addedge [\$g addnode World!]
\$g layout
eval [\$g render]
render
generates a series of canvas commands for each graph element, for example
a node typically consist of two items on the canvas, one for the shape
and the other for the label. The canvas items are automatically
tagged
(See
canvas(n)
) by the commands generated by render. The tags take one of two forms:
text items are tagged with 0 and
shapes and lines are rendered with 1.
The tagging can be used to recognize when a user wants to interact with
a graph element using the mouse. See the script in
examples/disp
of the tcldot distribution for a demonstration of this facility.
slide: COMMANDS
BUGS
Still batch-oriented. It would be nice if the layout was maintained incrementally.
No choice of layout engine. The neato undirected-graph engine would be a useful addition.
(The intent is to address these limitations in graphviz_2_0.)
slide: BUGS
AUTHOR
John Ellson, Lucent Technologies, Holmdel, NJ. (ellson@lucent.com)
ACKNOWLEDGEMENTS
John Ousterhout, of course, for
tcl
and
tk.
Steven North and Eleftherios Koutsofios for
dot.
Karl Lehenbauer and Mark Diekhans of NeoSoft
for the handles.c code which was derived from tclXhandles.c.
Tom Boutell of the Quest Center at Cold Spring Harbor Labs for the gif drawing routines.
Spencer Thomas of the University of Michigan for gdTcl.c.
Dayatra Shands for coding much of the initial implementation of
tcldot.
slide: ACKNOWLEDGEMENTS
KEYWORDS
graph, tcl, tk, dot
[.]
Papers
Tutorials
Examples
Manuals
Interfaces
Sources
Packages
Resources
?
