API Answers
API Answers
For background information about the answers described on this page,
refer to the
information about API answers
in the corresponding section of the API reference.
On this page, all answers of the uDraw(Graph) API are described. These
answers are sent back to an application program connected to the API.
Click here to get an
overview of all API answers.
ok
This answer is returned by the API to confirm the successful execution
of a command that was sent to the API.
Exceptions: the
commands listed here
do not return ok, they return another answer instead.
If the execution of a command has failed, then answer
communication_error(...)
is sent instead of "ok".
For synchronization, "ok" is also sent to the application at
initialization time
after the application has been successfully connected to uDraw(Graph).
communication_error(string)
This answer is returned by the API to inform about a failure regarding the
previous command.
In parameter "string", the application can find an error message describing
the reason for the failure.
Usually, an exception like this should not happen when the application
meets all rules and restrictions of the commands sent to the API.
node_selections_labels(node_ids)
This answer is returned by the API to inform the application about selection
of nodes in the graph after using the following API commands:
Further, answer "node_selections_labels(...)" is sent to the application
as an event after the user has selected a set of nodes in the graph
visualization.
In the parameter "node_ids" of the answer, the application can find the
identifiers of all nodes that are currently selected.
These identifiers are specified in the
term representation
of the graph.
Many nodes can be selected in uDraw(Graph) at a time, so the parameter of the answer
is a list of identifiers.
The list is empty when the user has deselected all nodes.
After loading a graph, no node is selected by default.
node_double_click
This answer is returned by the API after the user has selected a node twice
within a specific short time interval.
Note that the answer has no parameter because it refers to the previous node
selection.
So if the user clicks on a node with id "something" twice, then after the
first click uDraw(Graph) sends the answer node_selections_labels(["something"]).
When the second mouse click is detected within a short time interval,
uDraw(Graph) will send answer node_double_click to inform that the last selection
was a double click.
edge_selection_label(edge_id)
This answer is returned by the API to inform the application about selection
of one edge in the graph after using the following API command:
Further, answer "edge_selection_label(...)" is sent to the application
as an event after the user has selected an edge in the graph
visualization.
In the parameter "edge_id" of the answer, the application can find the
identifier of the edge that is currently selected.
This identifier is specified in the
term representation
of the graph.
Unlike nodes, only one edge can be selected at a time in uDraw(Graph),
so the parameter of this answer is not a list.
This is an obsolete alternative form of answer
edge_selection_label(...),
see above.
It is still available for backward compatibility in case of
loading an old graph that does not have edge IDs.
These IDs were recommended in previous V1.x versions, but not
required.
Since V2.x, these IDs are mandatory.
Your application should be able to handle answer
"edge_selection_labels(...)".
The first parameter "node_id" is the parent and the second "node_id"
is the child node of the currently selected edge.
edge_double_click
This answer is returned by the API after the user has selected an
edge twice within a specific short time interval.
Note that the answer has no parameter because it refers to the
previous edge selection.
So if the user clicks on an edge with id "something" twice, then
after the first click uDraw(Graph) sends the answer
edge_selection_label(["something"]).
When the second mouse click is detected within a short time
interval, uDraw(Graph) will send answer edge_double_click to
inform that the last selection was a double click.
menu_selection(menu_id)
This answer is returned by the API to inform the application
about selection of an application menu.
The application program is able to attach its own menu entries
to uDraw(Graph) using either
user interface extension
or
configuration.
The "menu_id" found in the parameter of this answer
is the identifier specified at creation time of the selected
menu.
The application is also able to
control the uDraw(Graph) "File" menu using command
app_menu(control_file_events).
In this case, answer "menu_selection(...)" is also used to
inform the application about selection events in the "File"
menu.
Make sure to read the
recommended actions
in order to be able to handle this events correctly.
icon_selection(icon_id)
This answer is returned by the API to inform the application
about selection of an application icon.
The application program is able to attach its own menu icons
to uDraw(Graph) using either
user interface extension
or
configuration.
The "icon_id" found in the parameter of this answer
is the identifier specified at creation time of the selected
icon.
This answer is returned by the API to inform the application
about selection of a pop-up menu of a node.
The application program is able to attach its own individual
pop-up menu entries to each node by setting the
pop-up menu attribute.
The "node_id" found in the parameter of this answer is the
identifier of the node where the pop-up menu was selected.
The "menu_id" is the identifier specified at creation time of
the selected menu.
This answer is returned by the API to inform the application
about selection of a pop-up menu of an edge.
The application program is able to attach its own individual
pop-up menu entries to each edge by setting the
pop-up menu attribute.
The "edge_id" found in the parameter of this answer is the
identifier of the edge where the pop-up menu was selected.
The "menu_id" is the identifier specified at creation time of
the selected menu.
This answer is sent by the API only in
multi-graph mode.
It is used to specify the context (i.e. graph) where the
event happened.
The event answer itself will be sent afterwards with the following
answer, see concept of
two answers in multi-graph mode
The "context_id" found in the parameter of the answer is the
context identifier which has been assigned at creation time
using the commands
multi(new_context)
or
multi(open_context).
The identifier can be used with command
set_context(...)
to set the context (graph) affected by subsequent commands.
If your application does not want to deal with more than one
graph at a time, i.e. when it does not enter the multi-graph mode
by opening a first context, then it will never receive the
context answers.
This answer is sent by the API only in
multi-window mode.
It is used to specify the context (i.e. graph) and window where
the event happened.
The event answer itself will be sent afterwards with the following
answer, see concept of
two answers in multi-window mode
The "context_id" found in the first parameter of the answer is the
context identifier which has been assigned at creation time
using the commands
multi(new_context)
or
multi(open_context).
The "window_id" in the second parameter is automatically assigned
by uDraw(Graph).
It is passed to the application with the preluding answer of
answer
open_window
at the time when a new base window is opened.
open_window
This answer is returned by the API only in
multi-window mode
to inform the application about a new base window in a
context (graph).
This is done to confirm the following API commands:
Further, this answer is sent to the application as an event
after the user has opened a new base window.
The window ID is automatically assigned by uDraw(Graph)
and can be taken from the preluding
context_window(...)
answer that has been sent directly before this answer.
This answer is returned by the API only in
multi-window mode
as an event after the user has closed a base window.
The window ID parameter is the identifier of the closed window.
After closing a window, the window ID cannot be used any further.
Afterwards, the application has to open a new window or specify
one of the remaining windows to be the new current window in the
context.
All other commands will be ignored, because after closing, the
current window will be undefined as long as a new one is not
specified.
This answer is returned by the API to pass results or
information from
Tcl/Tk scripts
back to the application.
These scripts can be sent to the uDraw(Graph) Tcl/Tk interface
by using the following API commands:
Both commands return "tcl_answer(...)" for confirmation rather than
the usual "ok" answer.
The string in this answer is the return value of the Tcl/Tk script
after finishing execution.
uDraw(Graph) is blocked while executing these scripts.
On the other hand, "tcl_answer(...)" may also occur as an event at
any time.
The uDraw(Graph) Tcl/Tk interface offers the opportunity to
send arbitrary messages back to the application via the API by using
a special Tcl-command inside of a Tcl/Tk script.
These messages are forwarded by uDraw(Graph) to the application with
API-answer "tcl_answer(...)".
This answer is returned by the API to confirm the API command
window(file_browser(...)).
uDraw(Graph) is blocked until the user has closed the file browser.
In the first string parameter you can find the chosen (absolute)
filename and the second string contains the last setting of the
type menu in the file browser.
Both strings of the answer are empty when the user has canceled
the browser.
create_node
This answer is returned by the API only in
drag and drop mode
to inform the application that the user has released the middle
mouse button over a free area and that no node was selected when
the middle mouse button was pressed before.
The coordinates where the mouse button is released are stored
internally in uDraw(Graph) and can be reused when the commands
drag_and_drop(new_node_at_coord(...))
or
drag_and_drop(new_node_and_edge_at_coord(...))
are sent to the API.
The recommended behavior to react on this event is to insert a
new node at the mouse position by using
the command
drag_and_drop(new_node_at_coord(...)).
create_node_and_edge(node_id)
This answer is returned by the API only in
drag and drop mode
to inform the application that the user has released the middle
mouse button over a free area and that the node with the given
"node_id" was selected when the middle mouse button was pressed
before.
The coordinates where the mouse button is released are stored
internally in uDraw(Graph) and can be reused when the commands
drag_and_drop(new_node_at_coord(...))
or
drag_and_drop(new_node_and_edge_at_coord(...))
are sent to the API.
The recommended behavior to react on this event is to insert a
new node at the mouse position that is connected to the existing
node supplied in the parameter "node_id" with a new edge by using
the command
drag_and_drop(new_node_and_edge_at_coord(...)).
This answer is returned by the API only in
drag and drop mode
to inform the application that the user has released
the middle mouse button over a node (second "node_id")
and that the node with the first "node_id" was selected
when the middle mouse button was pressed before.
The recommended behavior to react on this event is to insert
a new edge between the first and the second node by using
command
graph(update(...)).
This answer is returned by the API only in
drag and drop mode
to inform the application that the user has released
the middle mouse button over a node (second "node_id")
or free area (second "node_id" is empty, i.e. "")
and that a node (first "node_id") was selected when
the middle mouse button was pressed together with the
SHIFT-Key.
The coordinates where the mouse button is released are stored
internally in uDraw(Graph) and can be reused when the commands
drag_and_drop(new_node_at_coord(...))
or
drag_and_drop(new_node_and_edge_at_coord(...))
are sent to the API.
The second ("context_id") and third parameter ("window_id")
belong to the first "node_id" and specify the origin of the
drag and drop operation.
The destination is the second "node_id". Its context and
window ID can be taken from the preluding
context_window(...)
answer.
There is no recommended behavior to react on this event.
disconnect
This answer is returned by the API after the user has selected menu
File/Disconnect.
When this event happens, the application is obliged to terminate,
so the user is able to connect another application to the API.
Disconnection is only possible when uDraw(Graph) has established the
API connection, e.g. by using menu
File/Connect Application...
or command-line option
-startappl.
close
This answer is returned by the API only in
multi-graph mode.
or
multi-window mode
to inform the application that the current context (i.e. graph) has
been closed.
This can be done either by the application itself using API command
menu(file(close))
or by the user with menu
File/Close.
After closing a context, the corresponding graph and all of its views
(base windows) will be removed and the corresponding context ID
cannot be used any further.
Afterwards, the application has to open a new context or specify one
of the remaining contexts to be the new current context.
All other commands will be ignored, because after closing, the current
context will be undefined as long as a new one is not specified.
So answer "close" is either sent as result to confirm command
menu(file(close))
or as an event at any time if the user has selected menu
File/Close
in the last open view of a context.
If it is not appropriate to allow that the user can close a context
on his own, then the application can
control the events of the File menu
to interpose before the context is actually closed.
The context ID of the closed context can be taken from the preluding
context(...)
answer (or
context_window(...)
answer in multi-window mode)
that was sent directly before.
quit
This answer is sent by the API on termination, e.g. when the user has
selected menu
File/Exit.
At this time, the application should stop sending further commands
to the API.
If it is not appropriate to allow the user to exit
uDraw(Graph) on his own, then the application can
control the events of the File menu
to interpose before uDraw(Graph) is actually terminated.
This answer is sent by the API on command
special(version).
In parameter "string", the application can find a description of the version of uDraw(Graph).
For more information see
special(version).
|