API Graph Commands

On this page, API commands of the graph category are described. This category covers all commands to send graphs in term representation format 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 format "graphterm" to uDraw(Graph) for visualization. This is the same format used for file representation of uDraw(Graph) graphs, i.e. the files with suffix ".udg". Note: Unlike the file format, newline characters are not allowed in term representations if sent to the API. After transmitting a graph with this command, the layout algorithm for reducing edge crossing will not be started automatically. You can either do this later using API command menu(layout(improve_all)) or by combining both steps with command graph(new_placed(...)), see below. The advantage of using the second method is that the user will not see the intermediate graph visualization where the layout algorithm is not applied. If you do not want to send the whole graph via API, you can save it to a file and use command menu(file(open_graph(...))) to load 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 graph layout algorithm to reduce edge crossings) in one step. The advantage of using this command (instead of the previous one) is that the user will not see the intermediate graph visualization where the layout algorithm is not applied. The parameter "graphterm" is the term representation format of the graph. If you do not want to send the whole graph via API, you can save it to a file and use command menu(file(open_graph(...))) to load the graph from file.

graph(update(node_updates,edge_updates))

This command can be used to update the structure of the currently loaded graph. You can remove existing nodes and edges, add new nodes or connect nodes with new edges. Here a graph update contains two lists: one for the node and one for the edge updates. After sending this command, incremental layout will be used to integrate the update into the graph to make sure that the layout remains as stable as possible. After an update, all nodes (and edges) previously selected become implicitly deselected without sending the API answer node_selections_labels(...). For the list of "node_updates", there are two different kinds of list elements which can be mixed in any order:

• delete_node(node_id)
  Deletes the node with given "node_id". The ID must exist in the current graph. All edges of this node, coming from the parents and leading to the children, are implicitly removed as well.
• new_node(node_id,type,attributes)
  Inserts a new node in the graph with given node_id, type and node attributes. The node ID must be unique for all 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 any order:

• delete_edge(edge_id)
  Deletes the edge with given "edge_id". The ID must exist in the current graph. Note: The edges coming from the parents and leading to the children of a node that is removed in the same update must not be deleted, because they are removed implicitly.
• new_edge(edge_id,type,attributes,node_id,node_id)
  Inserts a new edge in the graph with given edge_id, type and edge attributes. The "edge_id" must be unique for all edges in the current graph and update. The first "node_id" is the parent and the second "node_id" is the child of the new edge. Both, the child and parent, have to be IDs of existing nodes in the current graph or new nodes of the update. Note: You cannot delete the parent and child node of a new edge in the same update.
• new_edge_behind(edge_id,edge_id,type,attributes,node_id,node_id)
  Same as "new_edge" (see directly above), but this inserts 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 first "edge_id". The left neighbour edge has to be an existing edge in the current graph or a new edge of the update.

graph(mixed_update(mixed_updates))

Same as command graph(update(...)) above, but here the node and edge updates can be mixed in one common list where the order is not significant. Creating mixed updates is easier in many situations because the node updates must not be collected before starting with the edge updates.

graph(change_attr(attr_changes))

This command is used to update the attributes of nodes and edges that exist in the current graph. The semantic of this operation is either to add the attribute if it does not previously exist (for that particular node or edge) or to overwrite it otherwise. For example, the current graph has a node with attributes to specify a red background and a text "test". So the attributes of the node are:

Now study the following attribute update for that node:

After sending this list of updates as parameter of command "graph(change_attr(...))", the node will be still drawn in red (the "COLOR" attribute is not overwritten), but with text "new test" and font "times".

In order to remove an attribute of a particular node or edge, you can set its value to an empty string using this API command. When removing the attribute, the default value for this attribute is used or (if the type of the node or edge has a visualization rule) the value from the corresponding visualization rule is applied.

The parameter of the API command (i.e. attr_changes) is a list of attribute changes with two different kinds of list elements. Both types of elements of this API command can be mixed in any order:

• node(node_id,attributes)
  Add or overwrite the attributes for the node specified by "node_id" that must exist in the current graph.
• edge(edge_id,attributes)
  Add or overwrite the attributes for the edge specified by "edge_id" that must exist in the current graph.

graph(update_and_change_attr(node_updates,edge_updates,attr_changes))

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 and edges in one step. The benefit of this command instead of using the other two commands directly after each other is that the graph is not displayed between applying the updates and modifying the attributes. First the updates in "node_updates" and "edge_updates" are applied to the graph and afterwards the attributes are changed according to the parameter "attr_changes". So here it is not allowed to modify the attributes of nodes and edges that are simultaneously removed.

graph(mixed_update_and_change_attr(mixed_updates,attr_changes))

Same as command graph(update_and_change_attr(...)) above, but here the node and edge updates can be mixed in one common list where the order is not significant. Creating mixed updates is easier in many situations because the node updates must not be collected before starting with the edge updates.

graph(change_type(type_changes))

This command is used to update the type of nodes and edges that have to exist in the current graph. The parameter of the command is a list of modifications with two different kinds of list elements. Both types of elements can be mixed in any order:

• node(node_id,type)
  Changes the type for the node specified by "node_id" that must exist in the current graph.
• edge(edge_id,type)
  Change the type for the edge specified by "edge_id" that must exist in the current graph.

This command is especially useful when several visualization rules have been supplied for different node and edge types using the visualization definition commands. Afterwards you can modify the appearance of nodes and edges by simply changing their type.