API Menu Commands

On this page, API commands of the menu category are described. This category covers all commands to call the functions of the pull-down menus which are available in the uDraw(Graph) base window. The commands of this category are enclosed by keyword "menu(...)". The menu commands are further divided into subcategories with respect to the menu they belong to, so for example you can find the functions of menu File in the "menu(file(...))" subcategory, and so on. Here is a list of all subcategories 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 uDraw(Graph) process. The file category is the equivalent API function of the File menu in the user interface.

menu(file(new))

Removes the current graph and clears the base window.

menu(file(open_graph(filename)))

To load a new graph from file. The parameter "filename" specifies an existing file containing a uDraw(Graph) graph in term representation format. After loading a graph this way, the layout algorithm for edge crossing reduction is not started automatically. You can either do this later using command menu(layout(improve_all)) or by combining both steps with command menu(file(open_graph_placed(...))) to avoid that the intermediate layout before edge crossing reduction is shown to the user. Alternatively, you can avoid file access by sending the graph in term representation format directly to the API with command graph(new(...)).

Note: Windows® users please use "/" (slash) instead of "\" (backslash) as a directory separator.

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 the layout algorithm to reduce edge crossings) in one step. The advantage of using this command rather than the two others is that the user will not see the intermediate graph visualization where the layout algorithm is not applied. The parameter "filename" specifies an existing file containing a uDraw(Graph) graph in term representation format. Alternatively, you can avoid file access by sending the graph in term representation format directly to the API with command graph(new_placed(...)).

Note: Windows® users please use "/" (slash) instead of "\" (backslash) as a directory separator.

menu(file(open_status(filename)))

To load a graph status from the specified file which was previously saved by uDraw(Graph). A status contains a graph with all layout information and user interface settings.

Note: Windows® users please use "/" (slash) instead of "\" (backslash) as a directory separator.

menu(file(save_graph(filename)))

Saves the current graph in term representation format to the specified file which should have the suffix ".udg". By choosing the term representation format, only the graph structure is stored and the layout information will be lost.

Note: Windows® users please use "/" (slash) instead of "\" (backslash) as a directory separator.

menu(file(save_status(filename)))

Saves the status of the current graph to the specified file which should have the suffix ".status". By choosing the status format, the graph structure will be stored as well as layout information and user interface settings.

Note: Windows® users please use "/" (slash) instead of "\" (backslash) as a directory separator.

menu(file(print(filename)))

Saves the current graph in PostScript® format to the specified file which should have the suffix ".ps". The generated file is EPSF compliant (encapsulated PostScript®) and can be printed either on a PostScript® printer or imported in suitable software. Refer for more information about the uDraw(Graph) PostScript® interface. The options of the PostScript® interface available in the print dialog window are not accessible using the API. This command will always use a PostScript® scale of 1:1 without centering.

Note: Windows® users please use "/" (slash) instead of "\" (backslash) as a directory separator.

menu(file(print_to_printer))

Similar to command menu(file(print(...))), but sends the graph to a PostScript® printer rather than saving it to a file. The print command used to access the printer can be set with command set(print(...)). Refer for more information about the uDraw(Graph) PostScript® interface. The options of the PostScript® interface available in the print dialog window are not accessible using the API. This command will always use the default page size and a PostScript® scale of 1:1 without centering.

menu(file(print))

Opens the print dialog window if a graph is loaded. Nothing will happen when no graph is loaded in the current context.

menu(file(export(boolean,string,filename)))

To export the current graph in a common graphics format to "filename". The whole graph is exported when "boolean" is "true", otherwise only the currently visible area of the graph is saved. The "string" parameter is used to specify the file format, either "gif", "tiff" or "png".

In order to use the export feature, it is necessary to have an open uDraw(Graph) base window which must not be covered by other windows. When using the export, uDraw(Graph) tries to raise the base window to bring it in front of all other windows (on Windows® platforms this might fail due to restrictions of the operating system). The export does not work when the base window is iconified or when uDraw(Graph) operates in the background without a user interface directly after starting the system with commandline option -nogui. In this case the API answer communication_error is sent. Make sure that the base window is visible in the front if you experience any problems with export.

Note: Windows® users please use "/" (slash) instead of "\" (backslash) as a directory separator.

menu(file(export))

Opens the export dialog window if a graph is loaded. Nothing will happen when no graph is loaded in the current context.

menu(file(close))

Note: This command returns the answer close instead of the usual answer ok!

To close the current context in multi-graph or multi-window mode. This will remove all base windows which are opened in 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 new current context using 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 the default single-graph mode. It is even possible to close the last context without quitting uDraw(Graph). After closing the last context, no window will be visible any longer, but the uDraw(Graph) process is still running in the background. In this situation, the application can open a new first context and a new base window will come back.

menu(file(exit))

To quit the system. This will terminate the uDraw(Graph) process.

View Menu Category

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

menu(view(open_new_view))

Note: When in multi-window mode, this command returns the answer multi-window mode instead of the usual answer ok!

Opens a new view of the current graph which is an additional base window showing the same graph, see multi-view mode). Each view of a graph is based on the same logical graph structure, so selection of a node or fine-tuning 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 in different contexts which show different graphs and are independent from each other. Multi-view is a feature of the user interface, so the application is unable to control multi-view windows, e.g. to close one particular view (base window). In the multi-view mode, the application can only open another view by using this API command without being able to control it later.

In multi-view mode, commands that are related to one specific window (e.g. setting the scale, focusing nodes or setting the window position) are always applied to the master view which is the oldest view in a context. To solve these restrictions, the multi-window mode has been introduced to be able to control all individual base windows (views) in a context. This mode is activated with command-line option -window_api. In the multi-window mode, this command returns the answer open_window rather than ok which is returned in multi-view mode. 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 by the application with command menu(file(close)). The user can open and close new views of a graph at any time.

menu(view(open_survey_view))

Note: When in multi-window mode, this command returns the answer open_window instead of the usual answer ok!

Same as command menu(file(open_new_view())), but opens a survey view with special properties. A survey view shows the whole graph in a reduced scale. The currently visible part of the master view is visualized with a blue rectangle. For the special features of the survey view, see the documentation of the corresponding operation in the user interface section.

menu(view(full_scale))

Sets the scale to 100%, so 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 where 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" which is a percent value that must be from 1 to 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 have to reduce the graph size without losing these details, then you can switch to a smaller font size with command set(font_size(...)) or you can reduce the gap between nodes with the commands 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 window if a graph is loaded. Nothing will happen when no graph is loaded in the current context.

menu(view(graph_info))

Opens the graph info dialog window if a graph is loaded. Nothing will happen when no graph is loaded in the current context.

menu(view(uDrawGraph_info))

Opens the uDraw(Graph) info dialog window.

Navigation Menu Category

The commands of the navigation category are used to change the selection, i.e. the set of currently selected nodes. There are commands to select the parent-, sibling- and child nodes for a given set of nodes or edges. Further, there are commands to navigate to related nodes and find particular nodes based on textual search. The navigation category is the equivalent API function of the Navigation menu in 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, any navigation command may fail, for example when there is no node that matches a particular string used in command menu(navigation(find(...))). A failed navigation command will not modify the current selection and will return the current (former) selection as result. So to see whether or not the command was successful, 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 set of nodes or one particular edge in the graph, then this category is obviously the wrong place (because nodes are not selected by menus, but with the mouse). Refer to the special category for commands to select particular nodes or an edge.

menu(navigation(select_parents(node_ids)))

Note: This command returns the answer node_selections_labels instead of the usual answer of ok!

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

menu(navigation(select_parent(edge_id)))

Note: This command returns the answer node_selections_labels instead of the usual answer ok!

Selects the parent node of the edge specified by parameter "edge_id". The returned answer is either a list with the parent (which is the new current selection) or the former selection when this operation has failed (i.e. when the edge has no parent).

menu(navigation(select_siblings(node_ids)))

Note: This command returns the answer node_selections_labels instead of the usual answer ok!

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

menu(navigation(select_children(node_ids)))

Note: This command returns the answer node_selections_labels instead of the usual answer ok!

Selects all of the child nodes of the nodes specified by parameter "node_ids". The returned answer is either the list of children (which is the new current selection) or the former selection when this operation has failed (i.e. when there are no children for the given nodes).

menu(navigation(select_child(edge_id)))

Note: This command returns the answer node_selections_labels instead of the usual answer ok!

Selects the child node of the edge specified by parameter "edge_id". The returned answer is either a list with the child (which is the new current selection) or the former selection when this operation has failed (i.e. when the edge has no child).

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

Selects the nearest neighbour node according to the given direction by starting at the specified node with ID "node_id". Geometrical navigation is used when the boolean parameter is "false". In this mode the relations given by the edges are ignored, so for example when the upward direction is used, one will navigate to the nearest node at the previous level. On the other side, when "true" is used for this parameter, structural navigation is used which takes the edges' relations into account. Navigating in upward direction with structural navigation will select the "nearest" parent node with respect to the center x coordinate of all parents.

Note 1: This command returns the answer node_selections_labels instead of the usual answer ok!

Note 2: The navigation command considers the current layout orientation that can be set with command menu(layout(orientation(...))). So "down" in a graph with a left-to-right layout will navigate to the same node as "left" in a top-down layout of the same graph. The answer of this command is either the node where the navigation command has moved to (which is the new current selection) or the former selection when this operation has failed (e.g. by navigating in upward direction starting at the nodes of the first level in a top-down layout).

menu(navigation(navigator))

Opens the navigator dialog window if a graph is loaded. Nothing will happen when no graph is loaded in the current context.

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

Note: This command returns the answer node_selections_labels instead of the usual answer ok!

To search for a node with text "string". The text of a node is the value of the node's attribute OBJECT in the term representation of the graph. The first "boolean" parameter of the command is a flag to show that the case shall be considered. Use "false" when upper and lower case letters (e.g. "A" and "a") shall be equal for the search. The second "boolean" parameter is a flag to show that an exact match shall be applied. Use "false" when a search string like "raw" shall match a node with text "uDraw(Graph)", for example. If exactly one node is selected before using this command, then the search starts 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 has failed (e.g. when there is no node in graph that matches the string).

menu(navigation(find))

Opens the find dialog window if a graph is loaded. Nothing will happen when no graph is loaded in the current context.

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 effect on the visualization of the graph. There are two forms of abstraction: subgraph abstractions and edge abstractions. Hidden subgraphs or edges can be restored for each individual node/edge with the "show..." commands or for all node/edges in one step with the "restore..." commands. The abstraction category is the equivalent API function of the Abstraction menu in the user interface.

menu(abstraction(hide_subgraph(node_ids)))

To hide the subgraphs of the nodes specified by "node_ids". Nodes that are already hidden are ignored. This kind of abstraction removes all children of a specified node from the visualization that can be exclusively reached by starting at the specified nodes. The hiding process stops as soon as there is a node with a parent that cannot be reached from "node_ids". For more information about subgraph abstractions see the documentation of the corresponding operation in the user interface section.

menu(abstraction(show_subgraph(node_ids)))

To undo a subgraph abstraction for the nodes specified by "node_ids". Nodes that are not hidden are ignored.

menu(abstraction(restore_all_subgraphs))

To undo all subgraph abstractions in the graph in one step.

menu(abstraction(hide_edges(node_ids)))

To hide the edges of the nodes specified by "node_ids". Nodes that are already hidden are ignored. This kind of abstraction removes all incoming and outgoing edges of the specified nodes from the visualization. For more information about edge abstractions see the documentation of the corresponding operation in the user interface section.

menu(abstraction(show_edges(node_ids)))

To undo an edge abstraction for the nodes specified by "node_ids". Nodes that are not hidden are ignored.

menu(abstraction(restore_all_edges))

To undo all edge abstractions in the graph in one step.

Layout Menu Category

The commands of the layout category are used to optimize the layout of a graph by arranging the nodes and edges. There are commands to start the graph layout algorithm with different options (i.e. edge crossing reduction), to move nodes closer together and to set the orientation of the graph layout. The layout category is the equivalent API function of the Layout menu in the user interface.

menu(layout(improve_all))

This command starts the layout algorithm to improve the visualization quality of the whole graph by reducing unnecessary edge crossings and edge bends. This is done by reordering all the nodes and dummy nodes. Processing this operation may take a long time, depending on the size of the graph and the accuracy of the layout algorithm that can be set with command set(layout_accuracy(...)). This is the reason why the layout algorithm is not applied automatically after loading a graph, so the user or the application are free to do this at any time.

menu(layout(improve_edges))

Similar to menu(layout(improve_all)), but here the command can only reorder dummy nodes in order to get a better routing of long span edges. The order of the regular nodes on the levels is not changed.

menu(layout(improve_selected))

Similar to menu(layout(improve_all)), but here the command can only reorder the nodes that are currently selected and the dummy nodes of their edges. The order of the remaining nodes is left unchanged.

menu(layout(improve_nodes(node_ids)))

Similar to menu(layout(improve_selected)), but this command reorders the nodes supplied in the parameter instead of the selected nodes.

menu(layout(improve_spacing))

Similar to menu(layout(improve_all)), but here the command keeps the order of node and dummy nodes, so only the relative position and distance between nodes may vary. This is especially useful after hiding nodes with command menu(abstraction(hide_subgraph(...))) to utilize the free space without losing the order of nodes.

menu(layout(orientation(orientation)))

To set the layout orientation in the graph according to parameter "orientation". The default orientation is top-down where the root nodes of the graph are at the top and edges are leading downwards. The other three directions are bottom-up, left-to-right and right-to-left.

Option Menu Category

The commands of the option menu category are used to open the option dialogs and to save the options. Individual options can be set with commands of the set category. The option category is the equivalent API function of the Options menu in the user interface.

menu(option(layout_algorithm))

Opens the layout algorithm dialog window.

menu(option(layout_settings))

Opens the layout settings dialog window.

menu(option(general_settings))

Opens the general settings dialog window.

menu(option(save))

Saves the current settings of the option dialogs for permanent use.