| Gnome Developers' Information | ||
|---|---|---|
| <<< Previous | Automatic menu and toolbar creation with GnomeAppHelper | Next >>> |
GnomeAppHelper uses arrays of GnomeUIInfo structures to define the items that compose a menu bar or toolbar. Each item contains an optional icon and a text label. Each item has a callback function attached to it that gets invoked when the item is activated. Also, items may have a hotkey defined for them. Items may have a check-box or be grouped inside a radio group. Also, menu items may specify a subtree which they spawn.
The GnomeUIInfo structure is defined as follows.
typedef struct {
GnomeUIInfoType type ;
gchar *label;
gchar *hint;
gpointer moreinfo;
gpointer user_data;
gpointer unused_data;
GnomeUIPixmapType pixmap_type;
gpointer pixmap_info;
guint accelerator_key;
GdkModifierType ac_mods;
GtkWidget *widget;
} GnomeUIInfo;
|
These are the fields in the GnomeUIInfo structure.
This field is used to specify the type of item that should be created. The rest of the fields in the structure define the item's attributes. The type field can have the following values:
This indicates that a normal item should be created. If the item is inside a radio group (see below), then a radio item will be created, by default in its inactive state.
This indicates that a a toggle item should be created. By default it starts in the inactive state.
This indicates that a group of radio items should be created. The moreinfo field must point to an array of items that will be created as the radio items in the group. By default the first item will be the active item in the radio group.
This indicates that the created item should have a submenu attached to it. The moreinfo field must point to an array of items that will be put in the submenu. This item type is not supported in toolbars.
This indicates that a separator should be created. For menus this is a separator line, and for toolbars it is a blank space.
This indicates that help entries should be created. The moreinfo field must point to a string with the application's ID string. See below for additional information on creating the help entries.
This indicates that all subsequent items should be aligned on the right side of the menu they are on. This only works for menus and only makes sense for menu bars.
This is intended for language bindings and GUI builders — it is not needed for normal programs. It specifies that all subsequent items should use a different GnomeUIBuilderData structure from the one that was in use then the item was inserted. The moreinfo field should point to the desired GnomeUIBuilderData structure.
This is used to indicate the end of an array of items. It is very important to include an element of this type as the last entry in GnomeUIInfo arrays.
This is used to indicate that the values for this menu item should be loaded from a configuration file. A description of the format for the configuration file is given in the Section called Format information for the configuration of keybindings for standard mens. These should probably not be used manually. Each possible configurable item has a matching convenience macro (see the Section called Convenience macros to fill GnomeUIInfo structures).
However, for completeness, a description of the programmatic use of this type is given. When using this item, most of the data is ignored. The exceptions are three fold. Firstly, the moreinfo and data fields are treated exactly as in a GNOME_APP_UI_ITEM GnomeUIInfo array element. Secondly, the accelerator_key field is an integer cast from an element of the GNOMEUIInfoConfigurableTypes enum describing which configurable menu item this represents. Finally, if accelerator_key is 0, i.e. GNOME_APP_CONFIGURABLE_ITEM_NEW, then label and hint are both used verbatim.
The other fields in the GnomeUIInfo structure are used to specify the attributes of the item being defined.
This field is used to specify the text label for the item being created. The un-translated version of the label should be specified; GnomeAppHelper calls the translation routines itself.
For menu items it is desirable to have an underlined letter in the label, so that the user knows that he can press that letter on the keyboard and activate the corresponding menu item. To specify an underlined letter, put an underscore (_) before it in the label's string. Examples are, "_File", "_Edit", and "_Copy".
This field specifies an optional string that should be used for the tooltip in toolbar items or for the status bar hint in menu items. The un-translated version of the hint should be specified. If no hint string is desired, specify NULL.
This field is used to specify different things according to the type of item that is being defined.
For normal, radio, and toggle items (GNOME_APP_UI_ITEM, GNOME_APP_UI_ITEM, and GNOME_APP_UI_TOGGLEITEM, respectively), this field should point to the function that should be called when the item is activated. The general prototype of this function is as follows:
The item argument is the menu item or button in the toolbar that was selected, and the >user_data argument is the normal callback's user data.For submenus (subtrees, type GNOME_APP_UI_SUBTREE), this field should point to another array of GnomeUIInfo structures. This array defines the subtree.
For items of type GNOME_APP_UI_RADIOITEMS, this field should point to an array of GnomeUIInfo structures which defines the items that are to be put in the radio group. Within this array, only items of type GNOME_APP_UI_ITEM and GNOME_APP_UI_BUILDER_DATA are supported.
For items of type GNOME_APP_UI_HELP, this item should point to a string that is the application's ID name. GnomeAppHelper will look for the topic.dat file in the help directory defined by the application's ID string, read it, and include the appropriate help topics in the menu. This type is not valid for toolbars.
For items of type GNOME_APP_UI_BUILDER_DATA, this field should point to a GnomeUIBuilderData structure. The information in this structure will be used for all subsequent items in the array. This is normally only needed by language bindings and GUI builders.
For all other item types, this field is ignored. You should set it to NULL, however, for compatibility with future extensions to GnomeAppHelper.
This should point to the data you want to pass to the callback that will be activated when the menu or toolbar item is selected. Frequently you will leave this as NULL and pass a specific data pointer to all callbacks using the functions defined below.
This field is reserved for future expansion, and should be set to NULL.
This should be one of the following values.
Specifies that no icon should be used for this item.
Specifies that a stock icon should be used. The name or identifier of the icon should be specified in the pixmap_info field.
Specifies that an icon created from inline XPM data should be used. A pointer to the XPM data must be specified in the pixmap_info field.
Specifies that an image file should be loaded and used as an icon. The file name must be specified in the pixmap_info field.
This field specifies the information used to create the pixmap for the item's icon.
For icons of type GNOME_APP_PIXMAP_NONE, this field can be set to NULL.
For icons of type GNOME_APP_PIXMAP_STOCK, this field should point to a string with the stock icon's identifier. For menu items it is suggested that you use the GNOME_STOCK_MENU_* symbols. For toolbars, you should use the GNOME_STOCK_PIXMAP_* symbols.
For icons of type GNOME_APP_PIXMAP_DATA, this field should point to the inline XPM data from which the icon will be created.
For icons of type GNOME_APP_PIXMAP_FILENAME, this field should point to a string with the name of the image file to load. This image will be used as an icon.
This field is used to specify an optional accelerator key for the item. Applications should use the standard accelerator keys defined in the GNOME User Interface Guidelines.
You should specify the key code of the key you want to use as an accelerator. Key codes are listed in the gdkkeysyms.h include file.
This field is used to specify the modifier keys that should be used in conjunction with the key specified in the accelerator_key field for the item's accelerator. Applications should use the standard accelerator keys defined in the GNOME User Interface Guidelines.
The value in this field is a bit mask composed of the values in the GdkModifierType enumeration.
This field is filled in by the GnomeAppHelper functions. Once you have called one of the functions that take an array of GnomeUIInfo structures and turn it into a widget tree, the widget fields of the structures in the array will have pointers to the created widgets. You can use these pointers to do several operations like hide and show the items, and make them insensitive.
In addition to the plain GnomeUIInfo structures, GnomeAppHelper provides some macros to make filling these structures easier. These are most useful for items that require a few parameters and for toolbars, which do not have as many options as menus.
| <<< Previous | Home | Next >>> |
| A quick example of using GnomeAppHelper | Up | Convenience macros to fill GnomeUIInfo structures |