Overview -> Reference -> API Reference -> Commands of Category Graph

daVinci API Definition - Graph Commands

On this page, API commands of the graph category are described. This category covers all commands to send graphs in term representation and updates on graphs. The commands of this category are enclosed by keyword graph(...). Click here to get an overview of all API commands.

graph(new(graphterm))

Sends a graph in term representation graphterm to daVinci for visualization. This is the same format used for file representation of daVinci graphs (i.e. the .daVinci files). Note: Unlike the file format, newline characters are not allowed in term representations if sent to the API.

After transmitting a graph by using this command, the layout algorithm for edge crossing minimization will not be started automatically. You can either do this later using command menu(layout(improve_all)) or by combining both steps with command graph(new_placed(...)), see below. The advantage of the second method is that the user will not see an unplaced graph without an applied crossing minimization.

If you do not like to send the whole graph via API, you can save it to a file and use command menu(file(open_graph(...))) instead for loading the graph from file.

graph(new_placed(graphterm))

This command combines graph(new(...)) (i.e. transmitting a graph) and menu(layout(improve_all)) (i.e. starting the layout algorithm to minimize edge crossings) in one step. The advantage of using this command (instead of the previous one) is that the user will not see an unplaced graph without an applied crossing minimization. The parameter graphterm is the term representation of the graph which should be visualized.

If you do not like to send the whole graph via API, you can save it to a file and use command menu(file(open_graph_placed(...))) instead for loading the graph from file.

graph(update(node_updates,edge_updates))
graph(update(mixed_updates))

These commands can be used to update the structure of a current graph. You can remove existing nodes and edges, add new nodes or connect nodes with new edges. For the first command a graph update consist of two lists: One for the node and one for the edge updates. For the second command, updates for nodes and edges are supplied in one list. After sending this command, incremental layout will be used to integrate the update into an existing layout to ensure visual stability. After an update, all previously selected nodes (and edges) are always deselected without sending API answer node_selections_labels(...)

We describe the possible updates divided into node and edge updates. If you use the mixed_updates form of the command, you can use elements of both lists, which can be mixed in arbitrary order.

For the list of node_updates, there are two different kinds of list elements which can be mixed in arbitrary order:

delete_node(node_id)
Delete the node with given node_id. The ID must exist in the current graph. All edges of this node, from the parents and to the children, are implicitly removed as well.
new_node(node_id,type,attributes)
Insert a new node in the graph with given node_id, type and node attributes. The node ID must be unique for the set of nodes in the current graph and update. If the new node is not connected with new edges in the same update (see below), it will be visualized as an unconnected root node.

For the list of edge_updates, there are three different kinds of list elements which can be mixed in arbitrary order:

delete_edge(edge_id)
Delete the edge with given edge_id. The ID must exist in the current graph. Note: The edges from the parents and to the children of a node removed in the same update must not be deleted, because they are removed implicitly.
new_edge(edge_id,type,attributes,node_id,node_id)
Insert a new edge in the graph with given edge_id, type and edge attributes. The edge ID must be unique for the set of edges in the current graph and update. The first node_id is the parent and the second node_id is the child of the edge. Both, the child and parent, have to be ID's of existing nodes in the current graph or new nodes of the update. Note: You cannot delete the specified parent and child node in the same update.
new_edge_behind(edge_id,edge_id,type,attributes,node_id,node_id)
Same as new_edge (read directly above), but this will enter the new edge behind a left neighbour edge which is specified by the additional first edge_id. So, the new edge will be the right neighbour of the edges specified by the first edge_id. The left neighbour edge has to be the ID of an existing edge in the current graph or a new edge of the update. At the moment, there is no need to insert an edge at a specific position, because the order of child nodes is currently not significant. This may change in a future version of daVinci when visualization definitions will be available.

graph(change_attr(attr_changes))

This command can be used to update the attributes of nodes and edges that are already present in the current graph. The semantic of this operation is either to complete or overwrite the existing attributes of a particular node or edge. For example, in the current graph, a node is specified to be drawn in red with text "test", i.e. attributes are: [a("COLOR","red"), a("OBJECT","test")] Now consider the following attribute update: [a("OBJECT","new test"),a("FONTFAMILY","times")]. After sending this update, the node will be still drawn in red (the COLOR attribute is not overwritten), but with text "new test" in font "times".

The parameter of the command is a list of attribute changes with two different kinds of list elements. Both types of elements can be mixed in arbitrary order:

node(node_id,attributes)
Complete or overwrite the attributes for the node specified by node_id which has to be the ID of an existing node in the current graph.
edge(edge_id,attributes)
Complete or overwrite the attributes for the edge specified by edge_id which has to be the ID of an existing edge in the current graph.

graph(update_and_change_attr(node_updates,edge_updates,attr_changes))
graph(update_and_change_attr(mixed_updates,attr_changes))

(Only available in daVinci V2.0.3 or higher.) This command combines the API commands graph(update(...)) and graph(change_attr(...)) (described above) to update the structure of a graph and modify attributes of existing nodes in one step. The benefit of this command instead of using the other two commands directly after eachother is that the graph is not displayed after the update and before attribute modification. First the ..._updates are applied to the graph and afterwards the attr_changes are applied to the updated graph. So for example it is not allowed to modify attributes of nodes in attr_changes that are removed in ..._updates.

graph(change_type(type_changes))

This command can be used to update the type of nodes and edges that are already present in the current graph.

The parameter of the command is a list of type changes with two different kinds of list elements. Both types of elements can be mixed in arbitrary order:

node(node_id,type)
Change the type for the node specified by node_id which has to be the ID of an existing node in the current graph.
edge(edge_id,type)
Change the type for the edge specified by edge_id which has to be the ID of an existing edge in the current graph.

This command is especially usefull, if you've supplied several visualization rules for different node and edge types. Than you can change the appearance of a node or edge by changing its type.

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