Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkuimanager.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkUIManager
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 constructing menus and toolbars from an XML description
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GtkUIManager constructs a user interface (menus and toolbars) from
  10 one or more UI definitions, which reference actions from one or more
  11 action groups.
  12 </para>
  13 <refsect2 id="XML-UI"><title>UI Definitions</title>
  14 <para>
  15 The UI definitions are specified in an XML format which can be
  16 roughly described by the following DTD.
  17 <programlisting>
  18 &lt;!ELEMENT ui          (menubar|toolbar|popup|accelerator)* &gt;
  19 &lt;!ELEMENT menubar     (menuitem|separator|placeholder|menu)* &gt;
  20 &lt;!ELEMENT menu        (menuitem|separator|placeholder|menu)* &gt;
  21 &lt;!ELEMENT popup       (menuitem|separator|placeholder|menu)* &gt;
  22 &lt;!ELEMENT toolbar     (toolitem|separator|placeholder)* &gt;
  23 &lt;!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* &gt;
  24 &lt;!ELEMENT menuitem     EMPTY &gt;
  25 &lt;!ELEMENT toolitem     EMPTY &gt;
  26 &lt;!ELEMENT separator    EMPTY &gt;
  27 &lt;!ELEMENT accelerator  EMPTY &gt;
  28 &lt;!ATTLIST menubar      name               &num;IMPLIED &gt;
  29 &lt;!ATTLIST toolbar      name               &num;IMPLIED &gt;
  30 &lt;!ATTLIST popup        name               &num;IMPLIED &gt;
  31 &lt;!ATTLIST placeholder  name               &num;IMPLIED &gt;
  32 &lt;!ATTLIST menu         name               &num;IMPLIED
  33                        action             &num;REQUIRED
  34                        position (top|bot) &num;IMPLIED &gt;
  35 &lt;!ATTLIST menuitem     name               &num;IMPLIED
  36                        action             &num;REQUIRED
  37                        position (top|bot) &num;IMPLIED &gt;
  38 &lt;!ATTLIST toolitem     name               &num;IMPLIED
  39                        action             &num;REQUIRED
  40                        position (top|bot) &num;IMPLIED &gt;
  41 &lt;!ATTLIST accelerator  name               &num;IMPLIED
  42                        action             &num;REQUIRED &gt;
  43 </programlisting>
  44 There are some additional restrictions beyond those specified in the
  45 DTD, e.g. every toolitem must have a toolbar in its anchestry and
  46 every menuitem must have a menubar or popup in its anchestry. Since
  47 a #GMarkup parser is used to parse the UI description, it must not only
  48 be valid XML, but valid #GMarkup. If a name is not specified, it defaults
  49 to the action. If an action is not specified either, the element name is
  50 used.
  51 </para>
  52 <example>
  53 <title>A UI definition</title>
  54 <programlisting>
  55 &lt;ui&gt;
  56   &lt;menubar&gt;
  57     &lt;menu name="FileMenu" action="FileMenuAction"&gt;
  58       &lt;menuitem name="New" action="New2Action" /&gt;
  59       &lt;placeholder name="FileMenuAdditions" /&gt;
  60     &lt;/menu&gt;
  61     &lt;menu name="JustifyMenu" action="JustifyMenuAction"&gt;
  62       &lt;menuitem name="Left" action="justify-left"/&gt;
  63       &lt;menuitem name="Centre" action="justify-center"/&gt;
  64       &lt;menuitem name="Right" action="justify-right"/&gt;
  65       &lt;menuitem name="Fill" action="justify-fill"/&gt;
  66     &lt;/menu&gt;
  67   &lt;/menubar&gt;
  68   &lt;toolbar action="toolbar1"&gt;
  69     &lt;placeholder name="JustifyToolItems"&gt;
  70       &lt;separator/&gt;
  71       &lt;toolitem name="Left" action="justify-left"/&gt;
  72       &lt;toolitem name="Centre" action="justify-center"/&gt;
  73       &lt;toolitem name="Right" action="justify-right"/&gt;
  74       &lt;toolitem name="Fill" action="justify-fill"/&gt;
  75       &lt;separator/&gt;
  76     &lt;/placeholder&gt;
  77   &lt;/toolbar&gt;
  78 &lt;/ui&gt;
  79 </programlisting>
  80 </example>
  81 <para>
  82 The constructed widget hierarchy is very similar to the element tree
  83 of the XML, with the exception that placeholders are merged into their
  84 parents. The correspondence of XML elements to widgets should be
  85 almost obvious:
  86 <variablelist>
  87 <varlistentry><term>menubar</term>
  88 <listitem><para>a #GtkMenuBar</para></listitem>
  89 </varlistentry>
  90 <varlistentry><term>toolbar</term>
  91 <listitem><para>a #GtkToolbar</para></listitem>
  92 </varlistentry>
  93 <varlistentry><term>popup</term>
  94 <listitem><para>a toplevel #GtkMenu</para></listitem>
  95 </varlistentry>
  96 <varlistentry><term>menu</term>
  97 <listitem><para>a #GtkMenu attached to a menuitem</para></listitem>
  98 </varlistentry>
  99 <varlistentry><term>menuitem</term>
 100 <listitem><para>a #GtkMenuItem subclass, the exact type depends on the
 101 action</para></listitem>
 102 </varlistentry>
 103 <varlistentry><term>toolitem</term>
 104 <listitem><para>a #GtkToolItem subclass, the exact type depends on the
 105 action</para></listitem>
 106 </varlistentry>
 107 <varlistentry><term>separator</term>
 108 <listitem><para>a #GtkSeparatorMenuItem or
 109 #GtkSeparatorToolItem</para></listitem>
 110 </varlistentry>
 111 <varlistentry><term>accelerator</term>
 112 <listitem><para>a keyboard accelerator</para></listitem>
 113 </varlistentry>
 114 </variablelist>
 115 </para>
 116 <para>
 117 The "position" attribute determines where a constructed widget is positioned
 118 wrt. to its siblings in the partially constructed tree. If it is
 119 "top", the widget is prepended, otherwise it is appended.
 120 </para>
 121 </refsect2>
 122 <refsect2 id="UI-Merging">
 123 <title>UI Merging</title>
 124 <para>
 125 The most remarkable feature of #GtkUIManager is that it can overlay a set
 126 of menuitems and toolitems over another one, and demerge them later.
 127 </para>
 128 <para>
 129 Merging is done based on the name of the XML elements. Each element is
 130 identified by a path which consists of the names of its anchestors, separated
 131 by slashes. For example, the menuitem named "Left" in the example above
 132 has the path <literal>/ui/menubar/JustifyMenu/Left</literal> and the
 133 toolitem with the same name has path
 134 <literal>/ui/toolbar1/JustifyToolItems/Left</literal>.
 135 </para>
 136 </refsect2>
 137 <refsect2>
 138 <title>Accelerators</title>
 139 <para>
 140 Every action has an accelerator path. Accelerators are installed together with
 141 menuitem proxies, but they can also be explicitly added with &lt;accelerator&gt;
 142 elements in the UI definition. This makes it possible to have accelerators for
 143 actions even if they have no visible proxies.
 144 </para>
 145 </refsect2>
 146 <refsect2 id="Smart-Separators">
 147 <title>Smart Separators</title>
 148 <para>
 149 The separators created by #GtkUIManager are "smart", i.e. they do not show up in the
 150 UI unless they end up between two visible menu or tool items. Separators which are located
 151 at the very beginning or end of the menu or toolbar containing them, or multiple separators
 152 next to each other, are hidden. This is a useful feature, since the merging of UI elements
 153 from multiple sources can make it hard or impossible to determine in advance whether a
 154 separator will end up in such an unfortunate position.
 155 </para>
 156 </refsect2>
 157
 158 <!-- ##### SECTION See_Also ##### -->
 159 <para>
 160
 161 </para>
 162
 163 <!-- ##### STRUCT GtkUIManager ##### -->
 164 <para>
 165 The <structname>GtkUIManager</structname> struct contains only private
 166 members and should not be accessed directly.
 167 </para>
 168
 169
 170 <!-- ##### FUNCTION gtk_ui_manager_new ##### -->
 171 <para>
 172
 173 </para>
 174
 175 @Returns:
 176
 177
 178 <!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
 179 <para>
 180
 181 </para>
 182
 183 @self:
 184 @add_tearoffs:
 185
 186
 187 <!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @self:
 193 @Returns:
 194
 195
 196 <!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
 197 <para>
 198
 199 </para>
 200
 201 @self:
 202 @action_group:
 203 @pos:
 204
 205
 206 <!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
 207 <para>
 208
 209 </para>
 210
 211 @self:
 212 @action_group:
 213
 214
 215 <!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
 216 <para>
 217
 218 </para>
 219
 220 @self:
 221 @Returns:
 222
 223
 224 <!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
 225 <para>
 226
 227 </para>
 228
 229 @self:
 230 @Returns:
 231
 232
 233 <!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
 234 <para>
 235
 236 </para>
 237
 238 @self:
 239 @path:
 240 @Returns:
 241
 242
 243 <!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
 244 <para>
 245
 246 </para>
 247
 248 @self:
 249 @path:
 250 @Returns:
 251
 252
 253 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
 254 <para>
 255
 256 </para>
 257
 258 @self:
 259 @buffer:
 260 @length:
 261 @error:
 262 @Returns:
 263
 264
 265 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
 266 <para>
 267
 268 </para>
 269
 270 @self:
 271 @filename:
 272 @error:
 273 @Returns:
 274
 275
 276 <!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### -->
 277 <para>
 278
 279 </para>
 280
 281 @self:
 282 @Returns:
 283
 284
 285 <!-- ##### ENUM GtkUIManagerItemType ##### -->
 286 <para>
 287 These enumeration values are used by gtk_ui_manager_add_ui() to determine
 288 what UI element to create.
 289 </para>
 290
 291 @GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context.
 292 @GTK_UI_MANAGER_MENUBAR: Create a menubar.
 293 @GTK_UI_MANAGER_MENU: Create a menu.
 294 @GTK_UI_MANAGER_TOOLBAR: Create a toolbar.
 295 @GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder.
 296 @GTK_UI_MANAGER_POPUP: Create a popup menu.
 297 @GTK_UI_MANAGER_MENUITEM: Create a menuitem.
 298 @GTK_UI_MANAGER_TOOLITEM: Create a toolitem.
 299 @GTK_UI_MANAGER_SEPARATOR: Create a separator.
 300 @GTK_UI_MANAGER_ACCELERATOR: Install an accelerator.
 301
 302 <!-- ##### FUNCTION gtk_ui_manager_add_ui ##### -->
 303 <para>
 304
 305 </para>
 306
 307 @self:
 308 @merge_id:
 309 @path:
 310 @name:
 311 @action:
 312 @type:
 313 @top:
 314
 315
 316 <!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
 317 <para>
 318
 319 </para>
 320
 321 @self:
 322 @merge_id:
 323
 324
 325 <!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
 326 <para>
 327
 328 </para>
 329
 330 @self:
 331 @Returns:
 332
 333
 334 <!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### -->
 335 <para>
 336
 337 </para>
 338
 339 @self:
 340
 341
 342 <!-- ##### SIGNAL GtkUIManager::actions-changed ##### -->
 343 <para>
 344
 345 </para>
 346
 347 @uimanager: the object which received the signal.
 348
 349 <!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
 350 <para>
 351
 352 </para>
 353
 354 @uimanager: the object which received the signal.
 355 @widget:
 356
 357 <!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
 358 <para>
 359
 360 </para>
 361
 362 <!-- ##### ARG GtkUIManager:ui ##### -->
 363 <para>
 364
 365 </para>
 366