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 an XML format which is described
  16 by the following 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 DTD, e.g.
  42 every toolitem must have a toolbar in its anchestry and every menuitem must have
  43 a menubar or popup in its anchestry. If a name is not specified, it defaults to
  44 the action. If an action is not specified either, the element name is used.
  45 </para>
  46 <para>
  47 The constructed widget hierarchy is very similar to the element
  48 tree of the XML, with the exception that placeholders are merged into their
  49 parents. The correspondence of XML elements to widgets should be almost obvious:
  50 <itemizedlist>
  51 <listitem><para>menubar: a #GtkMenuBar</para></listitem>
  52 <listitem><para>toolbar: a #GtkToolBar</para></listitem>
  53 <listitem><para>popup: a toplevel #GtkMenu</para></listitem>
  54 <listitem><para>menu: a #GtkMenu attached to a menuitem</para></listitem>
  55 <listitem><para>menuitem: a #GtkMenuItem subclass, the exact type depends on the action</para></listitem>
  56 <listitem><para>toolitem: a #GtkToolItem subclass, the exact type depends on the action</para></listitem>
  57 <listitem><para>separator: a #GtkSeparatorMenuItem or #GtkSeparatorToolItem</para></listitem>
  58 </itemizedlist>
  59 </para>
  60 <para>
  61 The pos attribute determines where a constructed widget is positioned wrt. to its
  62 siblings in the partially constructed tree. If it is "top", the widget is prepended,
  63 otherwise it is appended.
  64 </para>
  65 </refsect2>
  66
  67 <!-- ##### SECTION See_Also ##### -->
  68 <para>
  69
  70 </para>
  71
  72 <!-- ##### STRUCT GtkUIManager ##### -->
  73 <para>
  74
  75 </para>
  76
  77
  78 <!-- ##### FUNCTION gtk_ui_manager_new ##### -->
  79 <para>
  80
  81 </para>
  82
  83 @Returns:
  84
  85
  86 <!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
  87 <para>
  88
  89 </para>
  90
  91 @self:
  92 @add_tearoffs:
  93
  94
  95 <!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
  96 <para>
  97
  98 </para>
  99
 100 @self:
 101 @Returns:
 102
 103
 104 <!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
 105 <para>
 106
 107 </para>
 108
 109 @self:
 110 @action_group:
 111 @pos:
 112
 113
 114 <!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
 115 <para>
 116
 117 </para>
 118
 119 @self:
 120 @action_group:
 121
 122
 123 <!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
 124 <para>
 125
 126 </para>
 127
 128 @self:
 129 @Returns:
 130
 131
 132 <!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
 133 <para>
 134
 135 </para>
 136
 137 @self:
 138 @Returns:
 139
 140
 141 <!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @self:
 147 @path:
 148 @Returns:
 149
 150
 151 <!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @self:
 157 @path:
 158 @Returns:
 159
 160
 161 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
 162 <para>
 163
 164 </para>
 165
 166 @self:
 167 @buffer:
 168 @length:
 169 @error:
 170 @Returns:
 171
 172
 173 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
 174 <para>
 175
 176 </para>
 177
 178 @self:
 179 @filename:
 180 @error:
 181 @Returns:
 182
 183
 184 <!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
 185 <para>
 186
 187 </para>
 188
 189 @self:
 190 @merge_id:
 191
 192
 193 <!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @self:
 199 @Returns:
 200
 201
 202 <!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
 203 <para>
 204
 205 </para>
 206
 207 @uimanager: the object which received the signal.
 208 @widget:
 209
 210 <!-- ##### SIGNAL GtkUIManager::changed ##### -->
 211 <para>
 212
 213 </para>
 214
 215 @uimanager: the object which received the signal.
 216
 217 <!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
 218 <para>
 219
 220 </para>
 221