Overview -> Reference -> API Reference -> Commands of Category Multi

daVinci API Definition - Multi Commands

On this page, API commands of the multi category are described. This category covers all commands to work with more than one graph at a time. The commands of this category are enclosed by keyword multi(...). Click here to get an overview of all API commands.

Multi-Graph Background:

daVinci V2.x is able to visualize more than one graph at a time (multi-graph mode). Read about multi-graph in the concept document before going on here.

In multi-graph mode, each loaded graph is shown in a different base window. Operations on one graph do not affect the other graphs. To deal with different graphs at the API level, the notion of a context is introduced in daVinci V2.x. Each context has its own scope, so it is not neccessary to keep identifiers (e.g. for nodes and edges in a term representation or for menus) unique between two contexts, but of course all identifiers have to be unique in one context.

For each graph, there is a context which has a unique context_id. The context_id is either choosen and returned by daVinci when a new context is opened with command multi(new_context) or can be choosen by the application when the new context is opened with the alternative command multi(open_context(...)). After opening a context, which pop up a fresh and empty base window, all commands send to the API are applied to this current context until the current context is set to another one. So for example, by sending command menu(file(open_graph(...))) directly after opening a new context, the current context has been automatically switch to the new context before and the graph will be displayed in the new window. If the application wants to send an API command to another graph that has been previously opened, then it has to set the current context to the context of this graph first. The current context which specifies the graph currently affected by all the other API commands can be set with command multi(set_context(...)).

Two Answer Concept for Multi-Graph

On the other side, after entering multi-graph mode (i.e. by sending the first multi(new_context) or multi(open_context(...)) command), each answer from the API will have a preluding context(...) answer which specifies the context where the event happened. So, an application will always get two answers with each event in multi-graph mode: first the context and then the event itself. Note: The preluding context answer does not switch the current context which can only be done by the application itself.

To ensure full compatibility with applications designed for daVinci V1.x (who do not expect a preluding context), the context answer is only used after entering multi-graph mode. At startup time, daVinci is in single-graph mode by default. The user cannot enter the multi-graph mode if an application is connected to the API, only the application can decide to do so.

Enter the Multi-Graph Mode at Initialization Time

If the application would like to use the multi-graph mode later in a session, it should open the first context at initilization time. For consistency reasons, daVinci will remove a probably loaded graph as soon as the first context is opened (i.e. when the multi-user mode is entered).

The application is able to close an opened context by sending command menu(file(close)). This is the equivalent of menu File/Close. After closing a context, all of the windows of the particular graph will be removed, and the corresponding 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 the current context is undefined as long as a new one is not specified. It is even possible to close the last context without quitting daVinci. After closing the last context, no window will be visible any longer, but the daVinci process is still running. In this situation, the application can open a new first context and a new base window will come back.

Note: The user is also able to close a context at any time by using menu File/Close. The API will send anwer close after the user or the application has decided to close a context. If it is not appropriated to let the user closing a context, then the application has the opportunity to interpose daVinci's File menu to catch these events.

Multi-View Background:

Another issue is the multi-view mode where different base windows are used to visualize the same graph. In opposite to multi-graph, multi-view windows are based on the same graph structure, so working with one view manipulates all the other views of a graph, too. Multi-graph and multi-view can occur at the same time, e.g. several graphs can be loaded and each one may have different views. Multi-view is a feature of the user interface and cannot be controlled from the API, except of the opportunity to open a new view with command menu(view(open_new_view)). So it is not possible for an application to close a particular view. All views (base windows) of a context (graph) are removed if the context is closed with command menu(file(close)).

The user is able to open and close new views for a graph at any time. The first (i.e. oldest) view of a context is called master view. The master view can be closed by the user without closing the whole context as long as there is one other opened view of the same graph which will become the new master view. For example, when the user opens one additional view with menu View/Open New View, then he can work with the same graph in two different base windows. Now, he/she is able to close the first view (master view) with menu File/Close without closing the whole graph. The second remaining view will serve as the new master view in this situation.

Master View

Most of the commands dealing with one base window rather than a graph/context (e.g. setting the scale, focusing nodes or setting window position/extension, etc.) are applied only to the master view window of a context and not to all of its views. The master view is the oldest view of a context. The other views cannot be manipulated with API commands, because multi-view is a feature of the user interface rather than the API.

Multi-Window Background:

Usually the application has no access to individual windows (views) of a context (graph). In daVinci V2.1 we have the multi-window mode for the API, in which an application can access all base-windows opened in daVinci. You can set daVinci into this new mode with the command-line option -window_api. Than the multi-window mode is entered the same way as it is described above for the multi-graph mode.

After entering multi-window mode (i.e. by sending the first multi(new_context) or multi(open_context(...)) command), each answer from the API will have a preluding context_window(...) answer which specifies the context and the window where the event happened. So, an application will always get two answers with each event in multi-window mode: first the context and then the event itself. Note: The preluding context_window answer does not switch the current context and window which can only be done by the application itself.

To ensure full compatibility with applications designed for daVinci V1.x (who do not expect a preluding context_window), the context_window answer is only used after entering multi-window mode. At startup time, daVinci is in single-graph mode by default.

In multi-window mode the application is informed by the events open_window and close_window(...) about the opening or closing of a window.

Documentation of the Category Commands:

multi(new_context)

This command opens a new context by operating in multi-graph mode mode. If daVinci has been in single graph mode before and a graph was loaded in this situation, then the graph will be automatically removed to always start with an empty window for a new context (read note above). Otherwise, if daVinci has already been in multi-graph mode, then an additional empty base window will appear. In both cases, the current context (which specifies the graph that is currently affected by all other commands sent to the API) will be the new context until this is changed with command multi(set_context(...)) or another context is opened.

As with most commands, answer ok is sent back to the application to confirm this command. In multi-graph mode (always true after using this command), each answer sent back to the application has a preluding context(...) (or context_window(...)) answer that specifies the graph where the event happened, read above. If a new context is opened, daVinci will choose a new context_id (and window_id) which will be returned to the application in the preluding context(...) (or context_window(...)) answer. This means, the command always returns two answers, context(...) (or context_window(...)) with the ID of the new context (and the new window) and then ok). Your application has to store this context_id (and window_id) to apply commands to this context (and window) later.

The context_id (and window_id), returned by this command, is used in the preluding context (context_window) answer of each answer that is sent back to the application in multi-graph (multi-window) mode. Further, the context_id (and window_id) can be used by the application to set the current context with command multi(set_context(...)).

multi(open_context(context_id))

This command opens a new context in the same way like multi(new_context) do (see above), but the context_id is not choosen by daVinci, but given by the application as parameter. Note: An initial underscore ('_') is not allowed for context_id's given by the application.

The command returns answer ok with a preluding context(...) (or context_window(...)) answer, where the context_id is the one used in the parameter of the command. The current context will be the new one until this is changed with command multi(set_context(...)) or another context is opened.

multi(set_context(context_id))
multi(set_context(context_id,window_id))

The first form of the command is used in multi-graph, the second in multi-window mode to set the current context to context_id which specifies one of the graphs in multi-graph mode (and window_id, which specifies one of the windows of the context). All commands sent to the API are applied to the current context (and window), so to manipulate different graphs (and windows), the application has to switch between the contexts (and windows) by using this command. The context_id parameter of the command must be one of the identifiers returned from the API after opening a context. The window_id parameter of the command (second form) must be one of the identifiers returned from the API after opening a context or a window. The specified context (and window) needs to be still open and the context must not be closed by the user or the application (this is propagated with a close answer).

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