Multi-Graph Mode in the API

uDraw(Graph) is able to visualize more than one graph at a time, called multi-graph mode. Please read about multi-graph basics in the concepts chapter before going on here.

In multi-graph mode, each loaded graph is shown in a different base window. Operations applied to one graph do not affect the other graphs. The notion of contexts have been introduced to deal with more than one concurrent graph at the API level. Each context has its own scope, so it is not necessary to keep identifiers unique between two contexts, but of course all identifiers have to be unique inside a context. Identifiers are used for nodes and edges in a term representation or for menus.

In multi-graph mode, each graph has a context with a unique context ID (string). The context ID is either automatically generated by uDraw(Graph) when a new context is opened with command multi(new_context) or can be chosen by the application itself when the new context is opened with the alternative command multi(open_context(...)). Opening a new context creates a fresh and empty base window. Afterwards, all commands sent to the API are applied to this 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 will first switch to the new context automatically and afterwards the graph will be displayed in the new window. If the application wants to apply an API command to another graph that has been previously opened, then first of all it has to set the current context to the one that belongs to the other graph. So a context is used to specify one of the currently loaded graphs that should be affected by subsequent API commands. The context can be set using API command multi(set_context(...)).

Principle of two Answers in Multi-Graph Mode

By default, uDraw(Graph) operates in single-graph mode where setting a context is not necessary. After entering the multi-graph mode (i.e. after sending the first multi(new_context) or multi(open_context(...)) command to the API), each answer from the API will have a preluding context(...) answer that is used to specify the context where the event happened. So in multi-graph mode, the application will always get two answers with each event: first the context and then the event itself. Note that the preluding context answer does not switch the current context. This can only be done by the application itself, as described above.

To guarantee full compatibility with applications designed for uDraw(Graph) predecessor versions prior to 2.0 (which do not expect a preluding context), the context answer is only used after entering the multi-graph mode. At start-up time, uDraw(Graph) operates in single-graph mode by default. uDraw(Graph) cannot enter the multi-graph mode by itself with user interface operations, so only the application can decide to do so.

Entering the Multi-Graph Mode at Initialization Time

If the application intends to enter the multi-graph mode later in a session, it should open the first context at initialization time, because for consistency reasons, uDraw(Graph) has to remove a loaded graph as soon as the first context is opened (i.e. when the single-graph mode is left).

The application is able to close an opened context by sending command menu(file(close)). This is the equivalent operation 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 has to open a new context or specify one of the remaining contexts to be the new current context. Sending any other command without changing the context will be answered with an error message, because the current context is undefined after closing as long as a new one is not specified. It is even possible to close the last context without quitting uDraw(Graph). After closing the last context, no window will be visible any longer, but the uDraw(Graph) process is still running in the background. In this situation, the application can open a new first context and a new base window will come back.

Note: the user can also close a context at any time by using menu File/Close or the equivalent generic window function of the operating system respective window manager. The application will receive the answer close from the API after the user or the application has decided to close a context. If closing a context is not appropriate for the user, then the application should redefine the user interface or at least take control of the "File" menu in order to catch these events.

Multi-View Mode in the API

The multi-view mode is used to have different base windows where the same graph is visualized. In opposition to multi-graph, here the base windows show the same graph, so working with one view manipulates all the other views of the graph, too. Please refer to multi-view basics in the concepts chapter. Multi-graph and multi-view can be mixed at the same time, e.g. several graphs can be loaded and each may have different views. Multi-view is a feature of the user interface level and cannot be controlled on the API level, except for opening a new view using command menu(view(open_new_view)). So it is not possible for an application to close a particular view, but you have the option to use the multi-window mode where all base windows can be controlled. All views (base windows) of a context (graph) are removed when the corresponding context is closed with command menu(file(close)).

Master View

The user is able to open and close new views of 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 view of the same graph which will become the new master view. For example, if the user opens one additional view with menu View/Open New View after starting the system and loading a graph, then he can work with the same graph in two different base windows. Now, the user is able to close the first view (master view) with menu File/Close without closing the whole context/graph. The second remaining view will serve as the new master view in this situation.

Most of the commands dealing with one base window rather than the whole graph (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 the other views. The master view is always 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. But the multi-window mode can be used to have access to all individual base windows, read below.

Multi-Window Mode in the API

Usually, the application has no access to individual base windows (views) of a context (graph). But this is possible in the alternative multi-window mode where an application can access all base windows, whether they belong to multiple graphs or views. The idea is to add an additional window ID (beside the context ID) to the relevant API commands and answers.

The multi-window mode is not compatible with previous versions of the API (where window IDs are not expected), so the application must be designed to operate in this mode by accepting the special kind of answers mentioned below. To avoid compatibility problems, the multi-window mode has to be explicitly activated using command-line option -window_api. After this activation, the multi-window is entered as soon as the first command multi(new_context) or multi(open_context(...)) is sent to the API, similar to the multi-graph mode described above.

Instead of answer context(...) known from the multi-graph mode, the answer context_window(...) is used after the multi-window mode has been entered. Here, the application can find a window ID maintained by uDraw(Graph). This window ID can be used in command multi(set_context(...)) to restrict all subsequent commands to that particular base window. In multi-window mode, the application is informed with the answers open_window and close_window(...) about creation and destruction of a base window.

To summarize it, the multi-window mode is an extension of the multi-graph mode where the application has full control over any base window. The multi-view mode is not accessible from the API except of manipulating the master view and opening new views.