Overview ->
Reference ->
API Reference ->
Programmers Guide
daVinci API - Programmers Guide
This document is an overview of the API for programmers who want to connect
their application with daVinci.
Commands of the API
After connecting your application program with daVinci (section
"How to connect an Application"
explains this topic in detail), you can start sending commands
to the API. The
"Overview of Commands"
is a useful reference to browse the command syntax. The commands are
divided into eight categories with respect to their semantic. They are
build hierarchically with parenthesis according to the category they belong
to, e.g. command menu(file(exit)). The following categories are
available:
- graph(...)
The graph category covers commands to
send and update graphs. You can
send a complete graph in
term representation format
or update the structure of an already loaded graph by
adding and deleting nodes and edges.
Further, it is possible to
change the attributes
of nodes and edges
(more information about attributes).
Graph updates and attribute modifications
can be combined to be performed in one step.
- multi(...)
The multi-graph category covers commands to
work with many graphs in different windows at the same time. Commands are
available to
open a new context
(i.e. to get a new empty window, where an additional graph can be visualized).
Each context (graph) has its own unique context-ID. In multi-graph mode,
daVinci has a current context which can be
set with a command
of this category. The current context specifies
the graph that is currently affected by all the other commands sent to the
API. On the other side, in multi-graph mode, each answer from the API has a
preluding context answer to specify the graph where the event happened.
Multi-graph mode is entered as soon as the first context is opened. If you
intend to use more than one graph later in a session, you should open the
first context
at initialization time.
- menu(...)
The menu category covers commands to call
the menu functions of daVinci's user interface. All these commands
are further divided into sub-categories with respect to the menu they belong
to:
File,
View,
Navigation,
Abstraction, and
Layout.
- app_menu(...)
The application menu category covers
commands to let the application attach its own menus and icons to the
daVinci user interface.
Application menus
are always attached to the
Edit menu and
application icons
are placed on a separate plane of the
icon bar.
Application menus and icons, not applicable in the current state, should be
disabled by the application. This can be done with the
activation commands
which specify the currently enabled menus/icons, all the other menus/icons
will automatically be disabled this way. To interpose the I/O operations, the
application is able to
take control on daVinci's
file menu events, e.g. to store its own data structure when the user
selects the 'File/Save' menu in daVinci.
- set(...)
The set category covers commands to set the
options of daVinci which can also be done by the user with the
Option menu.
Commands are available to set the
accuracy
of the graph layout algorithm, to
keep the graph nodes
at their current level with the next start of the graph layout algorithm,
to specify
fontsize and
distances between nodes and edges
in the graph visualization (gap), to
control the scrolling
behaviour of
survey views,
to define the
animation speed
used for scrolling and to switch off the
pixmap cache when there is not
enough memory available.
- window(...)
The window category covers commands to
manipulate daVinci's base window. There are commands to set the
window title, to show
messages and
status informations in the
footer area, to set the window
position and
size, to
raise the window
(i.e. bring it to the front), and to
iconify or
deiconify it.
With the commands
deactivate and
activate,
all user input can be blocked for a time. Finally, there is a command to
let the application use the daVinci
file-browser
for its own purposes.
- tcl(...)
The Tcl category covers commands to access
daVinci's Tcl/Tk interface. The user interface of daVinci
V2.x is implemented in Tcl/Tk. This way, the application is able to execute
Tcl7.4/Tk4.0 scripts in daVinci, for example to implement dialog
windows which pop up when application menus or icons are selected.
The daVinci Tcl/Tk interface can be used in the same way
as a wish shell, but has an additional Tcl object
daVinci
that accepts API commands sent directly from inside the Tcl/Tk-script and
makes it possible for the script to send strings back to the application.
Note: daVinci's user interface and graph visualization
cannot be manipulated with the Tcl/Tk interface, so daVinci is
not a Tcl object in the common sense. daVinci can only be accessed
by using the commands of the API.
- special(...)
The special category covers
commands to
set the current node and egde
selection,
to
scroll to a particular node
with and without animation and to
display a particular HTML-page
(URL) in the Netscape Navigator WWW-browser.
Answers from the API
All commands sent to the API are confirmed after execution by returning an
answer which is usually ok,
but communication_error(...)
when the command failed. Some commands
(listed here) return another
confirmation answer instead of ok. It is very important to wait
for confirmation before sending the next command, because in rare situations,
the API accepts new commands even if the previous command is still in process
and not yet confirmed, so the confirmations answers may not appear in the
right order.
The rest of the answers (listed here)
are events that are triggered by the user (e.g. to inform the application
about selection of a graph node).
Events can occur at any time, except when an API command is currently
executed and not yet confirmed.
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!
Your application is responsible for handling an event answer. The event may
trigger an operation in the application or can simply be ignored.
Here are some important points that have to be considered when using
the daVinci API:
- Return characters
API commands must not have newline (NL, ASCII=10) or return
characters (CR, ASCII=13) inside. They must have exactly one newline at the
end of the command ("end-of-line") to flush the write buffer. No other
characters, even no spaces, should follow after this concluding return,
except of the next complete command. When these restrictions are not
considered, pipe communication with the daVinci API will likely fail.
- Initial ok:
After
connecting an application to daVinci's API,
the application program has to wait for the
initial ok answer
before sending any commands to daVinci.
- Disconnection:
An application will receive the answer
disconnect
if the user selects menu
File/Disconnect.
The appropriate action for this
event is to terminate the application to let the user connect another
application in daVinci.
- Multi-Graph Mode:
In
multi-graph mode,
each answer has a preluding
context(...)
answer to specify the context (graph) where the event happened. So, your
application has to receive two answers at a time after entering
multi-graph mode.
- Close and Exit:
If the application
controls daVinci's File menu events,
it will receive (a preluding answer
context("ID")
and then) an answer
menu_selection("#%close")
each time the user wants to close a particular context (graph) by using menu
File/Close.
The appropriate action in this case is to
set the current context
to the given ID and to close it by sending command
menu(file(close)).
In the same way, the application will receive answer
menu_selection("#%exit")
when the user want to exit daVinci by using menu
File/Exit.
The appropriate action in this case is to send command
menu(file(exit)) to terminate daVinci.
- Migration to the V2.x API:
If you have an existing application using commands of the V1.x
API, you should migrate to the V2.x API as soon as possible. Guidelines for
the neccessary tasks can be found in the
Transition Guide. Do not mix commands of the
V1.x and V2.x API!
daVinci V2.0.3 Online Documentation - Page update: Dec 12, 1996