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:
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:
Popup-menu: For popup menus, this is the recommended element to insert an entry into a popup menu, because popup menus can't have mnemonics. The entry is always active in the popup menu.
For this command, the internationalization mechanism of daVinci can be used by supplying a menu_label parameter of the form: #%<language-key> (i.e. "#%File.New"). This would display the language-value defined for language-key instead of directly using menu_label.
Popup-menu: For popup menus, this element is not recommended, because popup menus can't have mnemonics. But if you use it, it behaves as menu_entry above.
For this command, the internationalization mechanism of daVinci can be used by supplying a menu_label, menu_mne or menu_acc parameter of the form: #%<language-key> (i.e. "#%File.New", "#%File.New.mne" or "#%File.new.acc"). This would display the language-value defined for language-key instead of directly using the supplied value. A special mechanism had to be implemented for menu_mod, because this is an enumeration type and not a string. Please use lookup <language-key> (i.e. lookup "File.New.mod") to use the menu modifier from the language file.
Popup-menu: For popup menus, this is the element to insert a disabled entry into a popup menu. The entry is always deactivated in the popup menu. We have introduced it, to give the application the chance to keep popup menus consistent for all nodes and edges, because popup menus can't be deactivated. If the application want's to activate the menu entry, it has to exchange the popup menu by changing the node or edge attribute or the corresponding visualization rule.
For this command, the internationalization mechanism of daVinci can be used by supplying a menu_label parameter of the form: #%<language-key> (i.e. "#%File.New"). This would display the language-value defined for language-key instead of directly using menu_label.
Popup-menu: For popup menus, this is the recommended element to insert a submenu into a popup menu, because popup menus can't have mnemonics. The entry is always active in the popup menu.
For this command, the internationalization mechanism of daVinci can be used by supplying a menu_label parameter of the form: #%<language-key> (i.e. "#%File.New"). This would display the language-value defined for language-key instead of directly using menu_label.
Popup-menu: For popup menus, this element is not recommended, because popup menus can't have mnemonics. But if you use it, it behaves as submenu_entry above.
For this command, the internationalization mechanism of daVinci can be used by supplying a menu_label or menu_mne parameter of the form: #%<language-key> (i.e. "#%Layout.Orientation", "#%Layout.Orientation.mne"). This would display the language-value defined for language-key instead of directly using the supplied value.
Popup-menu: For popup menus, this is the element to insert a disabled submenu into a popup menu. The submenu is always deactivated in the popup menu. We have introduced it, to give the application the chance to keep popup menus consistent for all nodes and edges, because popup menus can't be deactivated. If the application want's to activate the submenu, it has to exchange the popup menu by changing the node or edge attribute or the corresponding visualization rule.
For this command, the internationalization mechanism of daVinci can be used by supplying a menu_label parameter of the form: #%<language-key> (i.e. "#%File.New"). This would display the language-value defined for language-key instead of directly using menu_label.
For this command, the internationalization mechanism of daVinci can be used by supplying a string parameter of the form: #%<language-key> (i.e. "#%Icon.Help.Layout.All"). This would display the language-value defined for language-key instead of directly using string.