[Contents] [Intro] [Reference] [Tutorial] [Questions [New [Index]
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:

After daVinci has been connected by an application, i.e. if it has been started with
option -pipe and if it is the child process of the application (refer to page How to Connect an Application for details), an initial answer ok will be send to the application at start-up time to signal preparedness for receiving commands. An application should not send commands to the API before receiving the inital ok. This initialization answer is not sent if daVinci connects the application on its own, e.g. by using menu File/Connect Application... or option -startappl.

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:

  1. menu(file(close)): Returns close
  2. menu(navigation(select_parents(...))): Returns node_selections_labels(...)
  3. menu(navigation(select_siblings(...))): Returns node_selections_labels(...)
  4. menu(navigation(select_childs(...))): Returns node_selections_labels(...)
  5. menu(navigation(navigator(...))): Returns node_selections_labels(...)
  6. menu(navigation(find(...))): Returns node_selections_labels(...)
  7. window(file_browser(...)): Returns browser_answer(...)
  8. tcl(eval(...)): Returns tcl_answer(...)
  9. tcl(eval_file(...)): Returns tcl_answer(...)
  10. special(select_nodes(...)): Returns node_selections_labels(...)
  11. special(select_edge(...)): Returns edge_selection_label(...)

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, except of the time interval between sending a command and receiving the corresponding
confirmation answer:
  1. node_selections_labels(...): Some nodes have been selected in the graph.
  2. node_double_click: The previously selected node has been clicked twice.
  3. edge_selection_label(...): An edge has been selected in the graph.
  4. edge_selection_labels(...): Obsolete answer for compatibility to daVinci V1.x API.
  5. edge_double_click: The previously selected edge has been clicked twice.
  6. menu_selection(...): An application menu entry of the Edit menu has been selected.
  7. icon_selection(...): An application icon of the icon bar has been selected.
  8. tcl_answer(...): Return value from a Tcl/Tk script sent to daVinci.
  9. disconnect: The user has selected menu File/Disconnect Application.
  10. close: In multi-graph mode, the current context has been closed.
  11. quit: daVinci has terminated.

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.

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.

ok is also sent to the application at initialization time if daVinci is started with option -pipe.

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: 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.0 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.0, 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.

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.

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.

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.0 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 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 confirmed with an error message, 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 (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.0 Online Documentation - Page update: Jun 13, 1996