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

daVinci API Definition - Menu Commands

On this page, API commands of the menu category are described. This category covers all commands to call the functions of the menus which can be found in the daVinci base window. The commands of this category are enclosed by keyword menu(...). The menu commands are further divided into sub-categories with respect to the menu they belong to, so for example, you can find the functions of menu File in the menu(file(...)) sub-category, and so on. Here is a list of all sub-categories on this page:

Click here to get an overview of all API commands.

File Menu Category:

The commands of the file category are responsible for input and output, i.e. loading, saving, and printing. Further, there are commands to close the current context (i.e. the actual graph in multi-graph mode) and to terminate the daVinci process. The file category is the API equivalent of the File menu of the user interface.

menu(file(new))

Remove the current graph and clear the window.

menu(file(open_graph(filename)))

Loads a new graph from file. The parameter filename (should not be relative!) specifies a file containing a daVinci graph in term representation.

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

As an alternative, you can avoid file access by sending the graph in term representation directly to the API using command graph(new(...)).

menu(file(open_graph_placed(filename)))

This command combines menu(file(open_graph(...))) (i.e. loading a graph) and menu(layout(improve_all)) (i.e. starting 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 applied crossing minimization. The parameter filename (should not be relative!) specifies a file containing a daVinci graph in term representation.

As an alternative, you can avoid file access by sending the graph in term representation directly to the API using command graph(new_placed(...)).

menu(file(open_status(filename)))

Loads a status from file filename (should not be relative!). The file has to exist and must contain a status previously saved by daVinci. A status is a graph together with layout informations and user interface settings.

menu(file(save_graph(filename)))

Saves the current graph in term representation to the specified file filename (should not be relative!). The filename should have the prefix .daVinci. By saving a term representation, only the graph structure will be stored and the layout informations will be lost.

menu(file(save_status(filename)))

Saves the status of the current graph to the specified file filename (should not be relative!). The filename should have the prefix .status. By saving a status, the graph structure will be stored as well as layout informations and user interface settings.

menu(file(print(filename)))

Saves a PostScript representation of the current graph to the specified file filename (should not be relative!). The filename should have the prefix .ps. The generated file is EPSF compliant (encapsulated PostScript) and can either be printed on a PostScript printer or imported with appropriated software. Read more about the PostScript interface in the reference.

The options of the PostScript interface, available in the print dialog window of the user interface, are not accessible from the API. This command will always use PostScript scale 1:1 without centering.

menu(file(print))

Opens the print dialog window if a graph is loaded. When no graph is loaded in the current context, nothing will happen.

menu(file(close))

-> Returns answer close!

Closes the current context in multi-graph multi-window mode. This will remove all windows which shows the graph of the current context. Afterwards, the closed context cannot be used any further. To proceed, the application has to open a new context with command multi(new_context) or specify one of the remaining contexts to be the current context with command multi(set_context(...)). All other commands will be ignored as long as a new current context is not specified!

This command is not available in single-graph mode. Even the last context may be closed without quitting daVinci. When closing the last context, no window will be visible, but the daVinci process is still running and accepts commands to open a new first context.

menu(file(exit))

Quits daVinci. This will immediately terminate the daVinci process.

View Menu Category:

The commands of the view category are used to open additional views (windows) to the current graph, to set the scale and to show some windows with information. The view category is the API equivalent of the View menu of the user interface.

menu(view(open_new_view))

Opens a new view of the current graph which is an additional base window showing the same graph (multi-view). Each view of a graph is based on the same logical structure, so selection of a node or fine-tuning operations in one view will manipulate all the other views of the same graph, too. One exception is the scale, so each view may have its own scale.

From a technical point of view, multi-view windows are not the same as multi-graph windows which show different graphs and are independent from eachother. Multi-view is a feature of the user interface, so an application is not able to control multi-view windows (e.g. to close one particular window). But the application has the opportunity to open additional views by using this command. All views (i.e. base windows) of a context (i.e. graph) will be removed when the context is closed, either by the user or the application with command menu(file(close)). The user may open and close new views for a graph at any time.

Note: In multi-view mode, all commands dealing with one base window rather than a graph (e.g. setting the scale, focusing nodes or setting the window position) are always applied only to the master view and not to all views of the current context. The master view is the oldest view of a context.

In multi-window mode this command returns answer open_window. All commands dealing with one base window rather than a graph (e.g. setting the scale, focusing nodes or setting the window position) are always applied to the current window.

menu(view(open_survey_view))

This command can be used to open a special survey view showing the whole graph in reduced scale, whereby the currently visible part of the master view is visualized with a blue rectangle. This rectangle is updated as soon as scrolling is used in the master view. When the user selects a node in the survey view, daVinci will automatically scroll to this node in the master view.

Refer to command menu(view(open_new_view)) for general information about multi-view.

In multi-window mode this command returns answer open_window.

menu(view(full_scale))

Sets the scale to 100% such that all details are visible. In multi-view mode, this operation will only affect the master view of the current context.

menu(view(fit_scale_to_window))

Sets the scale to the maximal value such that the graph is completely visible. In multi-view mode, this operation will only affect the master view of the current context.

menu(view(scale(integer)))

Sets the scale to the given parameter integer. The integer is a percent value and has to be in the range between 1 and 100. So, with a scale of 20 the graph is drawn five times smaller than usual. In scales smaller than 100, the text of nodes is not displayed and other details are dropped as well. If you like to have the graph in a smaller scale and need to see the text of nodes, you can set a smaller font size or gap width/height by using the API commands set(font_size(...)), set(gap_width(...)) and set(gap_height(...)). In multi-view mode, this operation will only affect the master view of the current context.

menu(view(scale))

Opens the scale dialog window if a graph is loaded. When no graph is loaded in the current context, nothing will happen.

menu(view(graph_info))

Opens the graph info dialog window if a graph is loaded. When no graph is loaded in the current context, nothing will happen.

menu(view(daVinci_info))

Opens the daVinci info dialog window.

Navigation Menu Category:

The commands of the navigation category are changing the selection, i.e. the set of currently selected nodes. There are commands to highlight the parent-, sibling- and child nodes for a given set of nodes. Further, there are commands to navigate to related nodes and find particular nodes based on textual search. The navigation category is the API equivalent of the Navigation menu of the user interface.

All commands of this category do not return answer ok for confirmation. Instead, they return the new selection by using answer node_selections_labels(...). Of course the corresponding operation of a navigation command may fail, for example when none of the nodes match with the string used in command menu(navigation(find(...))). A failed navigation command will not modify the selection and will return the current (former) selection as result. So, to see if the command was successful or not, you have to compare the node selection before and after sending the navigation command. If both selections are the same, then the navigation has failed, otherwise it was successful.

Note: If you are looking for an API command to select a specified set of nodes and edges in the graph, then this category is obviously the wrong place (because nodes are not selected via menus in daVinci, but with the mouse). You can select particular nodes and edges with the API commands found in the special(...) category.

menu(navigation(select_parents(node_ids)))

-> Returns answer node_selections_labels(...)!

Selects all parent nodes of the nodes specified by list node_ids. The returned answer is either the list of parents (which is the new current selection) or the former selection when this operation fails (i.e. if there are no parents for the given nodes).

menu(navigation(select_siblings(node_ids)))

-> Returns answer node_selections_labels(...)!

Selects all sibling nodes (i.e. children or all parents) of the nodes specified by list node_ids. The returned answer is either the list of siblings (which is the new current selection) or the former selection when this operation fails (i.e. if there are no siblings for the given nodes).

menu(navigation(select_children(node_ids)))

-> Returns answer node_selections_labels(...)!

(Only available in daVinci V2.1 or higher. This command was menu(navigation(select_childs(..))) in daVinci V2.0.x which is still supported by V2.1.x for backward compatibility.)
Selects all child nodes of the nodes specified by list node_ids. The returned answer is either the list of children (which is the new current selection) or the former selection when this operation fails (i.e. if there are no children for the given nodes).

menu(navigation(navigator(node_id,direction,boolean)))

-> Returns answer node_selections_labels(...)!

Selects the nearest neighbour node according to the given direction by starting at the specified node node_id. If the boolean parameter is false, geometrical navigation is used. This ignores the relations (edges) in the graph, so for example, if you navigate upwards, you will go to the nearest node at the previous level. On the other side, by using true for the boolean parameter, structural navigation is used which takes the relations of a graph into account. Navigating upwards with structural navigation will select the nearest parent node, according to the center x-coordinates of all parents.

Note: The navigation command will always consider the current layout orientation which can be set with command menu(layout(orientation(...))). So, down in a graph with left-to-right layout will go to the same node as left in a top-down layout of the same graph.

The returned answer is either the node the navigation command has moved to (which is the new current selection) or the former selection when this operation fails (e.g. by navigating upwards starting at the topmost node in a top-down layout).

menu(navigation(navigator))

Opens the navigator dialog window.

menu(navigation(find(string,boolean,boolean)))

-> Returns answer node_selections_labels(...)!

Searches for a node with text string. The node text is the value of the node attribute OBJECT in the term representation. The first boolean parameter of the command is a flag to consider the case or not. If this parameter is false, then upper and lower case characters (e.g. 'A' and 'a') are not distinguished from eachother for the search. The second boolean parameter is a flag to use exact match or not. If this parameter is false, then for example the search string "Vin" will match a node with text "daVinci", otherwise not. If exactly one node is selected before using this commands, then search will start at this node. Otherwise, the search will start at the leftmost and topmost node (for top-down layouts).

The returned answer is either the first node found by the search operation (which is the new current selection) or the former selection when this operation fails (e.g. when there is no node in graph that matches the string).

menu(navigation(find))

Opens the find dialog window.

Abstraction Menu Category:

The commands of the abstraction category are responsible for hiding particular details in a graph visualization. An abstraction does not manipulate the internal graph structure, it only has a temporary influence on the visualization of the graph. At the moment, there are two abstractions implemented in daVinci: Subgraph and edge hiding. After hiding subgraphs or edges, it will be possible to undo these operations later. The abstraction of a particular node can be undone with the show... commands of this category. All abstractions can be undone in one step using the restore... commands. The abstraction category is the API equivalent of the Abstraction menu of the user interface.

menu(abstraction(hide_subgraph(node_ids)))

Hides the subgraphs of the nodes specified by node_ids. This abstraction removes all children of a specified node from the drawing that can only be reached by starting at the specified node. The hiding process stops as soon as there is a node with an additional parent which is not hidden at the same time. Nodes on which this abstraction is applied are visualized with an icon showing a pair of scissors. node_ids of already hidden nodes can be used here, but of course this will have no effect.

menu(abstraction(show_subgraph(node_ids)))

Undoes a subgraph abstraction for the nodes specified by node_ids. node_ids of already shown nodes can be used here, but of course this will have no effect.

menu(abstraction(restore_all_subgraphs))

Undoes all subgraph abstractions in the graph in one step.

menu(abstraction(hide_edges(node_ids)))

Hides the edges of the nodes specified by node_ids. This abstraction removes all incoming and outgoing edges of a specified node from the drawing. Nodes on which this abstraction is applied are visualized with a surrounding rectangular border. node_ids of already hidden nodes can be used here, but of course this will have no effect.

menu(abstraction(show_edges(node_ids)))

Undoes an edge abstraction for the nodes specified by node_ids. node_ids of already shown nodes can be used here, but of course this will have no effect.

menu(abstraction(restore_all_edges))

Undoes all edge abstractions in the graph in one step.

Layout Menu Category:

The commands of the layout category are manipulating the layout of a graph. There are commands to start the layout algorithm (i.e. edge crossing minimization), to move nodes closer together, and to set the orientation of a graph layout. The layout category is the API equivalent of the Layout menu of the user interface.

menu(layout(improve_all))

This command starts the layout algorithm to improve the visualization quality for the whole graph by minimizing edge crossings and edge bends. Processing this algorithm may take a lot of time, depending on the size of the graph and the accuracy of the layout algorithm which can be set by using command set(layout_accuracy(...)). This is the reason for not applying the layout algorithm initially after loading a graph. The user or the application has to do this on its own.

menu(layout(improve_edges))

Same as command menu(layout(improve_all)) above, but this command optimizes only the dummy nodes (i.e. it calculates a better edge routing. The order of the regular nodes on the levels is left unchanged.

menu(layout(improve_selected))

Same as command menu(layout(improve_all)) above, but this command optimizes only the currently selected regular nodes and the dummy nodes of the graph. The order of all other nodes is left unchanged.

menu(layout(improve_nodes(node_ids)))

Same as command menu(layout(improve_selected)) above, but this command uses the nodes supplied in the parameter instead of the selected nodes.

menu(layout(improve_spacing))

Calculates a new layout by moving the nodes closer together if possible. Usually, one will use this operation after hiding subgraphs with command menu(abstraction(hide_subgraph(...))) to get a more compact graph layout.

menu(layout(orientation(orientation)))

Sets the layout orientation of a graph, according to parameter orientation. The default orientation is top-down, where root nodes of the graph are drawn at the top and edges are leading downwards. The other three directions bottom-up, left-to-right and right-to-left are supported as well.

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