Menu Commands
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.
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).
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.
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.
|