[Contents] [Intro] [Reference] [Tutorial] [Questions [New [Index]
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))

This command 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. A graph update consist of two lists: One for the node and one for the edge updates. At the moment, a complete new layout for the whole graph will be calculated after an update. In the next release daVinci V2.1, the dynamic layout engine will be able to integrate an update into an existing layout to ensure visual stability.

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

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

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:

graph(update_and_change_attr(node_updates,edge_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.


daVinci V2.0.3 Online Documentation - Page update: Dec 6, 1996