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 ore
  11 action groups.
  12 </para>
  13 <refsect2 id="XML-UI"><title>UI Definitions</title>
  14 <para>
  15 The UI definitions are specified in a #GMarkup format which can be
  16 roughly described by the following XML DTD.
  17 <programlisting>
  18 &lt;!ELEMENT ui          (menubar|toolbar|popup)* &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;!ATTLIST menubar      name             &num;IMPLIED &gt;
  28 &lt;!ATTLIST toolbar      name             &num;IMPLIED &gt;
  29 &lt;!ATTLIST popup        name             &num;IMPLIED &gt;
  30 &lt;!ATTLIST placeholder  name             &num;IMPLIED &gt;
  31 &lt;!ATTLIST menu         name             &num;IMPLIED
  32                        action           &num;REQUIRED
  33                        pos    (top|bot) &num;IMPLIED &gt;
  34 &lt;!ATTLIST menuitem     name             &num;IMPLIED
  35                        action           &num;REQUIRED
  36                        pos    (top|bot) &num;IMPLIED &gt;
  37 &lt;!ATTLIST toolitem     name             &num;IMPLIED
  38                        action           &num;REQUIRED
  39                        pos    (top|bot) &num;IMPLIED &gt;
  40 </programlisting>
  41 There are some additional restrictions beyond those specified in the
  42 DTD, e.g. every toolitem must have a toolbar in its anchestry and
  43 every menuitem must have a menubar or popup in its anchestry. If a name
  44 is not specified, it defaults to the action. If an action is not specified
  45 either, the element name is used.
  46 </para>
  47 <example>
  48 <title>A UI definition</title>
  49 <programlisting>
  50 &lt;ui&gt;
  51   &lt;menubar&gt;
  52     &lt;menu name="FileMenu" action="FileMenuAction"&gt;
  53       &lt;menuitem name="New" action="New2Action" /&gt;
  54       &lt;placeholder name="FileMenuAdditions" /&gt;
  55     &lt;/menu&gt;
  56     &lt;menu name="JustifyMenu" action="JustifyMenuAction"&gt;
  57       &lt;menuitem name="Left" action="justify-left"/&gt;
  58       &lt;menuitem name="Centre" action="justify-center"/&gt;
  59       &lt;menuitem name="Right" action="justify-right"/&gt;
  60       &lt;menuitem name="Fill" action="justify-fill"/&gt;
  61     &lt;/menu&gt;
  62   &lt;/menubar&gt;
  63   &lt;toolbar action="toolbar1"&gt;
  64     &lt;placeholder name="JustifyToolItems"&gt;
  65       &lt;separator/&gt;
  66       &lt;toolitem name="Left" action="justify-left"/&gt;
  67       &lt;toolitem name="Centre" action="justify-center"/&gt;
  68       &lt;toolitem name="Right" action="justify-right"/&gt;
  69       &lt;toolitem name="Fill" action="justify-fill"/&gt;
  70       &lt;separator/&gt;
  71     &lt;/placeholder&gt;
  72   &lt;/toolbar&gt;
  73 &lt;/ui&gt;
  74 </programlisting>
  75 </example>
  76 <para>
  77 The constructed widget hierarchy is very similar to the element tree
  78 of the XML, with the exception that placeholders are merged into their
  79 parents. The correspondence of XML elements to widgets should be
  80 almost obvious:
  81 <variablelist>
  82 <varlistentry><term>menubar</term>
  83 <listitem><para>a #GtkMenuBar</para></listitem>
  84 </varlistentry>
  85 <varlistentry><term>toolbar</term>
  86 <listitem><para>a #GtkToolbar</para></listitem>
  87 </varlistentry>
  88 <varlistentry><term>popup</term>
  89 <listitem><para>a toplevel #GtkMenu</para></listitem>
  90 </varlistentry>
  91 <varlistentry><term>menu</term>
  92 <listitem><para>a #GtkMenu attached to a menuitem</para></listitem>
  93 </varlistentry>
  94 <varlistentry><term>menuitem</term>
  95 <listitem><para>a #GtkMenuItem subclass, the exact type depends on the
  96 action</para></listitem>
  97 </varlistentry>
  98 <varlistentry><term>toolitem</term>
  99 <listitem><para>a #GtkToolItem subclass, the exact type depends on the
 100 action</para></listitem>
 101 </varlistentry>
 102 <varlistentry><term>separator</term>
 103 <listitem><para>a #GtkSeparatorMenuItem or
 104 #GtkSeparatorToolItem</para></listitem>
 105 </varlistentry>
 106 </variablelist>
 107 </para>
 108 <para>
 109 The pos attribute determines where a constructed widget is positioned
 110 wrt. to its siblings in the partially constructed tree. If it is
 111 "top", the widget is prepended, otherwise it is appended.
 112 </para>
 113 </refsect2>
 114
 115 <!-- ##### SECTION See_Also ##### -->
 116 <para>
 117
 118 </para>
 119
 120 <!-- ##### STRUCT GtkUIManager ##### -->
 121 <para>
 122
 123 </para>
 124
 125
 126 <!-- ##### FUNCTION gtk_ui_manager_new ##### -->
 127 <para>
 128
 129 </para>
 130
 131 @Returns:
 132
 133
 134 <!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
 135 <para>
 136
 137 </para>
 138
 139 @self:
 140 @add_tearoffs:
 141
 142
 143 <!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
 144 <para>
 145
 146 </para>
 147
 148 @self:
 149 @Returns:
 150
 151
 152 <!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
 153 <para>
 154
 155 </para>
 156
 157 @self:
 158 @action_group:
 159 @pos:
 160
 161
 162 <!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
 163 <para>
 164
 165 </para>
 166
 167 @self:
 168 @action_group:
 169
 170
 171 <!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
 172 <para>
 173
 174 </para>
 175
 176 @self:
 177 @Returns:
 178
 179
 180 <!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
 181 <para>
 182
 183 </para>
 184
 185 @self:
 186 @Returns:
 187
 188
 189 <!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
 190 <para>
 191
 192 </para>
 193
 194 @self:
 195 @path:
 196 @Returns:
 197
 198
 199 <!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
 200 <para>
 201
 202 </para>
 203
 204 @self:
 205 @path:
 206 @Returns:
 207
 208
 209 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @self:
 215 @buffer:
 216 @length:
 217 @error:
 218 @Returns:
 219
 220
 221 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
 222 <para>
 223
 224 </para>
 225
 226 @self:
 227 @filename:
 228 @error:
 229 @Returns:
 230
 231
 232 <!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
 233 <para>
 234
 235 </para>
 236
 237 @self:
 238 @merge_id:
 239
 240
 241 <!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
 242 <para>
 243
 244 </para>
 245
 246 @self:
 247 @Returns:
 248
 249
 250 <!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### -->
 251 <para>
 252
 253 </para>
 254
 255 @self:
 256
 257
 258 <!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @uimanager: the object which received the signal.
 264 @widget:
 265
 266 <!-- ##### SIGNAL GtkUIManager::changed ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @uimanager: the object which received the signal.
 272
 273 <!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
 274 <para>
 275
 276 </para>
 277