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.
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:
This command needs no further commands and no finish command.
This command needs no further commands and no finish command.
This command has to be followed by
menu configuration commands and finished with the
terminal finish_popup_menu.
This command has to be followed by
menubar configuration commands and finished
with the terminal finish_menubar.
This command has to be followed by
iconbar configuration commands
and finished with the terminal finish_iconbar.
This command needs no further commands and no finish command.
Define the status area for the user-interface. The status area is the right part of
the footer-area. In the status bar messages send with the command
window(show_status(...))
will be displayed. If this toplevel command is not used, the above command is useless.
Define the popup-menu, that will be displayed, if the right mouse button
(BMenu) is pressed over the graph-area and
no context-sensitive popup-menu needs to be displayed. Please have a look at
the documentation of the default pop-up menu for
further descriptions of popup-menus. If this toplevel command is not used, no default pop-up
menu will be displayed.
Define the pull-down menus in the top of the base-window. If this toplevel command is not
used, no menus will be visible in the base-window.
Define the icon bars at the left side of the base-window. With the parameter one can
decide, which iconbar will be specified (first or second). There can be
specifications for one or for both iconbars. If this toplevel command is not
used at all, no iconbar will be displayed in the base-window. Only if both iconbars
are specified in the configuration file, the icon to switch the iconbars will be
visible at the bottom of the iconbars.
The iconbar configured last will be the visible one after the window is first displayed.
With this command the handling of the close event for all windows can be configured. If
the user selects the system menu File/Close
or closes the window withe commands of the window manager, the application will be
informed about this event with API answer
menu_selection(<close_id>) and must
close the window with the appropriate API commands or deny the closing. With the parameter
close_type one can define, if the event will be sent for all windows (window)
or only if the last window of a context (context) should be closed. If this toplevel
command is not used, windows will be closed by daVinci without notification.
This command has to be followed by menu configuration commands and finished with the terminal finish_menu.
This command has to be followed by
menu configuration commands and finished with the
terminal finish_menu.
This command specifies the help menu on toplevel in the menubar. This menu is added to the
menubar according to the Tcl/Tk rules (i.e. the style-guide rules for the window manager)
for the help menu. This is always at the rightmost position of the menubar for Motif and
or the last entry in the menubar for Windows. The label of the menu is predefined. It is
the language-value for language-key #%Help from the actual language file for UNIX or just
'?' for Windows NT. The mnemonic is choosen by the same rule.
These menu entries can't be activated or deactivated by the application, because the system menus are handled by daVinci and activated or deactivated according to the internal rules. The application is not informed about the selection of this entry.
With this entry, an application specific entry can be added to a menu. The first
parameter specifies, the ID of the menu, which has to be unique for all menu entries and
is used for the API answer
menu_selection(<menu_id>) after
selection of the menu and in the API commands
gui(activate_menus(...)) and
gui(set_radio_menus(...)) for activation or
setting of the value of a radio menu.
The second parameter specifies the label for this entry. The last three parameters
are optional, where mne specifies the mnemonic for this entry (should be
an integer value or "-1" for no mnemonic or a language-key), modifier
specifies the modifier key for the keyboard accelerator of this entry (legal values are:
Control, Shift, Meta, Alt, "", or a language-key) and acc
specifies the key for the accelerator key of this entry (should be a single character or a language-key).
This command starts a radio menu like
Layout/Orientation. The parameter specifies
the name of the variable, which has to be unique for all menu entries and holds the current value of the radio menu selection. At the
initialization time no menu is selected. Please use the command
gui(set_radio_menus(...)) to set this value for
the first time. This command doesn't generate a real entry, it just defines all the
following menus as part of the radio menu until the terminal finish_radio_menu_entry
is found.
This command starts a submenu within a menu like
Layout/Orientation. The first parameter specifies the label of the
menu and the second, which can be omitted specifies the mnemonic character for the keyboard
activation of this menu (should be an integer value or a language-key). All the following
menus are part of the submenu until the terminal finish_submenu_entry
is found.
A separator line in the menu to group particular menu entries.
These icons can't be activated or deactivated by the application, because the system icons are handled by daVinci and activated or deactivated according to the internal rules. The application is not informed about the selection of this icon.
With this entry, an application specific icon can be added to an iconbar. The first
parameter specifies, the ID of the icon, which has to be unique for all icons and
is used for the API answer
icon_selection(<icon_id>) after
selection of the icon and in the API commands
gui(activate_icons(...)) and
gui(set_radio_icons(...)) for activation or
setting of the value of a radio icon.
The second parameter specifies the bitmap for this entry. This can be one
of the system bitmaps (please refer again to the above file, to find the name of the
system bitmap), in which case the bitmap string has to start with #% or a
filename. The filename is the file
with the bitmap of the icon. The file must be a X-Window Bitmap file
(.xbm format) of size 18x18 pixel.
Relative filenames are searched in the directories
specified by
environment variable
$DAVINCI_ICONDIR, whereas absolute filenames
are loaded directly. The third parameter help should be a short
description of the semantic of the icon or a language-key which will be displayed in the
footer area of the daVinci
base window
as soon as the mouse-pointer is over the icon and if a
message_bar has been configured.
This command starts a radio menu like
the last three icons in the regular iconbar.
The parameter specifies
the name of the variable, which has to be unique for all icons and holds the current value of the radio icon selection. At the
initialization time no icon is selected. Please use the command
gui(set_radio_icons(...)) to set this value for
the first time. This command doesn't generate a real icon, it just defines all the
following icons as part of the radio icon until the terminal finish_radio_icon_entry
is found.
A separator gap in the icon bar to group particular icon entries.
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.
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