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 ten 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) and to change the type of nodes and edges (more information about types). 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.
With this concept you can only access each context (graph) on its own, but you have no access to the windows opened in a context. Especially the commands of category Window are sometimes useless, because they work only for the first window of a context. Therefore we have introduced the Window-API mode in daVinci V2.1. With the command-line option -window_api, you can switch the behaviour of the API. We have to keep the old behaviour as the default, because we have to guarantee, that all old applications still work without changes. In multi-window mode, the current context must be set with a command of this category. The current context and window specifies the graph and its window that is currently affected by all the other commands sent to the API. On the other side, in multi-window mode, each answer from the API has a preluding context_window answer to specify the graph and window where the event happened.
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.
One option, that can't be set by the user via menus, is the precedence of visualization definitions in the evaluation of attribute values for nodes and edges. You can set this option only via API, because visualization definitions can only be defined via the API.
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.
visual(...)
The visual category covers commands to add new rules or modify rules of the visualization definitions.
drag_and_drop(...)
The Drag and Drop category covers commands to switch drag and drop on or off. Further commands are available to react on drag and drop events by adding a new node or a new node and edge at the drop position.

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

Important Notes about the API

Here are some important points that have to be considered when using the daVinci API:

No Return characters inside API commands
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. For example, in C you can send one command to daVinci's API this way, whereby dv_pipe is the file descriptor of the command pipe to daVinci (the API command is highlighted in bold face): fprintf(dv_pipe,"window(show_message(\"Hi\"))\n"); Note that there is a newline at the end of the C string and that there is another API string inside the C string (which is an API command). Quotes inside C strings have to be escaped with a backslash character '\'. The same is true for daVinci's API strings, read the next list item.
No unescaped double quotes inside API commands
Some API commands have a string argument which is enclosed by double quotes, for example command window(show_message("This is a string")). If you have to use double quotes inside a string, make sure that they are always escaped with a backslash character '\'. Example: window(show_message("Here is a quote \" inside.")). But do not escape the outermost double quotes of the string!
Use only balanced braces ('{' and '}') in API commands
As a result of using Tcl/Tk for the implemantation of the user interface, some characters have a special meaning for Tcl. So we have used '{' and '}' as delimiters for sending strings to Tcl. Therefore Tcl complains about unbalanced braces, if somewhere in a string only one of both is used (i.e. "}" or "{", whereas "{}" is allowed). So please avoid unbalanced braces in strings or you'll get Tcl/Tk error messages on command-line.
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.
multi-window Mode:
In multi-window mode, each answer has a preluding context_window(...) answer to specify the context (graph) and window where the event happened. So, your application has to receive two answers at a time after entering multi-window mode. The application is informed about opening (answer open_window) and closing (answer close_window(...) of windows.
Close and Exit:
If the application controls daVinci's File menu events, it will receive (a preluding answer context("ID") or context_window("ID") for multi-window mode 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 (and window) to the given ID (ID's) 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 wants 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.1 Online Documentation - Page update: June 15, 1998