MainAPIUser Interface Configuration

User Interface Configuration

Configuring the user interface is a way to determine the appearance of all menus, the icon bar and the footer area of the uDraw(Graph) base windows. So you can reorder the given menus and icons, insert your own application menus and icons at any position or remove the menus, icons or footer completely. Another option is to extend the user interface in the traditional way. Please refer to the chapter User Interface Extension to read about the motivation for extending or configuring the uDraw(Graph) user interface.

Configurable Parts of the User Interface

The base window has three configurable areas, namely the pull-down menus, the icon bar (with two planes) and the footer area where messages and status information is displayed. Additionally, the default pop-up menu and the handling of closing events for base windows can be configured. The configuration is done at initialization time by reading a configuration file when uDraw(Graph) is started. In the configuration file, all visible parts have to be defined exactly once. Parts not mentioned there are removed from the user interface, so it is even possible to get base windows without menus, icons and footer. A base window that is already visible cannot be reconfigured, so this has to be done at start-up time or when the corresponding context is opened in multi-graph mode.

With user interface configuration, an application program connected to the API can add (or reorder or reduce) menus and icons in any way. This is not possible with the traditional user interface extensions. Further, the application can define radio menus similar to the Layout/Orientation menu and radio icons similar to the last three icons of the standard icon bar.

The User Interface Configuration File

Only one configuration file is used at a time, but you can have more to work with different settings. The name of a configuration file is arbitrary, but the suffix of the filename has to be ".menu". Please look at the description of the command gui(configure(...)) to read the details about location and naming of configuration files.

The file must have one configuration command at each line according to the configuration file syntax. Some commands have parameters like basic types (e.g. string) or further commands. Some commands have a corresponding "finish_..." command to declare the end of the corresponding block. The easiest way to configure the user interface is to look at some examples. They are located in directory "$UDG_HOME/lib/uDrawGraph" of the distribution. You can copy and edit them for your own purpose. The directory contains three user interface configuration files:

• File "uDrawGraph.menu"
  

  A configuration for the standard user interface of uDraw(Graph) that appears after every start without using command-line option -nogui. The file is not actually used by the system, it only serves as an example.

• File "uDrawGraph_cfe.menu"
  

  Same as above, but this is the standard user interface that appears when a connected application has taken control of the file menu events. There are some small differences regarding necessary activation commands in order to get the same behavior known from previous releases when the file menu events are interposed. Please read the transition guideline below for further details.

• File "gedit.menu"
  

  This is the actual user interface configuration used by the graph editor application. It contains menus and icons for both the uDraw(Graph) standard operations and the graph editor operations attached to the "Edit" menu. Note: do not change this file without having a copy, because it is used by the system when the graph editor is connected. Otherwise the user interface may be damaged.

As you can see from the examples, it is even possible to rebuild the complete user interface without losing any function of uDraw(Graph). You can decide on your own about the user interface parts that are kept, changed or removed.

Top-level Configuration Commands

By using a top-level command in the configuration file, you declare the configurable part of the user interface. Unfinished commands of the previous top-level command are automatically finished this way. Please refer to the configuration file syntax, too.

• menubar
  

  The menu bar is the part of the pull-down menus that is always visible. It is the topmost area of the base window containing the entries "File", "Edit", etc. With the top-level command "menubar" you can define the whole pull-down menu hierarchy, i.e. the menu bar and all the menus that can be reached from this point. The menu bar will not be visible when this top-level command is not used in the configuration file. The "menubar" top-level command is followed by menu bar configuration commands and a final command "finish_menubar" to declare the end of this block.

• popup_menu
  

  To define the default pop-up menu that appears when the right mouse button is pressed over free space in the graph area or over a node/edge that does not have an own pop-up menu using node/edge attributes. No default pop-up menu will be available when this top-level command is not used in the configuration file. The "popup_menu" top-level command is followed by menu configuration commands and a final command "finish_popup_menu" to declare the end of this block.

• iconbar which_iconbar
  

  To define the whole content of the icon bar at the left side of the base window. The icon bar has two planes, the regular plane ("first", intended for built-in operations) and the application plane ("second", originally intended for icons sent by API command app_menu(create_icons(...))). When two planes are defined, the user will have a small arrow symbol at the bottom of the icon bar to switch between both planes. You can use the "iconbar" top-level command twice in a configuration file, i.e. one for each plane which is specified by parameter which_iconbar. If only one plane is defined, then this will be the one that becomes visible in the base window, even if it is the "second". The icon bar will not be visible when this top-level command is not used in the configuration file. The "iconbar" top-level command is followed by icon bar configuration commands and a final command "finish_iconbar" to declare the end of this block.

• message_bar
  

  To define that the base window should have a message bar. The message bar is the left part of the footer area. In the message bar, all standard text messages of uDraw(Graph) are displayed as well as the messages sent by an application with the API command window(show_message(...)). If this top-level command is not used in the configuration file, uDraw(Graph) will not display any messages and the above API command to show messages has no effect. The footer area will not be visible in the base window when both the message and status bar are omitted in the configuration file. The "message_bar" top-level command has no parameters, so there is no need to finish this command.

• status_bar
  

  To define that the base window should have a status bar. The status bar is the right part of the footer area. In the status bar, only messages are displayed that are sent by an application with the API command window(show_status(...)). If this top-level command is not used in the configuration file, the API command to show the status has no effect. The footer area will not be visible in the base window when both the message and status bar are omitted in the configuration file. The "status_bar" top-level command has no parameters, so there is no need to finish this command.

• close_event close_id close_type
  

  This top-level command can be used to define the behavior when a base window is closed, either by menu File/Close or the equivalent generic window function of the operating system respective window manager. With the "close_event" top-level command, the application will receive the answer "menu_selection(<close_id>)" (where "close_id" is taken from the configuration file) and has to react either by closing the corresponding context or by ignoring the event, similar to the recommended action on the "#%close" menu selection event described on the user interface extension page. Make sure that the "close_id" is unique with respect to the other menu IDs in your configuration file. With the parameter "close_type", you can specify that the event will be sent when any base window is closed ("window") or only when the last base window of a context is closed ("context"). If the "close_event" toplevel command is not used, base windows will be closed by uDraw(Graph) without notification. The "close_event" command has a fixed number of parameters, so there is no need to finish this command.

Menu Bar Configuration Commands

These commands are available to configure the top-level entries used for accessing the pull-down menus which are displayed in the menu bar (i.e. "File", "Edit", "View" etc. in the default user interface). Please refer to the configuration file syntax, too.

• menu label ?mne?
  

  To specify a regular entry in the menu bar. All menu entries are added from left to right in the menu bar according to the order of the menu commands in the menu bar part of the configuration file. The first parameter of this command is used to specify the label (text) of the menu and the second, which is optional, is a mnemonic character for keyboard activation of the menu. The mnemonic character is either an integer or a language key that maps to an integer. It specifies the n-th character of the label that should be used as mnemonic, where "0" is the first character of the label and "-1" means no mnemonic. The mnemonic character is underlined in the user interface. This command has to be followed by menu configuration commands and finished with a final "finish_menu" command.

• help_menu
  

  To specify a special entry for the help menu in the menu bar. This menu is added to the menu bar according to a particular style-guide. On UNIX® and Linux® platforms, the help menu is always at the rightmost position of the menu bar and on Windows® and Mac OS® platforms it is the last entry in the menu bar, directly next to the previous entry. The label (text) of the help menu is predefined. On UNIX® and Linux®, it is the current value of the language key "#%Help" and on Windows® it is just "?". A suitable mnemonic is used. This command has to be followed by menu configuration commands and finished with a final "finish_menu" command.

Menu Configuration Commands

These commands can be used to define an entry in a menu or help_menu of a menu bar, in a submenu_entry, in a radio_menu_entry or in a popup_menu. The order of menu entries in the user interface is determined by the order in the configuration file.

• menu_entry menu_id label ?mne? ?modifier acc?
  

  With this command, a menu entry specific to an application program can be added to a menu. The first parameter specifies the identifier of the menu that is sent back to the application using API answer menu_selection(<menu_id>) when the menu entry is selected by the user. This identifier can also be used in API command gui(activate_menus(...)) to enable the corresponding menu entry and in gui(set_radio_menus(...)) to set the current value if the menu entry is part of a radio menu. Note that all menu identifiers must be unique in a configuration file. The second parameter specifies the label (text) for this entry. The last three parameters are optional, where "mne" specifies the mnemonic of this entry (see command "menu" for details about mnemonics). The fourth parameter "modifier" specifies the modifier key for the keyboard accelerator of this entry (supported values are: "Control", "Shift", "Meta", "Alt", "" or a language key mapping to one of these values) and the fifth parameter "acc" is the corresponding key used for acceleration (should be a single character like "a" or a language key mapping to a character). The last two parameters must be used together.

• sys_menu_entry function label ?mne? ?modifier acc?
  

  With this command, a system menu entry available in the standard uDraw(Graph) user interface can be added to a menu. The first parameter specifies the system function. Please refer to the configuration file of the standard user interface (in "$UDG_HOME/lib/uDrawGraph/uDrawGraph.menu") for the settings. The remaining parameters are the same as in command menu_entry. System menu entries cannot be activated or deactivated by the application, because they are handled by uDraw(Graph) according to internal rules. The application is not informed about the selection of this entry.

• submenu_entry label ?mne?
  

  This command is used for a group of menu entries that belongs to a common submenu. The parameters are the label (text) and optional mnemonic character of the menu, as described for command menu_entry. Command "submenu_entry" is used to enclose the menu entries that should belong to the submenu. This command has to be followed by menu configuration commands and finished with a final "finish_submenu_entry" command after the last entry of the submenu.

• radio_menu_entry menu_var
  

  This command is used for a group of menu entries with "radio button" semantic like menu Layout/Orientation where one entry of the group is selected at a time. The parameter "menu_var" is a unique identifier for the radio entry. At initialization time, no entry of the group is selected. Please use command gui(set_radio_menus(...)) to set the initial value for all radio menus. Command "radio_menu_entry" is used to enclose the menu entries that should belong to the group. This command has to be followed by menu configuration commands and finished with a final "finish_radio_menu_entry" command after the last entry of the group.

• blank
  

  To set a separator line in the menu in order to group particular menu entries in a visual manner.

Icon Bar Configuration Commands

These commands are available to configure the content of the icon bar. Please refer to the configuration file syntax, too.

• icon_entry icon_id bitmap ?help?
  

  With this command, an icon specific to an application program can be added to the icon bar. The first parameter specifies the identifier of the icon that is send back to the application using API answer icon_selection(<icon_id>) when the icon is selected by the user. This identifier can also be used in API command gui(activate_icons(...)) to enable the corresponding icon and in gui(set_radio_icons(...)) to set the current value if the icon if part of a radio icon. Note that all icon identifiers must be unique in a configuration file. The second parameter "bitmap" 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^TM 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.

• sys_icon_entry function bitmap ?help?
  

  With this command, a system icon available in the standard uDraw(Graph) user interface can be added to the icon bar. The first parameter specifies the system function. Please refer to the configuration file of the standard user interface (in "$UDG_HOME/lib/uDrawGraph/uDrawGraph.menu") for the settings. The remaining parameters are the same as in command icon_entry. System icons cannot be activated or deactivated by the application, because they are handled by uDraw(Graph) according to internal rules. The application is not informed about the selection of this icon.

• radio_icon_entry icon_var
  

  This command is used for a group of icons with "radio button" semantic like the last three icons in the icon bar of the standard base window where one icon of the group is selected at a time. The parameter "icon_var" is a unique identifier for the radio icon entry. At initialization time, no icon of the group is selected. Please use command gui(set_radio_icons(...)) to set the initial value for all radio icons. Command "radio_icon_entry" is used to enclose the icon entries that should belong to the group. This command has to be followed by icon configuration commands and finished with a final "finish_radio_icon_entry" command after the last icon entry of the group.

• blank
  

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

Regular Strings, Internationalized Strings and Language Keys

In the configuration file syntax, you can find the non-terminal symbols "string" and "lang_string". Both are strings, enclosed by a double quote ("). A "lang_string" can be a regular string or a language key that maps to a string. A string that is using a language key is called internationalized string, because the mapping can be exchanged in order to support different languages. The chapter about internationalization describes this mechanism in detail. A language key always starts with "#%..." and is replaced by the value it currently maps to at run-time. Note that the non-terminal symbol "string" in the syntax must not be a language key.

Activation and Deactivation of Menus and Icons

All menus and icons that are defined in a configuration file are automatically deactivated after starting uDraw(Graph) (system menus/icons used in a configuration file are not affected). The application program has to activate them with the API commands gui(activate_menus(...)) and gui(activate_icons(...)) Both commands enable the menus (or icons) specified in the parameter and automatically disable all remaining application menus (or icons).

The system menus/icons are activated or deactivated by uDraw(Graph). Menu entries defined with command submenu_entry, menu and help_menu are only containers for other menu entries and do not need to be manually activated by the application. They are automatically activated by uDraw(Graph) when at least one of their entries is activated and they are deactivated otherwise. Note that this feature is not available for the traditional way of user interface extension when submenus are created with API command app_menu(create_menus(...)).

Transition from User Interface Extensions

If your application program has taken advantage of user interface extensions known from previous releases by using API command app_menu(control_file_events) and you want to migrate to the user interface configuration described here, then you can simply use (or derive from) the predefined configuration file "$UDG_HOME/lib/uDrawGraph/uDrawGraph_cfe.menu". For the dynamic part, simply use the API command gui(activate_menus(...)) instead of app_menu(activate_menus(...)) and gui(activate_icons(...)) instead of app_menu(activate_icons(...)). In this case, your application program has to be modified at one point, because the following API command activates both the menus and icons of the corresponding operations:

With user interface configuration this has to be done in two steps: