------------------- UI Definitions -- -------------------
The UI definitions are specified in an XML format which can be roughly described by the following DTD. - - - - - - - - - - - - - - - - - - -
There are some additional restrictions beyond those specified in the DTD, e.g. every toolitem must have a toolbar in its ancestry and every menuitem must have a menubar or popup in its ancestry. Since a GMarkup parser is used to parse the UI description, it must not only be valid XML, but valid GMarkup.
If a name is not specified, it defaults to the action. If an action is not specified either, the element name is used. The name and action attributes must not contain '/' characters after parsing (since that would mess up path lookup) and must be usable as XML attributes when enclosed in doublequotes, thus they must not '"' characters or references to the " entity.
Here is an example:
The constructed widget hierarchy is very similar to the element tree of the XML, with the exception that placeholders are merged into their parents. The correspondence of XML elements to widgets should be almost obvious:
- menubar : a Gtk_Menu_Bar - toolbar : a Gtk_Toolbar - popup : a toplevel Gtk_Menu - menu : a Gtk_Menu attached to a menuitem - menuitem : a Gtk_Menu_Item subclass, the exact type depends on the action - toolitem : a Gtk_Tool_Item subclass, exact type depends on the action. This may contain a menu element only if the associated action specifies a Gtk_Menu_Tool_Button as proxy - separator : a Gtk_Separator_Menu_Item or Gtk_Separator_Tool_Item - accelerator : a keyboard accelerator
The "position" attribute determines where a constructed widget is positioned wrt. to its siblings in the partially constructed tree. If it is "top", the widget is prepended, otherwise it is appended.
--------------- UI Merging -- ---------------
The most remarkable feature of Gtk_UI_Manager is that it can overlay a set of menuitems and toolitems over another one, and demerge them later.
Merging is done based on the names of the XML elements. Each element is identified by a path which consists of the names of its anchestors, separated by slashes. For example, the menuitem named "Left" in the example above has the path /ui/menubar/JustifyMenu/Left and the toolitem with the same name has path /ui/toolbar1/JustifyToolItems/Left.
----------------- Accelerators -- -----------------
Every action has an accelerator path. Accelerators are installed together
with menuitem proxies, but they can also be explicitly added with
---------------------
Smart Separators --
---------------------
The separators created by Gtk_UI_Manager are "smart", i.e. they do not show
up in the UI unless they end up between two visible menu or tool items.
Separators which are located at the very beginning or end of the menu or
toolbar containing them, or multiple separators next to each other, are
hidden. This is a useful feature, since the merging of UI elements from
multiple sources can make it hard or impossible to determine in advance
whether a separator will end up in such an unfortunate position.
For separators in toolbars, you can set expand="true" to turn them from a
small, visible separator to an expanding, invisible one. Toolitems
following an expanding separator are effectively right-aligned.
----------------
Empty Menus --
----------------
Submenus pose similar problems to separators inconnection with merging. It
is impossible to know in advance whether they will end up empty after
merging. Gtk_UI_Manager offers two ways to treat empty submenus:
- make them disappear by hiding the menu item they're attached to
- add an insensitive "Empty" item
The behaviour is chosen based on the "hide_if_empty" property of the action
to which the submenu is associated.
If Typ is Manager_Auto, GTK+ inserts a menuitem, toolitem or separator if such an element can be inserted at the place determined by Path. Otherwise Typ must indicate an element that can be inserted at the place determined by Path.
If Path points to a menuitem or toolitem, the new element will be inserted before or after this item, depending on Top.
Merge_Id: see New_Merge_Id. Action should be the empty string for a separator.
Note that the widget found by following a path that ends in a