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:

special(select_edge(...))

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.

edge_selection_labels(node_id,node_id)

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.

popup_selection_node(node_id,menu_id)

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.

popup_selection_edge(edge_id,menu_id)

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.

context(context_id)

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.

context_window(context_id,window_id)

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.

close_window(window_id)

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.

tcl_answer(string)

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(...)".

browser_answer(string,string)

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(...)).

create_edge(node_id,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 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(...)).

drop_node(node_id,context_id,window_id,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 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.

version(string)

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