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_add_ui_from_string ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @self:
 157 @buffer:
 158 @length:
 159 @error:
 160 @Returns:
 161
 162
 163 <!-- ##### FUNCTION gtk_ui_manager_add_ui_from_file ##### -->
 164 <para>
 165
 166 </para>
 167
 168 @self:
 169 @filename:
 170 @error:
 171 @Returns:
 172
 173
 174 <!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @self:
 180 @merge_id:
 181
 182
 183 <!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
 184 <para>
 185
 186 </para>
 187
 188 @self:
 189 @Returns:
 190
 191
 192 <!-- ##### FUNCTION gtk_ui_manager_activate ##### -->
 193 <para>
 194
 195 </para>
 196
 197 @self:
 198 @path:
 199
 200
 201 <!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
 202 <para>
 203
 204 </para>
 205
 206 @uimanager: the object which received the signal.
 207 @widget:
 208
 209 <!-- ##### SIGNAL GtkUIManager::changed ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @uimanager: the object which received the signal.
 215
 216 <!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
 217 <para>
 218
 219 </para>
 220