[Contents] [Intro] [Reference] [Tutorial] [Questions [New [Index]
Overview -> Reference -> API Reference -> Commands of Category Application Menu

daVinci API Definition - Application Menu Commands

On this page, API commands of the app_menu category are described. This category covers all commands to attach dialog elements (i.e. menus and icons) of an application to the daVinci user interface. The commands of this category are enclosed by keyword app_menu(...). Click here to get an overview of all API commands.

Why attaching Menus and Icons to the daVinci User Interface?

By attaching its own menus and icons to daVinci, the application can offer the opportunity to start operations, processed by the application itself, from the daVinci user interface. So, the user has the same kind of menu access to both the visualization operations executed by daVinci and to operations that modify the graph structure and need to be executed by the connected application.

For example, an application might add a "Delete Node" menu. If the user selects this menu in daVinci's user interface, the application will be informed about this event by receiving a menu_selection(...) answer from the API. With respect to the current node selection, which has been propagated by the API with a prior node_selections_labels(...) answer, the application can remove the specific node(s) in its own data structure. Afterwards, the application has to send one of the commands of the graph category back to the API to reflect the modifications in daVinci by updating the graph visualization. With the trivial tasks of this example, daVinci has been extended by the functionality of a simple graph editor without the need to provide the necessary code inside the visualization system. This way, daVinci is as flexible and generic as possible to be extended by any kind of functionality, depending on the behaviour of an application connected to the API.

Background of Application Menus and Icons

An application is able to attach menus in the daVinci user interface at any time by sending command app_menu(create_menus(...)). It is even possible to add more menus later in a session, although this is not a recommended practice with respect to human computer interaction guidelines. daVinci will always attach these application menus in the Edit menu hierarchy, on the assumption that these operations should usually deal with modification of the graph structure. Each time the user selects an entry of a menu provided by the application, answer menu_selection(...) will be sent back by the API to inform about this event. Afterwards, the application can perform any appropriated task to handle the event, e.g. manipulating the own data and sending commands to the API.

Application icons, added by using command app_menu(create_icons(...)), are attached on a separate plane of the icon bar. The other (default) plane of the icon bar, visible at startup time, contains daVinci's icons which are shortcuts to frequently used menu operations. The user can switch between the daVinci plane and the application plane by clicking on the arrow at the lower side of each plane. As soon as the application attaches new icons, the application plane and the arrow become visible automatically. Each time the user selects an icon provided by the application, answer icon_selection(...) will be sent back by the API to inform about this event. Afterwards, the application can perform any appropriated task to handle the event, e.g. manipulating the own data and sending commands to the API.

In multi-graph mode, each context (i.e. graph) has its own menus and icons. To guarantee a consistent user interface, application menus and icons cannot be removed later. If particular menu entries or icons are not applicable in a current situation (e.g. with respect to the current node or edge selection in daVinci), the application should deactivate them by using commands app_menu(activate_menus(...)) and app_menu(activate_icons(...)). Both activation commands enable the specified menus (or icons) and automatically disable all remaining application menus (or icons).

A closer Integration of I/O by interposing the File Menu Events

The application is not able to attach its menus in daVinci to other places than Edit. This might be inappropriated for I/O operations, for example if the applications would like to have a menu to save its own data structure. With respect to most style guides, such an operation should usually be available in the File menu. After connecting an application to the API, daVinci will disable most of the entries in the File menu to aviod situations where the user is able to load a new graph without permission of the application.

If desired, the application can use command app_menu(control_file_events) to take control on all entries of daVinci's File menu, except of File/Connect Application and File/Disconnect Application. After doing so, the application will receive events with the menu_selection(...) answer as soon as any entry of the File menu is selected by the user. After loosing control on the File menu, daVinci will not perform any operation if these menu entries are selected by the user. The application has to decide on its own what to do. To simulate daVinci's behaviour on these events, read the recommended actions below. The entries of daVinci's File menu have special predefined menu_ids (with prefix #%) which are used for the menu_selection(...) answer in case of selection. These reserved menu_ids cannot be used as identifier for application menus:

These menu_ids can also be used with command app_menu(activate_menus(...)) to enable resp. disable the corresponding entries in the File menu. Of course, an unapplicable File menu events can simply be ignored by the application, but usually it has to deactivate menu entries that are not applicable at a time.

Note: Each time command app_menu(activate_menus(...)) is sent to the API, all the other menus, not listed in the command's parameter menu_ids, will be automatically deactivated, even in the File menu (but of course only if the application has taken control on the File menu). So, an application programmer must always consider the entries of the File menu with each menu activation, because otherwise the user might not be able to exit daVinci, if menu File/Exit has been disabled automatically.

Very important: After taking control on the File menu events, the application is responsible for closing a context and quitting daVinci, if the user selects the corresponding menu (e.g. File/Close resp. File/Exit). In this case, the answers menu_selection("#%close") resp. menu_selection("#%exit") are sent to the application which should usually be handled by performing the recommended actions listed below. The user will not be able to close windows or exit daVinci, if the application ignores these events.

Recommended Actions on File Events

If the application controls daVinci's File menu (read above) and the user selects an entry of this menu, then daVinci does not perform any operation. Instead, the event is forwarded to the application by using the API answer menu_selection(...). At this time, the application has to decide what to do. For example, if menu File/New is selected, the application will receive answer menu_selection("#%new"). An appropriate behaviour to handle this event might be to clear the applications internal graph data structure and send an empty graph back to daVinci.

If the application would like to simulate daVinci's behaviour on file events, it can do so by sending the following API commands back to daVinci:

Note: In multi-graph mode, you also need to consider the context of the menu event, sent to the application in a preluding context(...) answer. The current context must be set using command multi(set_context(...)) (to the context_id returned by the event) before sending any commands. Otherwise, your reaction may affect other graphs than the one where the File menu event actually happened.

Documentation of the Category Commands:

app_menu(create_menus(menus))

Creates application menus, specified by list menus, to be attached to daVinci's Edit menu. Read above for details about application menus. The menus are build hierarchically, so they may contain submenus to realize cascades. The menus will appear in the same order in the user interface as the entries in the list. The following menu entry elements can be used for list menus:

app_menu(create_icons(icons))

Creates application icons, specified by list icons, to be attached to the application plane of the icon bar. Read above for details about application icons. The icons will appear in the same order in the user interface as the entries in the list. The following icon entry elements can be used for list icons:

app_menu(activate_menus(menu_ids))

Activates the application menu entries specified by menu_ids. All the other entries, previously created by sending command app_menu(create_menus(...)) and not member of list menu_ids, are deactivated at the same time, such that they cannot be selected by the user. So, the application only need to enable the menus that should be available at a time without deactivating the other ones. Read above for details about application menus.
Note: If the application has taken control on daVinci's File menu (read above for details), then it also has to activate/deactivate the menu entries of the File menu, which have a special menu_id.

app_menu(activate_icons(icon_ids))

Activates the application icons specified by icon_ids. All other icons, previously created by sending command app_menu(create_icons(...)) and not member of list icon_ids, are deactivated at the same time, such that they cannot be selected by the user. So, the application only need to enable the icons that should be available at a time without deactivating the other ones. Read above for details about application icons.

app_menu(control_file_events)

By sending this command, the application declares to take control on the events of daVinci's File menu. Afterwards, entries of the File menu can be enabled (resp. disabled) with command app_menu(activate_menus(...)) just like the other application menus. The entries of the File menu have a special menu_id, listed above. In this case, daVinci will not perform any operation, if an entry of the File menu is selected by the user. Instead, an event is sent by the API with answer menu_selection(...) to let the application decide what to do. Read above for details about controlling the File menu.

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