Migrating from GnomeUIInfo

Prior to GTK+ 2.4, some applications used the GnomeUIInfo
mechanism from
<libgnomeui/gnome-app-helper.h> to
define their menus and toolbars. With it, a program decleres an
array of GnomeUIInfo structures, which
contain information for menu or toolbar items such as their
label, icon, and accelerator key. Then, one calls
gnome_app_fill_menu() or gnome_app_fill_toolbar(), or one of the
related functions, to create the appropriate widgets based on
these structures.

A downside of this API is that the same structures are used to
pass back pointers to the widgets that got created. This means
that the structures cannot simply be kept around if the program
requires multiple instances of the user interface (e.g. several
windows); each new invocation of gnome_app_fill_menu() would
overwrite the widget fields of the structures.

Another disadvantage is that there is no automatic way to
synchronize the state of related controls. If there are toolbar
toogle buttons for "Bold", "Italic", "Underline", and also
corresponding menu items under "Format/Bold", etc., one has to
synchronize their toggled states by hand whenever the user
selects any one of them.

Finally, there is no way to do menu and toolbar merging for
applications that require embedded components.

To convert an application that uses GnomeUIInfo into the new
GtkAction mechanism, you need to do several things:

Separate your existing GnomeUIInfo entries into normal
actions, toggle actions, and radio actions, and then create
a separate array of GtkActionEntry structures
for each group. This will allow you to create the necessary
GtkActionGroup objects. Note that this does not describe
the actual "shape" that your menus and toolbars will have;
it simply defines the set of commands that will appear in them.

Create an XML description of your menus and toolbars for use
with GtkUIManager. This defines the actual shape of the menus
and toolbars.

If your GnomeUIInfo entries use GNOME_APP_PIXMAP_DATA or
GNOME_APP_PIXMAP_FILENAME for pixmaps, you have to create a
GtkIconFactory, add it to the list of default factories, then
create a GtkIconSet for each of your own icons. Add the sets to
the factory, and use the id in the GtkActionEntry like a regular
GTK+ stock id.

Example 58. GnomeUIInfo Example

The following code shows a declaration of a simple menu bar to
be used with gnome_app_fill_menu() or similar. The menu hierarchy i
looks like this:

The following code is the set of actions that are present in
the previous
example. Note that the toggle and radio entries are
separate from normal actions. Also, note that GtkActionEntry
structures take key names in the format of gtk_accelerator_parse()
rather than key values plus modifiers; you will have to convert these
values by hand. For example, GDK_F11 with no modifiers is equivalent
to a key name of "F11". Likewise, "o"
with GDK_CONTROL_MASK is equivalent to "<ontrol>O".

After extracting the actions, you will need to create an XML
description of the actual layout of your menus and toolbars
for use with GtkUIManager. The following code shows a simple
menu bar that corresponds to the previous
example. Note that the File and
View menus have their names specified in
the action
entries, not in the XML itself. This is because the
XML description only contains identifiers
for the items in the GUI, rather than human-readable names.