To specify graphs, a mechanism of identifiers (called labels
in former releases) and references is used in daVinci. For
example, if a child node has more than one parent node, then in the term
representation the corresponding subgraph of the child
appears in only one of the parents as a subterm. This subterm is marked with
an identifier (in fact, all nodes and edges need to be marked with a unique
identifier). All the other parents of the same child do not duplicate the
subterm. Instead, they point to the child by using a reference to the
identifier. Note that this way it is even possible to describe cyclic graphs.
When loading a term representation, daVinci will construct an
internal graph by resolving these references.
The linear order of a node's subterm (where the identifier is declared) and
a reference to this node (where the identifier is used) is arbitrary in a term
representation, so references can be used before the corresponding identifier
and subterm appears in the term representation.
Note: You have to make sure that each node and edge in a term
representation has its own unique identifier, i.e. do not use the same ID for
two objects. In multi-graph mode,
each context (graph) has its own scope, so there is no need to have unique
identifiers for the union of all current contexts.
Beside the identifier (a unique string) and the list of child nodes (which is
probably empty), each node also has a type and a list of
attributes which are responsible for the image of a node in the
visualization.
Types and
attributes
are discussed below. Between a parent
and the corresponding child node, there is an edge in the term representation
which also has its unique edge identifier, type and attributes. So, in fact
the childs of a node are edges and each edge has one node or reference as
subterm.
Note: In previous V1.x releases of daVinci, identifiers
(labels) for nodes and edges were recommended, but optional. In
daVinci V2.0, identifiers are now mandatory to support several new
features. For example, identifiers will be sent back to a connected
application when the user selects nodes or edges.
The syntax of the term representation
(startsymbol is graphterm) can be found in the API definition.
When a graph is loaded from file, whitespace (blanks, tabs or returns)
may occur at any position in a term representation. Of course, in strings
whitespace is significant. When a graph is sent in term representations to the
API, whitespace should be avoided and returns are
forbidden.
The following figure illustrates a term representation of a small graph and
the corresponding visualization in daVinci. A
more complex example is demonstrated below.
Multi-Edges and Self-Edges
Multi-edges and self-edges are special kinds of edges
that are treaded in a different way for the graph layout.
Multi-edges occur when there are two or
more edges between the same parent and child node. All these edges form one
multi-edge. The single edges of a multi-edge are spreaded in the middle between the parent and the child, whereby the
used gap can be adjusted with the
Options/Layout Dimensions...
dialog window.
Self-edges are edges where the parent and child node are the same, i.e. a node that is pointing to itself. Self-edges are visualized with a circular edge at the left resp. lower side of the node. The user can adjust the radius of self-edges with the Options/Layout Dimensions... dialog window. Multi self-edges are also possible when a node uses a reference to itself may times in its list of childs. These edges are visualized by writting the number of self-edges in the middle of the circle. The following figure illustrates the visualization of multi- and self-edges in daVinci.
In one of the next daVinci releases, the user will be able to load
a file of rules (visualization definition) that defines the visual
appearance of a class. For example, the user will be able to specify a rule
to draw all nodes of some class X with a red circle, instead of using
attributes
for each individual node of the class at the moment. The modification of a
rule will affect all elements of the class at the same time. So, the central
visualization definition will be a comfortable method to define
a universal visualization for a family of graphs.
Graphical object "text" can be used to simulate edge labels which are
currently not available in daVinci. "text" is very similar to object
"box", in fact it is a box without the black border. An example graph with
simulated edge labels is file
example_graphs/edge_labels.daVinci of the daVinci
distribution. The trick with simulated edge lables is to use a regular node
with graphical object "text" to show an edge label.
With object "icon", a user can define to use a monochrome image for a node
in the visualization. Unfortunately, "icon" is more complicated than the
other graphical objects. The bitmap file with the image of the icon need to
be specified with a second attribute "ICONFILE" (see below), so for icons
you need two attributes: "_GO" and "ICONFILE".
Notes about attribute "ICONFILE":
Attributes
Attributes are used in the term representation to specify the
visualization of individual nodes and edges. Each node and edge has its own
attributes which is a list of string pairs with a constructor a
followed by an attribute name and attribute value in parentheses. Here is an
example for the attributes of a node:
[a("OBJECT","hello"),a("COLOR","red"),a("FONTFAMILY","times")]
If a particular attribute is specified for a node or edge, it will overwrite
the default value for this attribute which is used otherwise. Node and edge
attributes are distinguished from eachother. For example, there are different
attributes (more precisely: attribute names) to set the color of nodes
("COLOR") and edges ("EDGECOLOR"). Edge attributes cannot be used for nodes
and vice versa. Unknown attribute names and values are simply ignored without
any warning. This way, the term representation is both up- and backward
compatible with previous and future releases of daVinci.
Some attributes, starting with character '_', are needed for internal
purposes, but can also be used in a term representation.
The usage of attributes is demonstrated in the
example
below.
Supported Node Attributes
Node Attribute "OBJECT"
This is the most important attribute for a graph visualization, used to
specify the text that appears inside a node. Usually, each node should have
this attribute. The text, i.e. the attribute value, may be an arbitrary
string, whereby international characters are supported (ISO 8bit). The
extension of a node in the graph visualization will automatically follow the
size of the text by considering the current font, so nodes may have any size.
Even multi-line text is supported by using a '\n' inside the attribute value.
The default value for this attribute is the empty string "".
Node Attribute "FONTFAMILY" and "FONTSTYLE"
These two attributes are used to visualize the text of a node in a different
font. Supported values of attribute
"FONTFAMILY" are: "lucida" (default), "times", "helvetica", and
"courier". Values of attribute "FONTSTYLE" are:
"normal", "bold" (default), "italic", and "bold_italic".
For a node, both font attributes do not need to be used pairwise at the
same time.
Node Attribute "COLOR"
Can be used to define the background color of a node. The value of this
attribute may be any X-Window colorname (see file lib/rgb.txt in
your X11 directory) or any RGB color specification in a format like
"#0f331e", where 0f is the hexadecimal value for the red part of the color,
33 is the green part and 1e is the blue. Hence, a pallet of 16.7 million
colors is supported. The default color for nodes is "white".
Node Attribute "_GO" (Graphical Object)
This attribute specifies the geometrical object used to draw a node. Six
different objects are currently implemented: "box" (default), "circle",
"ellipse", "rhombus", "text", and "icon".
Node Attribute "ICONFILE"
This is used as a supplement for attribute
"_GO"
when its value is set to "icon".
Attribute "ICONFILE" specifies the (relative) filename of the bitmap used
to draw the node as icon. The file must be in X-Window bitmap format
(.xbm). Absolute filenames are not allowed as a value for this
attribute. daVinci is looking for the file in all directories
given by environment variable $DAVINCI_ICONDIR. So for example,
when the bitmap of an icon is in file /home/me/images/my_image.xbm,
then add /home/me/images to the search path of environement variable
$DAVINCI_ICONDIR before starting daVinci, set attribute
"_GO" to "icon" and attribute "ICONFILE" to "my_image.xbm" for a particular
node. The default value for this attribute is "".
Node Attribute "HIDDEN"
Attribute "HIDDEN" is used to hide the subgraph of a node initially. This is
the same operation available in menu
Abstraction/Hide Subgraph.
Supported values for this attribute are "true" and "false" ("false" is the
default).
Node Attribute "BORDER"
The graphical objects "box", "circle", "ellipse", and "rhombus" (see attribute
"_GO") are drawn with a double border line
if this attribute is set to "double".
The default value is "single" to have a normal border.
Supported Edge Attributes
Edge Attribute "EDGECOLOR"
In the same way as nodes, the color of an edge can be specified using this
attribute. The value of this attribute may be any X-Window colorname (see
file lib/rgb.txt in your X11 directory) or any RGB color
specification in a format like "#0f331e", where 0f is the hexadecimal value
for the red part of the color, 33 is the green part and 1e is the blue. Hence,
a pallet of 16.7 million colors is supported. The default color for
edges is "black".
Edge Attribute "EDGEPATTERN"
The pattern style of an edge is defined by this attribute. Possible values
are: "solid" (default), "dotted", "dashed", "thick", and "double".
Note: Thick edges should be used carefully because users might confuse
with selected solid edges (both are drawn with the same line thickness!).
Edge Attribute "_DIR"
This attribute is used to control the arrow of an edge. In a graph
visualization, each edge usually has an arrow pointing to the child node.
This attribute can be used to let the arrow be drawn inverse
(i.e. pointing to the parent), to get an arrow at both sides of an edge
or to suppress arrows for a particular edge. The supported attribute
values are: "normal" (default), "inverse", "both", and "none".
Example of a Term Representation
This example demonstrates a complex term representation of a graph, where all
available node and edge attributes are used. The figure below shows the
resulting graph visualization in daVinci V2.0.
[
l("Node A",n("Module",[a("COLOR","#f31d8b"),
a("OBJECT","Node A"),
a("_GO","ellipse"),
a("FONTFAMILY","helvetica")],
[
l("Edge A->B",e("",[a("EDGECOLOR","red")],
l("Node B",n("anything",[a("COLOR","light steel blue"),
a("BORDER","double"),
a("OBJECT","Node B\nThis node has two lines")],
[
l("Edge B->D",e("",[a("EDGEPATTERN","dotted"),
a("_DIR","inverse")],
r("Node D")))
])))),
l("Edge A->C",e("",[a("EDGEPATTERN","dotted"),
a("EDGECOLOR","#0054aa")],
l("Node C",n("anything",[a("_GO","icon"),
a("ICONFILE","bkb.xbm"),
a("COLOR","gold"),
a("OBJECT","Node C"),
a("FONTSTYLE","italic")],
[
l("Edge C->D",e("anything",[a("EDGECOLOR","#00aaaa"),
a("_DIR","both")],
l("Node D",n("Module",[a("OBJECT","Node D"),
a("_GO","text"),
a("FONTFAMILY","times"),
a("FONTSTYLE","italic")],[])))),
l("Edge C->F",e("anything",[a("EDGEPATTERN","double")],
r("Node F")))
])))),
l("Edge A->E",e("",[a("EDGEPATTERN","dashed"),
a("_DIR","none")],
l("Node E",n("anything",[a("COLOR","LightGray"),
a("FONTFAMILY","courier"),
a("FONTSTYLE","normal"),
a("BORDER","double"),
a("OBJECT","Node E"),
a("_GO","rhombus")],
[
l("Edge E->F",e("anything",[a("EDGEPATTERN","thick")],
l("Node F",n("anything",[a("COLOR","#00dddd"),
a("OBJECT","Node F"),
a("HIDDEN","true")],
[
l("Edge F->G",e("anything",[],
l("Node G",n("anything",[a("OBJECT","Node G")],[]))))
]))))
]))))
]))
]
Visualization for this term representation:
daVinci V2.0 Online Documentation - Page update: May 7, 1996