Information about API Answers

Answer at initialization time

uDraw(Graph) can be connected to an application program using several options, refer to page How to connect an Application for details. After connecting uDraw(Graph) to the application, an initial answer ok is sent to the application to signal preparedness for receiving commands. An application must not start sending commands to uDraw(Graph) before receiving the initial "ok" as the first answer from the API.

Answers to confirm API commands

In general, commands sent to the API are confirmed by sending the answer ok back to the application after successfully executing the command. All commands that do not return "ok" are listed below. If an error occurred while executing the command, uDraw(Graph) will send the answer communication_error instead of "ok". Usually, this exception should not happen when the application meets all rules and restrictions of the API. The application can find the reason for the error in the string parameter of answer "communication_error(...)".

These are the API commands that do not return the "ok" answer:

menu(file(close)): returns close.
menu(navigation(select_parents(...))): returns node_selections_labels(...).
menu(navigation(select_parent(...))): returns node_selections_labels(...).
menu(navigation(select_siblings(...))): returns node_selections_labels(...).
menu(navigation(select_children(...))): returns node_selections_labels(...).
menu(navigation(select_child(...))): returns node_selections_labels(...).
menu(navigation(navigator(...))): returns node_selections_labels(...).
menu(navigation(find(...))): returns node_selections_labels(...).
menu(window(file_browser(...))): returns browser_answer(...).
tcl(eval(...)): returns tcl_answer(...).
tcl(eval_file(...)): returns tcl_answer(...).
special(select_nodes(...)): returns node_selections_labels(...).
special(select_edge(...)): returns edge_selection_label(...).
special(version): returns version(...).

In multi-window mode, the following commands answer open_window instead of ok:

Answers to notify events

Beside the answers used to confirm a command sent to the API, some answers may occur at any time. These are notifications for events that are triggered by the user. A uDraw(Graph) application must be prepared to receive these answers at any time, even in the time interval between sending a command and receiving the corresponding confirmation answer. The API sends the following events:

node_selections_labels(...): Some nodes have been selected in the graph.
node_double_click(...): The previously selected node has been clicked twice.
edge_selection_label(...): One edge has been selected in the graph.
edge_selection_labels(...): Obsolete, for compatibility with previous V1.x versions.
edge_double_click(...): The previously selected edge has been clicked twice.
menu_selection(...): A menu entry added by the application has been selected.
icon_selection(...): An icon entry added by the application has been selected.
tcl_answer(...): Return value from a Tcl/Tk script sent to uDraw(Graph).
popup_selection_node(...): An entry in the pop-up menu of a node has been selected.
popup_selection_edge(...): An entry in the pop-up menu of an edge has been selected.
create_node(...): Create a new node in drag and drop mode.
create_node_and_edge(...): Create a new node and edge starting at a parent in drag and drop mode.
create_edge(...): Create a new edge between two nodes in drag and drop mode.
drop_node(...): Drop a node on another node in drag and drop mode.
disconnect(...): The user has selected menu File/Disconnect Application.
close(...): In multi-graph mode, the current context has been closed.
quit(...): uDraw(Graph) has terminated.
open_window(...): User has opened a new base window in multi-window mode.
close_window(...): User has closed a base window in multi-window mode.

VERY IMPORTANT: Due to the strange effects of asynchronous communication caused by message delays, an event must also be expected by the application after sending a command to the API and before receiving the corresponding confirmation answer! uDraw(Graph) guarantees that event answers are not propagated during execution of an API command, but if the event occurs during transfer time of the command (i.e. after it has been sent by the application and before it has been received by the API), then the event answer may interfere and will arrive at the application side in the time interval after sending the command and before receiving the corresponding confirmation answer. So never expect that the confirmation answer will come back directly after sending an API command. Your application must accept event answers at any time!

Answers in Multi-Graph Mode

When uDraw(Graph) has left the default single-graph mode to enter the multi-graph mode, the behavior for confirming commands and sending event notifications will slightly change. In multi-graph mode, all answers from uDraw(Graph) will always have a preluding answer context(...) to specify the context (graph) where the following answer happened. So in multi-graph mode, an application will always get two answers instead of one: The first one is the context and the second one is the event or confirmation answer.

Answers in Multi-Window Mode

In the multi-view mode where the user (or the application) has opened additional views (base windows) to the graph, the application is unable to access each individual view. To solve this restriction, you can use the multi-window mode by using command-line option -window_api. Here, the behavior of sending two answers with each confirmation or event is the same, but instead the preluding answer context_window(...) is used where the application can find an additional window ID. Further, the commands menu(view(open_new_view)) and menu(view(open_survey_view)) return the confirmation answer open_window instead of the usual ok that is sent by these commands when the multi-window mode is not active.