The GnomeUIInfo structure

Gnome Developers' Information
Prev	Chapter 7. Automatic menu and toolbar creation with GnomeAppHelper	Next

7.3. The GnomeUIInfo structure

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.

type

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:

GNOME_APP_UI_ITEM

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.

GNOME_APP_UI_TOGGLEITEM

This indicates that a a toggle item should be created. By default it starts in the inactive state.

GNOME_APP_UI_RADIOITEMS

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.

GNOME_APP_UI_SUBTREE

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.

GNOME_APP_UI_SEPARATOR

This indicates that a separator should be created. For menus this is a separator line, and for toolbars it is a blank space.

GNOME_APP_UI_HELP

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.

GNOME_APP_UI_JUSTIFY_RIGHT

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.

GNOME_APP_UI_BUILDER_DATA

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.

GNOME_APP_UI_ENDOFINFO

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.

GNOME_APP_UI_ITEM_CONFIGURABLE

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 Section 7.5. These should probably not be used manually. Each possible configurable item has a matching convenience macro (see Section 7.4).

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.

label

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".

hint

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.

moreinfo