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
 150 in the UI unless they end up between two visible menu or tool items. Separators
 151 which are located at the very beginning or end of the menu or toolbar
 152 containing them, or multiple separators next to each other, are hidden. This
 153 is a useful feature, since the merging of UI elements from multiple sources
 154 can make it hard or impossible to determine in advance whether a separator
 155 will end up in such an unfortunate position.
 156 </para>
 157 </refsect2>
 158 <refsect2>
 159 <title>Empty Menus</title>
 160 <para>
 161 Submenus pose similar problems to separators inconnection with merging. It is
 162 impossible to know in advance whether they will end up empty after merging.
 163 #GtkUIManager offers two ways to treat empty submenus:
 164 <itemizedlist>
 165 <listitem><para>make them disappear by hiding the menu item they're attached to
 166 </para></listitem>
 167 <listitem><para>add an insensitive "Empty" item
 168 </para></listitem>
 169 </itemizedlist>
 170 The behaviour is chosen based on the "is_important" property of the action
 171 to which the submenu is associated.
 172 </para>
 173 </refsect2>
 174 <!-- ##### SECTION See_Also ##### -->
 175 <para>
 176
 177 </para>
 178
 179 <!-- ##### STRUCT GtkUIManager ##### -->
 180 <para>
 181 The <structname>GtkUIManager</structname> struct contains only private
 182 members and should not be accessed directly.
 183 </para>
 184
 185
 186 <!-- ##### FUNCTION gtk_ui_manager_new ##### -->
 187 <para>
 188
 189 </para>
 190
 191 @Returns:
 192
 193
 194 <!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
 195 <para>
 196
 197 </para>
 198
 199 @self:
 200 @add_tearoffs:
 201
 202
 203 <!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
 204 <para>
 205
 206 </para>
 207
 208 @self:
 209 @Returns:
 210
 211
 212 <!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @self:
 218 @action_group:
 219 @pos:
 220
 221
 222 <!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
 223 <para>
 224
 225 </para>
 226
 227 @self:
 228 @action_group:
 229
 230
 231 <!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @self:
 237 @Returns:
 238
 239
 240 <!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
 241 <para>
 242
 243 </para>
 244
 245 @self:
 246 @Returns:
 247
 248
 249 <!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
 250 <para>
 251
 252 </para>
 253
 254 @self:
 255 @path:
 256 @Returns:
 257
 258
 259 <!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
 260 <para>
 261
 262 </para>
 263
 264 @self:
 265 @path:
 266 @Returns:
 267
 268
 269 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
 270 <para>
 271
 272 </para>
 273
 274 @self:
 275 @buffer:
 276 @length:
 277 @error:
 278 @Returns:
 279
 280
 281 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @self:
 287 @filename:
 288 @error:
 289 @Returns:
 290
 291
 292 <!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### -->
 293 <para>
 294
 295 </para>
 296
 297 @self:
 298 @Returns:
 299
 300
 301 <!-- ##### ENUM GtkUIManagerItemType ##### -->
 302 <para>
 303 These enumeration values are used by gtk_ui_manager_add_ui() to determine
 304 what UI element to create.
 305 </para>
 306
 307 @GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context.
 308 @GTK_UI_MANAGER_MENUBAR: Create a menubar.
 309 @GTK_UI_MANAGER_MENU: Create a menu.
 310 @GTK_UI_MANAGER_TOOLBAR: Create a toolbar.
 311 @GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder.
 312 @GTK_UI_MANAGER_POPUP: Create a popup menu.
 313 @GTK_UI_MANAGER_MENUITEM: Create a menuitem.
 314 @GTK_UI_MANAGER_TOOLITEM: Create a toolitem.
 315 @GTK_UI_MANAGER_SEPARATOR: Create a separator.
 316 @GTK_UI_MANAGER_ACCELERATOR: Install an accelerator.
 317
 318 <!-- ##### FUNCTION gtk_ui_manager_add_ui ##### -->
 319 <para>
 320
 321 </para>
 322
 323 @self:
 324 @merge_id:
 325 @path:
 326 @name:
 327 @action:
 328 @type:
 329 @top:
 330
 331
 332 <!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
 333 <para>
 334
 335 </para>
 336
 337 @self:
 338 @merge_id:
 339
 340
 341 <!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
 342 <para>
 343
 344 </para>
 345
 346 @self:
 347 @Returns:
 348
 349
 350 <!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### -->
 351 <para>
 352
 353 </para>
 354
 355 @self:
 356
 357
 358 <!-- ##### SIGNAL GtkUIManager::actions-changed ##### -->
 359 <para>
 360
 361 </para>
 362
 363 @uimanager: the object which received the signal.
 364
 365 <!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
 366 <para>
 367
 368 </para>
 369
 370 @uimanager: the object which received the signal.
 371 @widget:
 372
 373 <!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
 374 <para>
 375
 376 </para>
 377
 378 <!-- ##### ARG GtkUIManager:ui ##### -->
 379 <para>
 380
 381 </para>
 382