Overview -> Reference -> API Reference -> All Answers

daVinci API Definition - Answers

On this page, all answers of the daVinci API are described. These answers are sent back to an application connected with the API. An overview of all answers is also available.

Answers at Initialization Time:

daVinci can be connected with an application program either by starting daVinci from the application process with option -pipe or by starting the application from the daVinci process using menu File/Connect Application... or option -startappl, refer to page How to Connect an Application for details. After connecting daVinci with the application, an initial answer ok is sent to the application to signal preparedness for receiving commands. An application should not start sending commands to daVinci before receiving the inital ok as the first answer from the API.

Answers for confirming API Commands:

In general, commands sent to the API will be confirmed with an answer ok after the command was executed successfully. All commands that do not return ok are listed below. If an error occured while executing a command, daVinci will send answer communication_error(...) instead of ok. Usually, this exception should not happen in a running system, if 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(...).

Commands that do not return the ok answer are:

menu(file(close)): Returns close
menu(navigation(select_parents(...))): Returns node_selections_labels(...)
menu(navigation(select_siblings(...))): Returns node_selections_labels(...)
menu(navigation(select_children(...))): Returns node_selections_labels(...)
menu(navigation(navigator(...))): Returns node_selections_labels(...)
menu(navigation(find(...))): Returns node_selections_labels(...)
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(...)

In multi-window mode, the following two commands don't answer open_window instead of ok:

Answers for Event Notification:

The rest of the answers may occur at any time. These are event notifications which are triggered by the user. A daVinci 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 following events may be sent by the API:

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(...): An edge has been selected in the graph.
edge_selection_labels(...): Obsolete answer for compatibility to daVinci V1.x API.
edge_double_click: The previously selected edge has been clicked twice.
menu_selection(...): An application menu entry of the Edit menu has been selected.
icon_selection(...): An application icon of the icon bar has been selected.
popup_selection_node(...): A popup-menu for a node has been selected.
popup_selection_edge(...): A popup-menu for an edge has been selected.
tcl_answer(...): Return value from a Tcl/Tk script sent to daVinci.
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: daVinci has terminated.
open_window: User opened a window in multi-window mode.
close_window(...): User closed a window in multi-window mode.

VERY IMPORTANT: Due to the strange effects of asynchronous communication, an event must also be expected by the application after sending a command to the API and before receiving the corresponding confirmation answer! daVinci guarantees that events are not propagated during execution of an API command, but if the event occured during transfer time of the command (i.e. after it is sent by the application and before it is received by the API), then the event answer may interfere and will arive 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 should accept events at any time!

Answers in Multi-Graph Mode:

If an application is leaving the default single-graph mode to enter the multi-graph mode, then the behaviour for confirming commands and sending event notification will slightly change. In multi-graph mode, all answers from daVinci always have a preluding answer context(...) to specify the context (graph) where the event 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 itself.

Answers in Multi-Window Mode:

If an application is leaving the default single-graph mode to enter the multi-window mode by setting the command-line option -window_api, then the behaviour for confirming commands and sending event notification will slightly change. In multi-window mode, all answers from daVinci always have a preluding answer context_window(...) to specify the context (graph) and window where the event happened. So, in multi-window mode, an application will always get two answers instead of one: The first one is the context/window and the second one is the event itself. Additionally the answers of the commands menu(view(open_new_view)) and menu(view(open_survey_view)) change to open_window instead of ok.

Documentation of all API Answers:

ok

This answer is returned by the API to confirm the successful execution of a command sent to the API. Exceptions: The commands listed above 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 of the API after the application is successfully connected with daVinci.

communication_error(string)

This answer will be returned by the API after the execution of an API command has failed. In the string parameter, the application can find an error message describing the reason for the failure. Usually, such an exception cannot happen if the application meets all rules and restrictions of the commands sent to the API.

node_selections_labels(node_ids)

Answer node_selections_labels(...) is returned by the API to inform the application about selection of nodes in the graph. This is done to confirm the following API commands:

Further, answer node_selections_labels(...) will be 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 which are currently selected. These identifiers are specified in the term representation of the graph. Note: Many nodes may be selected in daVinci at a time which is reflected by the list of identifiers returned by this answer. The list will be empty if the user has deselected all nodes. After loading a graph, no node will be selected by default.

node_double_click

This answer will be 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 last node selection. So, if the user clicks on a node with node_id "something" twice, then after the first click daVinci will send answer node_selections_labels(["something"]). If the second mouse click will be detected within the time interval, then daVinci will send answer node_double_click to inform that the last selection was a double click.

edge_selection_label(edge_id)

Answer edge_selection_label(...) is returned by the API to inform the application about selection of a single edge in the graph. This is done to confirm the following API command:

special(select_edge(...))

Further, answer edge_selections_label(...) will be 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 which is currently selected. This identifier is specified in the term representation of the graph. Note: Unlike nodes, there can only be one edge selected at a time in daVinci, so the parameter of this answer is not a list.

edge_selection_labels(node_id,node_id)

This is an obsolete alternative of answer edge_selection_label(...) to inform an application about selection of an edge, too. This answer is present in the V2.x API for backward compatibility. The first node_id parameter of the answer is the parent and the second node_id is the child node of the currently selected edge. Read the description of answer edge_selection_label(...) above for details about edge selection.

Note: This is an obsolete answer which is only used if the selected edge has no specified edge_id in the graph. In previous V1.x releases of daVinci, edge_id's were recommended, but not required for the term representation of a graph. In daVinci V2.x, an edge_id is now mandatory for all edges. This obsolete answer will be supported for some time to ensure backward compatibility.

edge_double_click

This answer will be 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 last edge selection. So, if the user clicks on an edge with edge_id "something" twice, then after the first click daVinci will send answer edge_selection_label(["something"]). If the second mouse click will be detected within the time interval, then daVinci 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 daVinci's Edit menu by using the API command app_menu(create_menus(...)). The menu_id, found in the parameter of this answer, is the identifier specified at creation time of the selected menu.

If the application would like to have a closer integration of I/O by taking control on the events of the daVinci File menu events, then it is able to do so by 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. Click here to get more information about controlling events of the File menu and the recommended actions to handle these events.

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 icons to the application plane of daVinci's icon bar by using the API command app_menu(create_icons(...)). 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 popup menu of a node. The application program is able to attach its own menu entries to each node by setting the popup-menu attribute. The node_id, found in the parameter of this answer, is the node identifier of the node over which the right mouse button was pressed and the menu was selected. The menu_id, found in the parameter of this answer, 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 popup menu of an edge. The application program is able to attach its own menu entries to each edge by setting the popup-menu attribute. The edge_id, found in the parameter of this answer, is the edge identifier of the edge over which the right mouse button was pressed and the menu was selected. The menu_id, found in the parameter of this answer, is the identifier specified at creation time of the selected menu.

context(context_id)

This answer is returned by the API only in multi-graph mode to specify the context (i.e. graph) where an event happened. The event answer itself will be sent afterwards. The context_id, found in the parameter of answer context(...), is the context identifier which has been assigned at creation time (by using commands multi(new_context) or multi(open_context(...))). If your application does not want to deal with more than one graph at a time, i.e. when it does not enter multi-graph mode by opening a context, it will never receive the context answers.

In multi-graph mode, each answer of the API sent back to the application has always a preluding context(...) answer to specify the context where the event happened. So in fact daVinci sends two answers at a time. Read above for details.

context_window(context_id,window_id)

This answer is returned by the API only in multi-window mode to specify the context (i.e. graph) where an event happened. The event answer itself will be sent afterwards. The context_id, found in the parameter of answer context_window(...), is the context identifier which has been assigned at creation time (by using commands multi(new_context) or multi(open_context(...))). The window_id found in the parameter of answer context_window(...), is the window identifier, which is automatically assigned by daVinci if the user opens a new base window. You'll be informed about the window identifier the first time, if you get the answer open_window. If your application does not want to deal with more than one graph at a time, i.e. when it does not enter multi-window mode by opening a context, it will never receive the context_window answers.

In multi-window mode, each answer of the API sent back to the application has always a preluding context_window(...) answer to specify the context and window where the event happened. So in fact daVinci sends two answers at a time. Read above for details.

open_window

This answer is returned by the API only in multi-window mode to inform the application about a new open base-window for a context (graph). This is done to confirm the following API commands:

Further this answer will be sent to the application as an event after the user has opened a new base-window. The window_id which is automatically assigned to the new window, can be taken from the preluding context_window(...) answer which is sent prior to each answer in multi-window mode.

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 needs to open a new window or specify one of the remaining windows to be the new current window. 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 informations from Tcl/Tk scripts back to the application. These scripts can be sent to the daVinci Tcl/Tk interface by using the following API commands:

Both commands return a 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. The whole daVinci user interface is disabled as long as a Tcl-script is executed.

On the other side, tcl_answer(...) may also occur as an event at any time. The daVinci Tcl/Tk interface offers the opportunity to send arbitrary messages back to the application via the API by using the Tcl-command daVinci tcl_answer <string> inside a Tcl/Tk script. These messages are forwarded by daVinci to the connected application with an API-answer tcl_answer(...).

browser_answer(string,string)

This answer is returned by the API to confirm the API command window(file_browser(...)). In the two parameters of the answer, the application can find the results of the file browser, i.e. the file and type the user has choosen. The first string of the parameters is the selected (absolute) file name and the second string is the choosen file type which is one of the first elements (i.e. the plain text of the type) of the three-tuples in the btypes list used as parameter for the window(file_browser(...)) command. Both strings of the answer are empty if the user has canceled the browser.

create_node

This answer is returned by the API to inform the application if the user released the middle mouse button over the free area and if no node was selected when the middle mouse button was pressed in drag and drop mode. The coordinate at which the mouse button is released is stored internally in daVinci and is reused if the API command drag_and_drop(new_node_at_coord(...)) or drag_and_drop(new_node_and_edge_at_coord(...)) is received. The recommended behaviour to react on this event is to insert a new node at the mouse position by using drag_and_drop(new_node_at_coord(...)).

create_node_and_edge(node_id)

This answer is returned by the API to inform the application if the user released the middle mouse button over the free area and if a node was selected when the middle mouse button was pressed in drag and drop mode. The coordinate at which the mouse button is released is stored internally in daVinci and is reused if the API command drag_and_drop(new_node_at_coord(...)) or drag_and_drop(new_node_and_edge_at_coord(...)) is received. The parameter node_id of the event is the identifier of the node which was selected when the middle mouse button was pressed. The recommended behaviour 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 with a new edge by using drag_and_drop(new_node_and_edge_at_coord(...)).

create_edge(node_id,node_id)

This answer is returned by the API to inform the application if the user released the middle mouse button over a node and if a node was selected when the middle mouse button was pressed in drag and drop mode. The first parameter node_id of the event is the identifier of the node which was selected when the middle mouse button was pressed. The second parameter node_id of the event is the identifier of the node which was selected when the middle mouse button was released. The recommended behaviour to react on this event is to insert a new edge between the two nodes by using graph(update(...)).

drop_node(node_id,context_id,window_id,node_id)

This answer is returned by the API if the user released the middle mouse button over a node or the free area and if a node was selected when the middle mouse button was pressed together with the Shift-Key in drag and drop mode. The coordinate at which the mouse button is released is stored internally in daVinci and is reused if the API command drag_and_drop(new_node_at_coord(...)) or drag_and_drop(new_node_and_edge_at_coord(...)) is received. The first parameter node_id of the event is the identifier of the node which was selected when the middle mouse button was pressed. The second parameter context_id of the event is the identifier of the context (graph) of the node specified in the first parameter. The third parameter window_id of the event is the identifier of the window of the node specified in the first parameter (this parameter is only usefull in multi-window mode). The fourth parameter node_id of the event is the identifier of the node which was selected when the middle mouse button was released or "" if it was released over the free area. The context_id (and the window_id) of the node specified in the fourth parameter can be taken from the preluding context(...) answer which is sent prior to each answer in multi-graph mode or from the preluding context_window(...) answer which is sent prior to each answer in multi-window mode. There is no recommended behaviour to react on this event.

disconnect

This answer will be returned by the API after the user has selected menu File/Disconnect. When this event happens, the application is obliged to terminate. daVinci V2.x is reentrant (in opposite to previous V1.x releases), so the daVinci process will not die after the application has terminated. With this feature, the user has the opportunity to connect another application after disconnecting the old one.

Disconnecting is only available if daVinci has established the pipe connection to the application before, e.g. by using menu File/Connect Application... or option -startappl. On the other side, if daVinci has been started by the application program, then disconnecting is not possible, so the disconnect answer will never be sent in this situation.

close

The answer close will be returned by the API only in multi-graph or multi-window mode to inform the application that the current context (i.e. graph) has been closed. This can either be done 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 view windows will be removed and its context_id cannot be used any further. Afterwards, the application need 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 window of a context. If it is not appropriated to allow that the user is able to 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 which is sent prior to each answer in multi-graph mode or from the preluding context_window(...) answer which is sent prior to each answer in multi-window mode. (read above for details).

quit

This answer is sent by the API on termination, e.g. if the user has selected menu File/Exit. At this time, the daVinci process is going to die and the application should stop sending any further command to the API. If it is not appropriated to allow that the user is able to exit daVinci on his own, then the application can control the events of the File menu to interpose before daVinci is actually terminated.

daVinci V2.1 Online Documentation - Page update: June 15, 1998