[Contents] [Intro] [Reference] [Tutorial] [Questions [New [Index]
Overview -> Reference -> API Reference -> Commands of Category Graphical User-Interface

daVinci API Definition - Graphical User-Interface Commands

On this page, API commands of the gui category are described. This category covers all commands to configure menus, icons and status bars of the daVinci user interface. The commands of this category are enclosed by keyword gui(...) and are only available, if the command-line option -nogui has been set. In the other case the commands of the category Application Menu have to be used. Click here to get an overview of all API commands.

Why configuring the daVinci User Interface?

Many users have asked for a more flexible method to expand the daVinci user-interface, than the commands of the category Application Menu allow. Now the whole user-interface of daVinci can be redefined, without losing the chance to use the normal system menus.

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.

Configurable parts of the user-interface

The daVinci base-window normally contains four areas, that can be configured or even omitted in the configuration-file. These are the footer areas for message and status, the two switchable iconbars and the pull-down menus. Additionally the default popup-menu and the handling of the close-event for windows can be configured.

Applications are no longer restricted to adding menus to the Edit menu or the second iconbar as they were with the commands of the API category Application Menu. Application specific menus and icons can be added to all menus, iconbars and even the popup-menu, without losing the system menus and icons. As a new feature in this command category, it is possible to add radio menus similar to the Layout/Orientation menu and radio icons similar to the last three icons of the regular iconbar.

If a user-interface is configured this way, all parts have to be configured. All parts not configured in the configuration file are omitted from the user-interface. For each context the user-interface can be configured only once and each part of the user-interface maybe configured only once in each configuration file.

The configuration file

A configuration file can have any filename, but the file-suffix has to be .menu. Please look at the description of the command gui(configure(...)) below to find out more about the locations and naming for configuration-files.

Each configuration-file contains one configuration command on each line of the file according to the syntax of the configuration-file. The easiest way to configure the daVinci user-interface is to copy one of the example files of the daVinci distribution in $DAVINCIHOME/lib/daVinci and edit it for the purposes of the application. There are three example files contained in this directory:

As you can see in this examples, it is even possible to rebuild the complete daVinci user-interface, without lossing any functionality of daVinci. Just decide which parts of the user-interface shall be kept and which parts shall be changed in the configuration file.

Toplevel configuration commands

With the toplevel commands, the configuration of each of the parts of the base-window is initiated. They implicitly finish all commands opened before.

Menubar configuration commands

These commands are needed to configure the toplevel menus of a menubar.

Menu configuration commands

These commands specify the entries in a menu or help_menu of a menubar, in a submenu_entry, in a radio_menu_entry or in a pop-up menu.

Iconbar configuration commands

Internationalized strings and strings

The non-terminals string and lang_string in the
syntax of the configuration-file both define strings, that normally should be enclosed in '"'. The '"' can be omitted, if the string contains no whitespace characters. Please refer to the Tcl/Tk documentation to find out more about strings in Tcl/Tk. A lang_string can be a regular string as described above or it can be a language-key to use the internationalization mechanism of daVinci. In this case, the string has to have the form #%<language-key> (i.e. "#%FileDlg.Cancel"). This would display the language-value defined for language-key instead of directly using lang_string.

Activation and deactivation of menus and icons

All menus and icons defined with the configuration commands
menu_entry ... or icon_entry ... are usually deactivated. The application has to activate them with the commands gui(activate_menus(...)) and gui(activate_icons(...)). Both activation commands enable the specified menus (or icons) and automatically disable all remaining application menus (or icons).

All other menus and icons are activated or deactivated by daVinci. Especially entries defined with command submenu_entry ... or menus defined with the commands menu ... or help_menu need not be activated, because they are automatically activated, if at least one of their entries is activated or deactivated, if none of their entries is activated. Remember, that in the API command category Application Menu submenus had to be activated!

For those of you, who have used API command app_menu(control_file_events) in their applications and now want to use the predefined menu configuration-file $DAVINCIHOME/lib/daVinci/daVinci_cfe.menu the application has to be changed in one place, because for control_file_events the API command app_menu(activate_menus(["#%open","#%saveas","#%print"])) activates both the menus and icons for this functions. This has to be done with the two commands gui(activate_menus(["#%open","#%saveas","#%print"])) and gui(activate_icons(["#%open","#%saveas","#%print"])) now.


Documentation of the Category Commands:

gui(configure(string))

Configure the user-interface of a context from file <string>.menu. The file is searched in the current working directory or the directory $DAVINCIHOME/lib/daVinci or if <string> is the initial sequence of an absolute filename, the absoulte file is opened.

For each context, this command can be called only once, because it is not possible to reconfigure the user-interface of an open window. If daVinci is first started with option -nogui, or if a new context is opened with the commands of category Multi and -nogui had been set, no window will appear as long as this command or the command window(deiconify)) hasn't been send.

Please read more about the contents of a configuration file above.

gui(activate_menus(menu_ids))

Activates the application menu entries specified by menu_ids. All the other application specific menu entries, defined in the configuration file 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.

gui(set_radio_menus(menu_ids))

Mark all the application menu entries specified by menu_ids as selected, where all members of menu_ids must be part of a radio menu.

gui(activate_icons(icon_ids))

Activates the application icons specified by icon_ids. All other application specific icons, defined in the configuration file 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.

gui(set_radio_icons(icon_ids))

Mark all the application icon entries specified by icon_ids as selected, where all members of icon_ids must be part of a radio icon.


daVinci V2.1.1 Online Documentation - Page update: Oct 21, 1998