Commands that do not return the ok answer are:
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:
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:
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.0.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.
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:
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.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 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.