1 2@c %start of fragment 3 4@node GtkUIManager 5@chapter GtkUIManager 6Constructing menus and toolbars from an XML description 7 8@section Overview 9A @code{<gtk-ui-manager>} constructs a user interface (menus and toolbars) from 10one or more UI definitions, which reference actions from one or more action 11groups. 12 13@section UI Definitions 14The UI definitions are specified in an XML format which can be roughly described 15by the following DTD. There are some additional restrictions beyond those 16specified in the DTD, e.g. every toolitem must have a toolbar in its anchestry 17and every menuitem must have a menubar or popup in its anchestry. Since a 18@code{<g-markup>} parser is used to parse the UI description, it must not only 19be valid XML, but valid @code{<g-markup>}. 20 21@example 22 23<!ELEMENT ui (menubar|toolbar|popup|accelerator)* > 24<!ELEMENT menubar (menuitem|separator|placeholder|menu)* > 25<!ELEMENT menu (menuitem|separator|placeholder|menu)* > 26<!ELEMENT popup (menuitem|separator|placeholder|menu)* > 27<!ELEMENT toolbar (toolitem|separator|placeholder)* > 28<!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* > 29<!ELEMENT menuitem EMPTY > 30<!ELEMENT toolitem (menu?) > 31<!ELEMENT separator EMPTY > 32<!ELEMENT accelerator EMPTY > 33<!ATTLIST menubar name #IMPLIED 34 action #IMPLIED > 35<!ATTLIST toolbar name #IMPLIED 36 action #IMPLIED > 37<!ATTLIST popup name #IMPLIED 38 action #IMPLIED > 39<!ATTLIST placeholder name #IMPLIED 40 action #IMPLIED > 41<!ATTLIST separator name #IMPLIED 42 action #IMPLIED 43 expand (true|false) #IMPLIED > 44<!ATTLIST menu name #IMPLIED 45 action #REQUIRED 46 position (top|bot) #IMPLIED > 47<!ATTLIST menuitem name #IMPLIED 48 action #REQUIRED 49 position (top|bot) #IMPLIED > 50<!ATTLIST toolitem name #IMPLIED 51 action #REQUIRED 52 position (top|bot) #IMPLIED > 53<!ATTLIST accelerator name #IMPLIED 54 action #REQUIRED > 55@end example 56 57If a name is not specified, it defaults to the action. If an action is not 58specified either, the element name is used. The name and action attributes must 59not contain '/' characters after parsing (since that would mess up path lookup) 60and must be usable as XML attributes when enclosed in doublequotes, thus they 61must not '"' characters or references to the " entity. 62 63@example 64 65<ui> 66 <menubar> 67 <menu name="FileMenu" action="FileMenuAction"> 68 <menuitem name="New" action="New2Action" /> 69 <placeholder name="FileMenuAdditions" /> 70 </menu> 71 <menu name="JustifyMenu" action="JustifyMenuAction"> 72 <menuitem name="Left" action="justify-left"/> 73 <menuitem name="Centre" action="justify-center"/> 74 <menuitem name="Right" action="justify-right"/> 75 <menuitem name="Fill" action="justify-fill"/> 76 </menu> 77 </menubar> 78 <toolbar action="toolbar1"> 79 <placeholder name="JustifyToolItems"> 80 <separator/> 81 <toolitem name="Left" action="justify-left"/> 82 <toolitem name="Centre" action="justify-center"/> 83 <toolitem name="Right" action="justify-right"/> 84 <toolitem name="Fill" action="justify-fill"/> 85 <separator/> 86 </placeholder> 87 </toolbar> 88</ui> 89@end example 90 91The constructed widget hierarchy is very similar to the element tree of the XML, 92with the exception that placeholders are merged into their parents. The 93correspondence of XML elements to widgets should be almost obvious: 94 95@table @var 96@item toolbar 97 98@c %start of fragment 99 100 101@c %end of fragment 102@item popup 103 104@c %start of fragment 105 106 107@c %end of fragment 108@item menu 109 110@c %start of fragment 111 112 113@c %end of fragment 114@item menuitem 115 116@c %start of fragment 117 118 119@c %end of fragment 120@item toolitem 121 122@c %start of fragment 123 124 125@c %end of fragment 126@item separator 127 128@c %start of fragment 129 130 131@c %end of fragment 132@item accelerator 133 134@c %start of fragment 135 136 137@c %end of fragment 138@end table 139 140a @code{<gtk-menu-bar>} 141 142a @code{<gtk-toolbar>} 143 144a toplevel @code{<gtk-menu>} 145 146a @code{<gtk-menu>} attached to a menuitem 147 148a @code{<gtk-menu-item>} subclass, the exact type depends on the action 149 150a @code{<gtk-tool-item>} subclass, the exact type depends on the action. Note 151that toolitem elements may contain a menu element, but only if their associated 152action specifies a @code{<gtk-menu-tool-button>} as proxy. 153 154a @code{<gtk-separator-menu-item>} or @code{<gtk-separator-tool-item>} 155 156a keyboard accelerator 157 158The "position" attribute determines where a constructed widget is positioned 159wrt. to its siblings in the partially constructed tree. If it is "top", the 160widget is prepended, otherwise it is appended. 161 162@section UI Merging 163The most remarkable feature of @code{<gtk-ui-manager>} is that it can overlay a 164set of menuitems and toolitems over another one, and demerge them later. 165 166Merging is done based on the names of the XML elements. Each element is 167identified by a path which consists of the names of its anchestors, separated by 168slashes. For example, the menuitem named "Left" in the example above has the 169path @samp{/ui/menubar/JustifyMenu/Left} and the toolitem with the same name has 170path @samp{/ui/toolbar1/JustifyToolItems/Left}. 171 172@section Accelerators 173Every action has an accelerator path. Accelerators are installed together with 174menuitem proxies, but they can also be explicitly added with <accelerator> 175elements in the UI definition. This makes it possible to have accelerators for 176actions even if they have no visible proxies. 177 178@section Smart Separators 179The separators created by @code{<gtk-ui-manager>} are "smart", i.e. they do not 180show up in the UI unless they end up between two visible menu or tool items. 181Separators which are located at the very beginning or end of the menu or toolbar 182containing them, or multiple separators next to each other, are hidden. This is 183a useful feature, since the merging of UI elements from multiple sources can 184make it hard or impossible to determine in advance whether a separator will end 185up in such an unfortunate position. 186 187For separators in toolbars, you can set @samp{expand="true"} to turn them from a 188small, visible separator to an expanding, invisible one. Toolitems following an 189expanding separator are effectively right-aligned. 190 191@section Empty Menus 192Submenus pose similar problems to separators inconnection with merging. It is 193impossible to know in advance whether they will end up empty after merging. 194@code{<gtk-ui-manager>} offers two ways to treat empty submenus: The behaviour 195is chosen based on the "hide_if_empty" property of the action to which the 196submenu is associated. 197 198make them disappear by hiding the menu item they're attached to 199 200add an insensitive "Empty" item 201 202@section Usage 203@include defuns-gtkuimanager.xml.texi 204 205@c %end of fragment 206