API Application Menu Commands

For background information about the commands described on this page, refer to the information about user interface extension in the corresponding section of the API reference. Alternatively, you can use user interface configuration to control more aspects of the user interface.

On this page, API commands of the application menu category are described. This category covers all commands to extend the uDraw(Graph) user interface by attaching dialog elements (i.e. menus and icons) that are exclusively used by the application. The commands of this category are enclosed by keyword "app_menu(...)". They are not available when command-line option -nogui has been used. In this case you have to use the commands of category graphical user interface instead. Click here to get an overview of all API commands.

app_menu(create_menus(menus))

Creates a menu for the application specified by list "menus" which are attached to the Edit menu in the uDraw(Graph) user interface. Details about application menus are available in the user interface extension guide. The menus are built 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 parameter "menus" is also used for pop-up menus that are created by using the pop-up menu node attribute and pop-up menu edge attribute in the graph, so special cases for pop-up menus are described here. The following menu entry elements can be used in list "menus":

menu_entry(menu_id,menu_label)

A single menu entry, where "menu_id" is the identifier sent back to the application with answer menu_selection(...) when the user selects this entry. Further, the "menu_id" can be used with command app_menu(activate_menus(...)) to enable this menu entry in the user interface. "menu_label" is the text of the entry that will appear in the menu.

Note: The parameter "menu_label" can be a language key starting with "#%..." to use the internationalization feature for multilingual interfaces. This menu entry does not have a mnemonic, so for regular pull-down menus you should use menu_entry_mne(...) instead to provide access by keyboard. But use "menu_entry(...)" for pop-up menus, because naturally they cannot be controlled with the keyboard.

menu_entry_mne(menu_id,menu_label,menu_mne,menu_mod,menu_acc)

Same as menu_entry(...) above, but with three additional parameters. "menu_mne" is a string with one character used as mnemonic, so this character must exist in parameter "menu_label". The mnemonic character will be underlined in the menu for keyboard access. The last two parameters are used to specify an optional keyboard accelerator. Parameter "menu_mod" is the modifier key, either alt, shift, control, meta, none (do not quote this parameter, e.g. no "alt"!). "menu_acc" is the accelerator key. So with the alt modifier and "A" for the accelerator key, you can select the corresponding menu entry by pressing "Alt" and "A" together on the keyboard. The accelerators of existing uDraw(Graph) menus must not be overloaded, so do not use the control modifier with O, S, P, C, X, N, L, T, F, A or I.

Example:

menu_entry_mne("id1","my menu","y",alt,"m")

Note: The parameters "menu_label", "menu_mne" and "menu_acc" can be a language key starting with "#%..." to use the internationalization feature for multilingual interfaces. The parameter "menu_mod" is an enumeration and not a string, but here you can use the unquoted value lookup followed by a "string" which is a language key. Note that this string must not begin with "#%...", although it is a language key used to retrieve the actual text from the translation table. Simply remove the "#%" when you use a language key for this parameter, because the lookup in the translation table is done in any case, so the distinction between a usual string (without "#%") and a language key (with "#%") is not necessary here.

Example:

menu_entry_mne("id1","#%m1","#%m1_mne",lookup "#%m1_mod","#%m1_acc")

For pop-up menus, the entry "menu_entry_mne(...)" is not recommended, because naturally pop-up menus cannot be controlled with the keyboard. Use entry menu_entry(...) instead.

menu_entry_disabled(menu_id,menu_label)

Same as menu_entry(...) above, but here the entry is always deactivated and can never be selected with the mouse. Do not use this entry for regular pull-down menus, because these entries can be activated (and deactivated) with API command app_menu(activate_menus(...)). This is not possible in pop-up menus, where the menu is an attribute value of a particular node/edge. To activate and deactivate entries in a pop-up menu, you have to create a new menu with normal and deactivated entries. Afterwards, you have to set this menu as the value of the pop-up menu attribute for the node/edge, either with command graph(change_attr(...)) or more easily with types and visualization definitions.

Note: The parameter "menu_label" can be a language key starting with "#%..." to use the internationalization feature for multilingual interfaces.

submenu_entry(menu_id,menu_label,menus)

A submenu (i.e. cascade) that contains another list of menu entries, specified by parameter "menus". "menu_id" can be used with command app_menu(activate_menus(...)) to enable this submenu in the user interface. Submenus can be opened by the user, but not selected, so their "menu_id" will never be sent back to the application with a menu selection event. You have to read above, because all the other information about menu_entry(...) applies to this entry, too.

submenu_entry_mne(menu_id,menu_label,menus,menu_mne)

Same as submenu_entry(...), but with an additional mnemonic. You have to read above, because all the other information about menu_entry_mne(...) applies to this entry, too (except for modifier and accelerator which are not present here).

submenu_entry_disabled(menu_id,menu_label,menus)

Same as submenu_entry(...), but always disabled. You have to read above, because all the other information about menu_entry_disabled(...) applies to this entry, too.

blank

A separator line in the menu to group particular menu entries.

app_menu(create_icons(icons))

Creates icons for the application specified by list "icons" which are attached to the application plane of the icon bar in the uDraw(Graph) user interface. Details about application icons are available in the user interface extension guide. 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 in list "icons":

icon_entry(icon_id,filename,lang_string)

A single icon entry, where "icon_id" is the identifier sent back to the application with answer icon_selection(...) when the user selects this entry. Further, the "icon_id" can be used with command app_menu(activate_icons(...)) to enable this icon entry in the user interface. The "filename" specifies the file with the bitmap used for the icon. This can be a uDraw(Graph) system bitmap (the settings can be found in the configuration file of the standard user interface in "$UDG_HOME/lib/uDrawGraph/uDrawGraph.menu") or a file name in one of the directories specified by environment variable $UDG_ICONDIR. The bitmap file used for icons must be in X11 Bitmap format (".xbm") with a size of 18x18 pixel. The third optional parameter "help" is a short text or language key mapping to a text that describes the semantic of the icon operation. The help text is automatically displayed in the footer area of the base window as long as the mouse pointer is over the icon.

Note: The parameter "string" can be a language key starting with "#%..." to use the internationalization feature for multilingual interfaces.

blank

A separator gap in the icon bar in order to group particular icons in a visual manner.

app_menu(activate_menus(menu_ids))

To activate the application menu entries specified by "menu_ids", so it is possible to select them with the mouse. All the other entries previously created by app_menu(create_menus(...)) and not member of list "menu_ids" are automatically deactivated at the same time, so they cannot be selected by the user. In other words, the application only has to enable the menus that should be available at a time without deactivating the other ones. Details about application menus are available in the user interface extension guide.

Note: after controlling the "File" (see below), the application also has to activate and deactivate the "File" menu entries of the File menu. They have a special menu ID, see user interface extension guide.

app_menu(activate_icons(icon_ids))

To activate the application icon entries specified by "icon_ids", so it is possible to select them with the mouse. All the other entries previously created by app_menu(create_icons(...)) and not member of list "icon_ids" are automatically deactivated at the same time, so they cannot be selected by the user. In other words, the application only has to enable the icons that should be available at a time without deactivating the other ones. Details about application icons are available in the user interface extension guide.

app_menu(control_file_events)

After sending this command, the application declares to take control on the events of the uDraw(Graph) File menu. Afterwards, the entries in the "File" menu can be enabled and disabled using command app_menu(activate_menus(...)) just like any other application menu entry. The entries of the "File" menu have a special menu ID, listed in the user interface extension guide. After using this command, uDraw(Graph) will not perform any operation when 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 more about controlling the "File" menu in the user interface extension guide.