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 </para>
  18 <para>
  19 Do not confuse the GtkUIManager UI Definitions described here with
  20 the similarly named <link linkend="BUILDER-UI">GtkBuilder UI
  21 Definitions</link>.
  22 </para>
  23 <para>
  24 <programlisting><![CDATA[
  25 <!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >
  26 <!ELEMENT menubar     (menuitem|separator|placeholder|menu)* >
  27 <!ELEMENT menu        (menuitem|separator|placeholder|menu)* >
  28 <!ELEMENT popup       (menuitem|separator|placeholder|menu)* >
  29 <!ELEMENT toolbar     (toolitem|separator|placeholder)* >
  30 <!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
  31 <!ELEMENT menuitem     EMPTY >
  32 <!ELEMENT toolitem     (menu?) >
  33 <!ELEMENT separator    EMPTY >
  34 <!ELEMENT accelerator  EMPTY >
  35 <!ATTLIST menubar      name                      &num;IMPLIED
  36                        action                    &num;IMPLIED >
  37 <!ATTLIST toolbar      name                      &num;IMPLIED
  38                        action                    &num;IMPLIED >
  39 <!ATTLIST popup        name                      &num;IMPLIED
  40                        action                    &num;IMPLIED
  41                        accelerators (true|false) &num;IMPLIED >
  42 <!ATTLIST placeholder  name                      &num;IMPLIED
  43                        action                    &num;IMPLIED >
  44 <!ATTLIST separator    name                      &num;IMPLIED
  45                        action                    &num;IMPLIED
  46                        expand       (true|false) &num;IMPLIED >
  47 <!ATTLIST menu         name                      &num;IMPLIED
  48                        action                    &num;REQUIRED
  49                        position     (top|bot)    &num;IMPLIED >
  50 <!ATTLIST menuitem     name                      &num;IMPLIED
  51                        action                    &num;REQUIRED
  52                        position     (top|bot)    &num;IMPLIED
  53                        always-show-image (true|false) &num;IMPLIED >
  54 <!ATTLIST toolitem     name                      &num;IMPLIED
  55                        action                    &num;REQUIRED
  56                        position     (top|bot)    &num;IMPLIED >
  57 <!ATTLIST accelerator  name                      &num;IMPLIED
  58                        action                    &num;REQUIRED >
  59 ]]></programlisting>
  60 There are some additional restrictions beyond those specified in the
  61 DTD, e.g. every toolitem must have a toolbar in its anchestry and
  62 every menuitem must have a menubar or popup in its anchestry. Since
  63 a #GMarkup parser is used to parse the UI description, it must not only
  64 be valid XML, but valid #GMarkup.
  65 </para>
  66 <para>
  67 If a name is not specified, it defaults to the action. If an action is
  68 not specified either, the element name is used. The name and action
  69 attributes must not contain '/' characters after parsing (since that
  70 would mess up path lookup) and must be usable as XML attributes when
  71 enclosed in doublequotes, thus they must not '"' characters or references
  72 to the &amp;quot; entity.
  73 </para>
  74 <example>
  75 <title>A UI definition</title>
  76 <programlisting>
  77 &lt;ui&gt;
  78   &lt;menubar&gt;
  79     &lt;menu name="FileMenu" action="FileMenuAction"&gt;
  80       &lt;menuitem name="New" action="New2Action" /&gt;
  81       &lt;placeholder name="FileMenuAdditions" /&gt;
  82     &lt;/menu&gt;
  83     &lt;menu name="JustifyMenu" action="JustifyMenuAction"&gt;
  84       &lt;menuitem name="Left" action="justify-left"/&gt;
  85       &lt;menuitem name="Centre" action="justify-center"/&gt;
  86       &lt;menuitem name="Right" action="justify-right"/&gt;
  87       &lt;menuitem name="Fill" action="justify-fill"/&gt;
  88     &lt;/menu&gt;
  89   &lt;/menubar&gt;
  90   &lt;toolbar action="toolbar1"&gt;
  91     &lt;placeholder name="JustifyToolItems"&gt;
  92       &lt;separator/&gt;
  93       &lt;toolitem name="Left" action="justify-left"/&gt;
  94       &lt;toolitem name="Centre" action="justify-center"/&gt;
  95       &lt;toolitem name="Right" action="justify-right"/&gt;
  96       &lt;toolitem name="Fill" action="justify-fill"/&gt;
  97       &lt;separator/&gt;
  98     &lt;/placeholder&gt;
  99   &lt;/toolbar&gt;
 100 &lt;/ui&gt;
 101 </programlisting>
 102 </example>
 103 <para>
 104 The constructed widget hierarchy is very similar to the element tree
 105 of the XML, with the exception that placeholders are merged into their
 106 parents. The correspondence of XML elements to widgets should be
 107 almost obvious:
 108 <variablelist>
 109 <varlistentry><term>menubar</term>
 110 <listitem><para>a #GtkMenuBar</para></listitem>
 111 </varlistentry>
 112 <varlistentry><term>toolbar</term>
 113 <listitem><para>a #GtkToolbar</para></listitem>
 114 </varlistentry>
 115 <varlistentry><term>popup</term>
 116 <listitem><para>a toplevel #GtkMenu</para></listitem>
 117 </varlistentry>
 118 <varlistentry><term>menu</term>
 119 <listitem><para>a #GtkMenu attached to a menuitem</para></listitem>
 120 </varlistentry>
 121 <varlistentry><term>menuitem</term>
 122 <listitem><para>a #GtkMenuItem subclass, the exact type depends on the
 123 action</para></listitem>
 124 </varlistentry>
 125 <varlistentry><term>toolitem</term>
 126 <listitem><para>a #GtkToolItem subclass, the exact type depends on the
 127 action. Note that toolitem elements may contain a menu element, but only
 128 if their associated action specifies a #GtkMenuToolButton as proxy.</para></listitem>
 129 </varlistentry>
 130 <varlistentry><term>separator</term>
 131 <listitem><para>a #GtkSeparatorMenuItem or
 132 #GtkSeparatorToolItem</para></listitem>
 133 </varlistentry>
 134 <varlistentry><term>accelerator</term>
 135 <listitem><para>a keyboard accelerator</para></listitem>
 136 </varlistentry>
 137 </variablelist>
 138 </para>
 139 <para>
 140 The "position" attribute determines where a constructed widget is positioned
 141 wrt. to its siblings in the partially constructed tree. If it is
 142 "top", the widget is prepended, otherwise it is appended.
 143 </para>
 144 </refsect2>
 145 <refsect2 id="UI-Merging">
 146 <title>UI Merging</title>
 147 <para>
 148 The most remarkable feature of #GtkUIManager is that it can overlay a set
 149 of menuitems and toolitems over another one, and demerge them later.
 150 </para>
 151 <para>
 152 Merging is done based on the names of the XML elements. Each element is
 153 identified by a path which consists of the names of its anchestors, separated
 154 by slashes. For example, the menuitem named "Left" in the example above
 155 has the path <literal>/ui/menubar/JustifyMenu/Left</literal> and the
 156 toolitem with the same name has path
 157 <literal>/ui/toolbar1/JustifyToolItems/Left</literal>.
 158 </para>
 159 </refsect2>
 160 <refsect2>
 161 <title>Accelerators</title>
 162 <para>
 163 Every action has an accelerator path. Accelerators are installed together with
 164 menuitem proxies, but they can also be explicitly added with &lt;accelerator&gt;
 165 elements in the UI definition. This makes it possible to have accelerators for
 166 actions even if they have no visible proxies.
 167 </para>
 168 </refsect2>
 169 <refsect2 id="Smart-Separators">
 170 <title>Smart Separators</title>
 171 <para>
 172 The separators created by #GtkUIManager are "smart", i.e. they do not show up
 173 in the UI unless they end up between two visible menu or tool items. Separators
 174 which are located at the very beginning or end of the menu or toolbar
 175 containing them, or multiple separators next to each other, are hidden. This
 176 is a useful feature, since the merging of UI elements from multiple sources
 177 can make it hard or impossible to determine in advance whether a separator
 178 will end up in such an unfortunate position.
 179 </para>
 180
 181 <para>
 182 For separators in toolbars, you can set <literal>expand="true"</literal> to
 183 turn them from a small, visible separator to an expanding, invisible one.
 184 Toolitems following an expanding separator are effectively right-aligned.
 185 </para>
 186 </refsect2>
 187 <refsect2>
 188 <title>Empty Menus</title>
 189 <para>
 190 Submenus pose similar problems to separators inconnection with merging. It is
 191 impossible to know in advance whether they will end up empty after merging.
 192 #GtkUIManager offers two ways to treat empty submenus:
 193 <itemizedlist>
 194 <listitem><para>make them disappear by hiding the menu item they're attached to
 195 </para></listitem>
 196 <listitem><para>add an insensitive "Empty" item
 197 </para></listitem>
 198 </itemizedlist>
 199 The behaviour is chosen based on the "hide_if_empty" property of the action
 200 to which the submenu is associated.
 201 </para>
 202 </refsect2>
 203
 204 <refsect2 id="GtkUIManager-BUILDER-UI">
 205 <title>GtkUIManager as GtkBuildable</title>
 206 <para>
 207 The GtkUIManager implementation of the GtkBuildable interface accepts
 208 GtkActionGroup objects as &lt;child&gt; elements in UI definitions.
 209 </para>
 210 <para>
 211 A GtkUIManager UI definition as described above can be embedded in
 212 an GtkUIManager &lt;object&gt; element in a GtkBuilder UI definition.
 213 </para>
 214 <para>
 215 The widgets that are constructed by a GtkUIManager can be embedded in
 216 other parts of the constructed user interface with the help of the
 217 "constructor" attribute. See the example below.
 218 </para>
 219 <example>
 220 <title>An embedded GtkUIManager UI definition</title>
 221 <programlisting><![CDATA[
 222 <object class="GtkUIManager" id="uiman">
 223   <child>
 224     <object class="GtkActionGroup" id="actiongroup">
 225       <child>
 226         <object class="GtkAction" id="file">
 227           <property name="label">_File</property>
 228         </object>
 229       </child>
 230     </object>
 231   </child>
 232   <ui>
 233     <menubar name="menubar1">
 234       <menu action="file">
 235       </menu>
 236     </menubar>
 237   </ui>
 238 </object>
 239 <object class="GtkWindow" id="main-window">
 240   <child>
 241     <object class="GtkMenuBar" id="menubar1" constructor="uiman"/>
 242   </child>
 243 </object>
 244 ]]></programlisting>
 245 </example>
 246 </refsect2>
 247
 248 <!-- ##### SECTION See_Also ##### -->
 249 <para>
 250 #GtkBuilder
 251 </para>
 252
 253 <!-- ##### SECTION Stability_Level ##### -->
 254
 255
 256 <!-- ##### STRUCT GtkUIManager ##### -->
 257 <para>
 258 The <structname>GtkUIManager</structname> struct contains only private
 259 members and should not be accessed directly.
 260 </para>
 261
 262
 263 <!-- ##### SIGNAL GtkUIManager::actions-changed ##### -->
 264 <para>
 265
 266 </para>
 267
 268 @uimanager: the object which received the signal.
 269
 270 <!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
 271 <para>
 272
 273 </para>
 274
 275 @uimanager: the object which received the signal.
 276 @widget:
 277
 278 <!-- ##### SIGNAL GtkUIManager::connect-proxy ##### -->
 279 <para>
 280
 281 </para>
 282
 283 @uimanager: the object which received the signal.
 284 @arg1:
 285 @widget:
 286
 287 <!-- ##### SIGNAL GtkUIManager::disconnect-proxy ##### -->
 288 <para>
 289
 290 </para>
 291
 292 @uimanager: the object which received the signal.
 293 @arg1:
 294 @widget:
 295
 296 <!-- ##### SIGNAL GtkUIManager::post-activate ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @uimanager: the object which received the signal.
 302 @arg1:
 303
 304 <!-- ##### SIGNAL GtkUIManager::pre-activate ##### -->
 305 <para>
 306
 307 </para>
 308
 309 @uimanager: the object which received the signal.
 310 @arg1:
 311
 312 <!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
 313 <para>
 314
 315 </para>
 316
 317 <!-- ##### ARG GtkUIManager:ui ##### -->
 318 <para>
 319
 320 </para>
 321
 322 <!-- ##### FUNCTION gtk_ui_manager_new ##### -->
 323 <para>
 324
 325 </para>
 326
 327 @Returns:
 328
 329
 330 <!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
 331 <para>
 332
 333 </para>
 334
 335 @self:
 336 @add_tearoffs:
 337
 338
 339 <!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @self:
 345 @Returns:
 346
 347
 348 <!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
 349 <para>
 350
 351 </para>
 352
 353 @self:
 354 @action_group:
 355 @pos:
 356
 357
 358 <!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
 359 <para>
 360
 361 </para>
 362
 363 @self:
 364 @action_group:
 365
 366
 367 <!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @self:
 373 @Returns:
 374
 375
 376 <!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @self:
 382 @Returns:
 383
 384
 385 <!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
 386 <para>
 387
 388 </para>
 389
 390 @self:
 391 @path:
 392 @Returns:
 393
 394
 395 <!-- ##### FUNCTION gtk_ui_manager_get_toplevels ##### -->
 396 <para>
 397
 398 </para>
 399
 400 @self:
 401 @types:
 402 @Returns:
 403
 404
 405 <!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
 406 <para>
 407
 408 </para>
 409
 410 @self:
 411 @path:
 412 @Returns:
 413
 414
 415 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
 416 <para>
 417
 418 </para>
 419
 420 @self:
 421 @buffer:
 422 @length:
 423 @error:
 424 @Returns:
 425
 426
 427 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
 428 <para>
 429
 430 </para>
 431
 432 @self:
 433 @filename:
 434 @error:
 435 @Returns:
 436
 437
 438 <!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### -->
 439 <para>
 440
 441 </para>
 442
 443 @self:
 444 @Returns:
 445
 446
 447 <!-- ##### ENUM GtkUIManagerItemType ##### -->
 448 <para>
 449 These enumeration values are used by gtk_ui_manager_add_ui() to determine
 450 what UI element to create.
 451 </para>
 452
 453 @GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context.
 454 @GTK_UI_MANAGER_MENUBAR: Create a menubar.
 455 @GTK_UI_MANAGER_MENU: Create a menu.
 456 @GTK_UI_MANAGER_TOOLBAR: Create a toolbar.
 457 @GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder.
 458 @GTK_UI_MANAGER_POPUP: Create a popup menu.
 459 @GTK_UI_MANAGER_MENUITEM: Create a menuitem.
 460 @GTK_UI_MANAGER_TOOLITEM: Create a toolitem.
 461 @GTK_UI_MANAGER_SEPARATOR: Create a separator.
 462 @GTK_UI_MANAGER_ACCELERATOR: Install an accelerator.
 463 @GTK_UI_MANAGER_POPUP_WITH_ACCELS: Same as %GTK_UI_MANAGER_POPUP, but the actions' accelerators are shown.
 464
 465 <!-- ##### FUNCTION gtk_ui_manager_add_ui ##### -->
 466 <para>
 467
 468 </para>
 469
 470 @self:
 471 @merge_id:
 472 @path:
 473 @name:
 474 @action:
 475 @type:
 476 @top:
 477
 478
 479 <!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
 480 <para>
 481
 482 </para>
 483
 484 @self:
 485 @merge_id:
 486
 487
 488 <!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
 489 <para>
 490
 491 </para>
 492
 493 @self:
 494 @Returns:
 495
 496
 497 <!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### -->
 498 <para>
 499
 500 </para>
 501
 502 @self:
 503
 504