← Back to branch summary

~ubuntu-branches/ubuntu/raring/gtk+2.0/raring-proposed

« back to all changes in this revision

Viewing changes to docs/reference/gtk/tmpl/gtkuimanager.sgml

  • Committer: Package Import Robot
  • Author(s): Sebastien Bacher
  • Date: 2012-02-06 22:03:26 UTC
  • mfrom: (1.14.12)
  • Revision ID: package-import@ubuntu.com-20120206220326-10d7cnkpdpbi9iox
Tags: 2.24.10-0ubuntu1
https://launchpad.net/bugs/920961
* New upstream version, dropped patches included in the new version
* debian/patches/090_logging_file_saves.patch:
  - improve the logging of saved filed, thanks Siegfried Gevatter 
    (lp: #920961)

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
<!-- ##### SECTION Image ##### -->
 
257
 
 
258
 
 
259
<!-- ##### STRUCT GtkUIManager ##### -->
 
260
<para>
 
261
The <structname>GtkUIManager</structname> struct contains only private
 
262
members and should not be accessed directly.
 
263
</para>
 
264
 
 
265
 
 
266
<!-- ##### SIGNAL GtkUIManager::actions-changed ##### -->
 
267
<para>
 
268
 
 
269
</para>
 
270
 
 
271
@uimanager: the object which received the signal.
 
272
 
 
273
<!-- ##### SIGNAL GtkUIManager::add-widget ##### -->
 
274
<para>
 
275
 
 
276
</para>
 
277
 
 
278
@uimanager: the object which received the signal.
 
279
@widget: 
 
280
 
 
281
<!-- ##### SIGNAL GtkUIManager::connect-proxy ##### -->
 
282
<para>
 
283
 
 
284
</para>
 
285
 
 
286
@uimanager: the object which received the signal.
 
287
@arg1: 
 
288
@widget: 
 
289
 
 
290
<!-- ##### SIGNAL GtkUIManager::disconnect-proxy ##### -->
 
291
<para>
 
292
 
 
293
</para>
 
294
 
 
295
@uimanager: the object which received the signal.
 
296
@arg1: 
 
297
@widget: 
 
298
 
 
299
<!-- ##### SIGNAL GtkUIManager::post-activate ##### -->
 
300
<para>
 
301
 
 
302
</para>
 
303
 
 
304
@uimanager: the object which received the signal.
 
305
@arg1: 
 
306
 
 
307
<!-- ##### SIGNAL GtkUIManager::pre-activate ##### -->
 
308
<para>
 
309
 
 
310
</para>
 
311
 
 
312
@uimanager: the object which received the signal.
 
313
@arg1: 
 
314
 
 
315
<!-- ##### ARG GtkUIManager:add-tearoffs ##### -->
 
316
<para>
 
317
 
 
318
</para>
 
319
 
 
320
<!-- ##### ARG GtkUIManager:ui ##### -->
 
321
<para>
 
322
 
 
323
</para>
 
324
 
 
325
<!-- ##### FUNCTION gtk_ui_manager_new ##### -->
 
326
<para>
 
327
 
 
328
</para>
 
329
 
 
330
@void: 
 
331
@Returns: 
 
332
 
 
333
 
 
334
<!-- ##### FUNCTION gtk_ui_manager_set_add_tearoffs ##### -->
 
335
<para>
 
336
 
 
337
</para>
 
338
 
 
339
@self: 
 
340
@add_tearoffs: 
 
341
 
 
342
 
 
343
<!-- ##### FUNCTION gtk_ui_manager_get_add_tearoffs ##### -->
 
344
<para>
 
345
 
 
346
</para>
 
347
 
 
348
@self: 
 
349
@Returns: 
 
350
 
 
351
 
 
352
<!-- ##### FUNCTION gtk_ui_manager_insert_action_group ##### -->
 
353
<para>
 
354
 
 
355
</para>
 
356
 
 
357
@self: 
 
358
@action_group: 
 
359
@pos: 
 
360
 
 
361
 
 
362
<!-- ##### FUNCTION gtk_ui_manager_remove_action_group ##### -->
 
363
<para>
 
364
 
 
365
</para>
 
366
 
 
367
@self: 
 
368
@action_group: 
 
369
 
 
370
 
 
371
<!-- ##### FUNCTION gtk_ui_manager_get_action_groups ##### -->
 
372
<para>
 
373
 
 
374
</para>
 
375
 
 
376
@self: 
 
377
@Returns: 
 
378
 
 
379
 
 
380
<!-- ##### FUNCTION gtk_ui_manager_get_accel_group ##### -->
 
381
<para>
 
382
 
 
383
</para>
 
384
 
 
385
@self: 
 
386
@Returns: 
 
387
 
 
388
 
 
389
<!-- ##### FUNCTION gtk_ui_manager_get_widget ##### -->
 
390
<para>
 
391
 
 
392
</para>
 
393
 
 
394
@self: 
 
395
@path: 
 
396
@Returns: 
 
397
 
 
398
 
 
399
<!-- ##### FUNCTION gtk_ui_manager_get_toplevels ##### -->
 
400
<para>
 
401
 
 
402
</para>
 
403
 
 
404
@self: 
 
405
@types: 
 
406
@Returns: 
 
407
 
 
408
 
 
409
<!-- ##### FUNCTION gtk_ui_manager_get_action ##### -->
 
410
<para>
 
411
 
 
412
</para>
 
413
 
 
414
@self: 
 
415
@path: 
 
416
@Returns: 
 
417
 
 
418
 
 
419
<!-- ##### FUNCTION gtk_ui_manager_add_ui_from_string ##### -->
 
420
<para>
 
421
 
 
422
</para>
 
423
 
 
424
@self: 
 
425
@buffer: 
 
426
@length: 
 
427
@error: 
 
428
@Returns: 
 
429
 
 
430
 
 
431
<!-- ##### MACRO gtk_ui_manager_add_ui_from_file ##### -->
 
432
<para>
 
433
 
 
434
</para>
 
435
 
 
436
@Returns: 
 
437
 
 
438
 
 
439
<!-- ##### FUNCTION gtk_ui_manager_new_merge_id ##### -->
 
440
<para>
 
441
 
 
442
</para>
 
443
 
 
444
@self: 
 
445
@Returns: 
 
446
 
 
447
 
 
448
<!-- ##### ENUM GtkUIManagerItemType ##### -->
 
449
<para>
 
450
These enumeration values are used by gtk_ui_manager_add_ui() to determine
 
451
what UI element to create.
 
452
</para>
 
453
 
 
454
@GTK_UI_MANAGER_AUTO: Pick the type of the UI element according to context.
 
455
@GTK_UI_MANAGER_MENUBAR: Create a menubar.
 
456
@GTK_UI_MANAGER_MENU: Create a menu.
 
457
@GTK_UI_MANAGER_TOOLBAR: Create a toolbar.
 
458
@GTK_UI_MANAGER_PLACEHOLDER: Insert a placeholder.
 
459
@GTK_UI_MANAGER_POPUP: Create a popup menu.
 
460
@GTK_UI_MANAGER_MENUITEM: Create a menuitem.
 
461
@GTK_UI_MANAGER_TOOLITEM: Create a toolitem.
 
462
@GTK_UI_MANAGER_SEPARATOR: Create a separator.
 
463
@GTK_UI_MANAGER_ACCELERATOR: Install an accelerator.
 
464
@GTK_UI_MANAGER_POPUP_WITH_ACCELS: Same as %GTK_UI_MANAGER_POPUP, but the actions' accelerators are shown.
 
465
 
 
466
<!-- ##### FUNCTION gtk_ui_manager_add_ui ##### -->
 
467
<para>
 
468
 
 
469
</para>
 
470
 
 
471
@self: 
 
472
@merge_id: 
 
473
@path: 
 
474
@name: 
 
475
@action: 
 
476
@type: 
 
477
@top: 
 
478
 
 
479
 
 
480
<!-- ##### FUNCTION gtk_ui_manager_remove_ui ##### -->
 
481
<para>
 
482
 
 
483
</para>
 
484
 
 
485
@self: 
 
486
@merge_id: 
 
487
 
 
488
 
 
489
<!-- ##### FUNCTION gtk_ui_manager_get_ui ##### -->
 
490
<para>
 
491
 
 
492
</para>
 
493
 
 
494
@self: 
 
495
@Returns: 
 
496
 
 
497
 
 
498
<!-- ##### FUNCTION gtk_ui_manager_ensure_update ##### -->
 
499
<para>
 
500
 
 
501
</para>
 
502
 
 
503
@self: 
 
504
 
 
505