<!-- ##### SECTION Title ##### -->GtkUIManager<!-- ##### SECTION Short_Description ##### -->Constructing menus and toolbars from an XML description<!-- ##### SECTION Long_Description ##### --><para>A #GtkUIManager constructs a user interface (menus and toolbars) fromone or more UI definitions, which reference actions from one or more action groups. </para><refsect2 id="XML-UI"><title>UI Definitions</title><para>The UI definitions are specified in an XML format which can beroughly described by the following DTD. <programlisting>&lt;!ELEMENT ui          (menubar|toolbar|popup|accelerator)* &gt;&lt;!ELEMENT menubar     (menuitem|separator|placeholder|menu)* &gt;&lt;!ELEMENT menu        (menuitem|separator|placeholder|menu)* &gt;&lt;!ELEMENT popup       (menuitem|separator|placeholder|menu)* &gt;&lt;!ELEMENT toolbar     (toolitem|separator|placeholder)* &gt;&lt;!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* &gt;&lt;!ELEMENT menuitem     EMPTY &gt;&lt;!ELEMENT toolitem     EMPTY &gt;&lt;!ELEMENT separator    EMPTY &gt;&lt;!ELEMENT accelerator  EMPTY &gt;&lt;!ATTLIST menubar      name               &num;IMPLIED                        action             &num;IMPLIED &gt;&lt;!ATTLIST toolbar      name               &num;IMPLIED                        action             &num;IMPLIED &gt;&lt;!ATTLIST popup        name               &num;IMPLIED                        action             &num;IMPLIED &gt;&lt;!ATTLIST placeholder  name               &num;IMPLIED                       action             &num;IMPLIED &gt;&lt;!ATTLIST separator    name               &num;IMPLIED                       action             &num;IMPLIED &gt;&lt;!ATTLIST menu         name               &num;IMPLIED                       action             &num;REQUIRED                       position (top|bot) &num;IMPLIED &gt;&lt;!ATTLIST menuitem     name               &num;IMPLIED                       action             &num;REQUIRED                       position (top|bot) &num;IMPLIED &gt;&lt;!ATTLIST toolitem     name               &num;IMPLIED                       action             &num;REQUIRED                       position (top|bot) &num;IMPLIED &gt;&lt;!ATTLIST accelerator  name               &num;IMPLIED                       action             &num;REQUIRED &gt;</programlisting>There are some additional restrictions beyond those specified in theDTD, e.g. every toolitem must have a toolbar in its anchestry andevery menuitem must have a menubar or popup in its anchestry. Sincea #GMarkup parser is used to parse the UI description, it must not onlybe valid XML, but valid #GMarkup. </para><para>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 &amp;quot; entity.</para><example><title>A UI definition</title><programlisting>&lt;ui&gt;  &lt;menubar&gt;    &lt;menu name="FileMenu" action="FileMenuAction"&gt;      &lt;menuitem name="New" action="New2Action" /&gt;      &lt;placeholder name="FileMenuAdditions" /&gt;    &lt;/menu&gt;    &lt;menu name="JustifyMenu" action="JustifyMenuAction"&gt;      &lt;menuitem name="Left" action="justify-left"/&gt;      &lt;menuitem name="Centre" action="justify-center"/&gt;      &lt;menuitem name="Right" action="justify-right"/&gt;      &lt;menuitem name="Fill" action="justify-fill"/&gt;    &lt;/menu&gt;  &lt;/menubar&gt;  &lt;toolbar action="toolbar1"&gt;    &lt;placeholder name="JustifyToolItems"&gt;      &lt;separator/&gt;      &lt;toolitem name="Left" action="justify-left"/&gt;      &lt;toolitem name="Centre" action="justify-center"/&gt;      &lt;toolitem name="Right" action="justify-right"/&gt;      &lt;toolitem name="Fill" action="justify-fill"/&gt;      &lt;separator/&gt;    &lt;/placeholder&gt;  &lt;/toolbar&gt;&lt;/ui&gt;</programlisting></example><para>The constructed widget hierarchy is very similar to the element treeof the XML, with the exception that placeholders are merged into theirparents. The correspondence of XML elements to widgets should bealmost obvious: <variablelist><varlistentry><term>menubar</term><listitem><para>a #GtkMenuBar</para></listitem></varlistentry><varlistentry><term>toolbar</term><listitem><para>a #GtkToolbar</para></listitem></varlistentry><varlistentry><term>popup</term><listitem><para>a toplevel #GtkMenu</para></listitem></varlistentry><varlistentry><term>menu</term><listitem><para>a #GtkMenu attached to a menuitem</para></listitem></varlistentry><varlistentry><term>menuitem</term><listitem><para>a #GtkMenuItem subclass, the exact type depends on theaction</para></listitem> </varlistentry><varlistentry><term>toolitem</term><listitem><para>a #GtkToolItem subclass, the exact type depends on theaction</para></listitem> </varlistentry><varlistentry><term>separator</term><listitem><para>a #GtkSeparatorMenuItem or#GtkSeparatorToolItem</para></listitem> </varlistentry><varlistentry><term>accelerator</term><listitem><para>a keyboard accelerator</para></listitem> </varlistentry></variablelist></para><para>The "position" attribute determines where a constructed widget is positionedwrt. to its siblings in the partially constructed tree. If it is"top", the widget is prepended, otherwise it is appended.</para></refsect2><refsect2 id="UI-Merging"><title>UI Merging</title><para>The most remarkable feature of #GtkUIManager is that it can overlay a setof menuitems and toolitems over another one, and demerge them later.</para><para>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, separatedby slashes. For example, the menuitem named "Left" in the example abovehas the path <literal>/ui/menubar/JustifyMenu/Left</literal> and thetoolitem with the same name has path <literal>/ui/toolbar1/JustifyToolItems/Left</literal>.</para></refsect2><refsect2><title>Accelerators</title><para>Every action has an accelerator path. Accelerators are installed together withmenuitem proxies, but they can also be explicitly added with &lt;accelerator&gt;elements in the UI definition. This makes it possible to have accelerators foractions even if they have no visible proxies.</para></refsect2><refsect2 id="Smart-Separators"><title>Smart Separators</title><para>The separators created by #GtkUIManager are "smart", i.e. they do not show up in the UI unless they end up between two visible menu or tool items. Separatorswhich 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.</para></refsect2><refsect2><title>Empty Menus</title><para>Submenus pose similar problems to separators inconnection with merging. It is impossible to know in advance whether they will end up empty after merging. #GtkUIManager offers two ways to treat empty submenus:<itemizedlist><listitem><para>make them disappear by hiding the menu item they're attached to</para></listitem><listitem><para>add an insensitive "Empty" item</para></listitem></itemizedlist>The behaviour is chosen based on the "hide_if_empty" property of the action to which the submenu is associated.</para></refsect2><!-- ##### SECTION See_Also ##### --><para></para><!-- ##### SECTION Stability_Level ##### --><!-- ##### STRUCT GtkUIManager ##### --><para>The <structname>GtkUIManager</structname> struct contains only privatemembers and should not be accessed directly.</para><!-- ##### SIGNAL GtkUIManager::actions-changed ##### --><para></para>@uimanager: the object which received the signal.<!-- ##### SIGNAL GtkUIManager::add-widget ##### --><para></para>@uimanager: the object which received the signal.@widget: <!-- ##### SIGNAL GtkUIManager::connect-proxy ##### --><para></para>@uimanager: the object which received the signal.@arg1: @widget: <!-- ##### SIGNAL GtkUIManager::disconnect-proxy ##### --><para></para>@uimanager: the object which received the signal.@arg1: @widget: <!-- ##### SIGNAL GtkUIManager::post-activate ##### --><para></para>@uimanager: the object which received the signal.@arg1: <!-- ##### SIGNAL GtkUIManager::pre-activate ##### --><para></para>@uimanager: the object which received the signal.@arg1: <!-- ##### ARG GtkUIManager:add-tearoffs ##### --><para></para><!-- ##### ARG GtkUIManager:ui ##### --><para></para><!-- ##### FUNCTION gtk_ui_manager_new ##### --><para></para>@Returns: <!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### --><para></para>@self: @add_tearoffs: <!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### --><para></para>@self: @Returns: <!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### --><para></para>@self: @action_group: @pos: <!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### --><para></para>@self: @action_group: <!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### --><para></para>@self: @Returns: <!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### --><para></para>@self: @Returns: <!-- ##### FUNCTION gtk_ui_manager_get_widget ##### --><para></para>@self: @path: @Returns: <!-- ##### FUNCTION gtk_ui_manager_get_toplevels ##### --><para></para>@self: @types: @Returns: <!-- ##### FUNCTION gtk_ui_manager_get_action ##### --><para></para>@self: @path: @Returns: <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### --><para></para>@self: @buffer: @length: @error: @Returns: <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### --><para></para>@self: @filename: @error: @Returns: <!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### --><para></para>@self: @Returns: <!-- ##### ENUM GtkUIManagerItemType ##### --><para>These enumeration values are used by gtk_ui_manager_add_ui() to determinewhat UI element to create.</para>@GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context.@GTK_UI_MANAGER_MENUBAR: Create a menubar.@GTK_UI_MANAGER_MENU: Create a menu.@GTK_UI_MANAGER_TOOLBAR: Create a toolbar.@GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder.@GTK_UI_MANAGER_POPUP: Create a popup menu.@GTK_UI_MANAGER_MENUITEM: Create a menuitem.@GTK_UI_MANAGER_TOOLITEM: Create a toolitem.@GTK_UI_MANAGER_SEPARATOR: Create a separator.@GTK_UI_MANAGER_ACCELERATOR: Install an accelerator.<!-- ##### FUNCTION gtk_ui_manager_add_ui ##### --><para></para>@self: @merge_id: @path: @name: @action: @type: @top: <!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### --><para></para>@self: @merge_id: <!-- ##### FUNCTION gtk_ui_manager_get_ui ##### --><para></para>@self: @Returns: <!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### --><para></para>@self: