daVinci Term Representation

Structure of Term Representation

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 children 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.x, 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.

Self-edges are edges where the parent and child node are the same, i.e. a node that has an edge 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 edges with a reference to itself many times in its list of children. These edges are visualized by writing the number of self-edges in the middle of the circle. The attributes of self-edges are considered for the graph visualization (only in daVinci V2.0.2 or higher), but it is undefined which self-edge of a multi self-edge is taken for the attributes. So for example, if you have a multi self-edge containing a red and a blue self-edge, then it is not defined whether the multi self-edge is drawn in red or blue.

The following figure illustrates the visualization of multi- and self-edges in daVinci.

Note: With the command-line option -init you can supply API commands at startup of daVinci. If you put your definitions into such an initial file, you will be able to use visualization defintions without the API. Unfortunately, you will not be able to change the definitions at runtime.

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.

Attributes

    [a("OBJECT","hello"),a("COLOR","red"),a("FONTFAMILY","times"),
     m([menu_entry("MenuID","Menu Entry")])
    ]

Note: The geometrical object "scissors" is normally used to display nodes with hidden subgraphs. So it is not recommended to use this object, because the user may get confused.

Node Attribute "_CGO" (Graphical Object)

Notes about attribute "ICONFILE":

• Using attribute "ICONFILE" without setting "_GO" to "icon" will have no effect. Do not forget to set both attributes when you want to have icons in a graph visualization.
• Icon images are not saved in a status file, so when you like to transfer the status file of a graph with icons, make sure to transfer the bitmap files, too!
• If daVinci does not find the specified bitmap file of an icon in the directories defined by environment variable $DAVINCI_ICONDIR, then a default image with a question mark will be used instead.

Example of a Term Representation

This example demonstrates a complex term representation of a graph, where nearly all available node and edge attributes are used. The figure below shows the resulting graph visualization in daVinci V2.1.x.

 [
 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")],[]))))
            ]))))
        ]))))
    ]))
 ]

Here is the visualization of this term representation:

---

daVinci V2.1 Online Documentation - Page update: June 15, 1998