1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Migrating from GnomeUIInfo: GTK+ 2 Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="GTK+ 2 Reference Manual">
<link rel="up" href="gtk-migrating-GtkAction.html" title="Migrating from old menu and toolbar systems to GtkAction">
<link rel="prev" href="ui-manager.html" title="User Interface Manager Object">
<link rel="next" href="gtk-migrating-GtkComboBox.html" title="Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and GtkComboBoxEntry">
<meta name="generator" content="GTK-Doc V1.33.0 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="gtk-migrating-GtkAction.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="ui-manager.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="gtk-migrating-GtkComboBox.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="migrating-gnomeuiinfo"></a>Migrating from GnomeUIInfo</h2></div></div></div>
<p>
Prior to GTK+ 2.4, some applications used the GnomeUIInfo
mechanism from
<code class="filename"><libgnomeui/gnome-app-helper.h></code> to
define their menus and toolbars. With it, a program decleres an
array of <span class="structname">GnomeUIInfo</span> structures, which
contain information for menu or toolbar items such as their
label, icon, and accelerator key. Then, one calls
<code class="function">gnome_app_fill_menu()</code> or <code class="function">gnome_app_fill_toolbar()</code>, or one of the
related functions, to create the appropriate widgets based on
these structures.
</p>
<p>
A downside of this API is that the same structures are used to
pass back pointers to the widgets that got created. This means
that the structures cannot simply be kept around if the program
requires multiple instances of the user interface (e.g. several
windows); each new invocation of <code class="function">gnome_app_fill_menu()</code> would
overwrite the widget fields of the structures.
</p>
<p>
Another disadvantage is that there is no automatic way to
synchronize the state of related controls. If there are toolbar
toogle buttons for "Bold", "Italic", "Underline", and also
corresponding menu items under "Format/Bold", etc., one has to
synchronize their toggled states by hand whenever the user
selects any one of them.
</p>
<p>
Finally, there is no way to do menu and toolbar merging for
applications that require embedded components.
</p>
<p>
To convert an application that uses GnomeUIInfo into the new
GtkAction mechanism, you need to do several things:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem"><p>
Separate your existing GnomeUIInfo entries into normal
actions, toggle actions, and radio actions, and then create
a separate array of <a class="link" href="GtkActionGroup.html#GtkActionEntry" title="struct GtkActionEntry"><span class="type">GtkActionEntry</span></a> structures
for each group. This will allow you to create the necessary
<a class="link" href="GtkActionGroup.html" title="GtkActionGroup"><span class="type">GtkActionGroup</span></a> objects. Note that this does not describe
the actual "shape" that your menus and toolbars will have;
it simply defines the set of commands that will appear in them.
</p></li>
<li class="listitem"><p>
Create an XML description of your menus and toolbars for use
with <a class="link" href="GtkUIManager.html" title="GtkUIManager"><span class="type">GtkUIManager</span></a>. This defines the actual shape of the menus
and toolbars.
</p></li>
<li class="listitem"><p>
Port the code that uses gnome-app and gnome-app-helper to
<a class="link" href="GtkAction.html" title="GtkAction"><span class="type">GtkAction</span></a> and <a class="link" href="GtkUIManager.html" title="GtkUIManager"><span class="type">GtkUIManager</span></a>.
</p></li>
<li class="listitem"><p>
If your GnomeUIInfo entries use GNOME_APP_PIXMAP_DATA or
GNOME_APP_PIXMAP_FILENAME for pixmaps, you have to create a
<a class="link" href="gtk2-Themeable-Stock-Images.html#GtkIconFactory"><span class="type">GtkIconFactory</span></a>, add it to the list of default factories, then
create a <a class="link" href="gtk2-Themeable-Stock-Images.html#GtkIconSet"><span class="type">GtkIconSet</span></a> for each of your own icons. Add the sets to
the factory, and use the id in the <a class="link" href="GtkActionGroup.html#GtkActionEntry" title="struct GtkActionEntry"><span class="type">GtkActionEntry</span></a> like a regular
GTK+ stock id.
</p></li>
</ol></div>
<div class="example">
<a name="gnomeuiinfo-example"></a><p class="title"><b>Example 17. GnomeUIInfo Example</b></p>
<div class="example-contents">
<p>
The following code shows a declaration of a simple menu bar to
be used with <code class="function">gnome_app_fill_menu()</code> or similar. The menu hierarchy i
looks like this:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="guimenu">File</span></p>
<table border="0" summary="Simple list" class="simplelist">
<tr><td><span class="guimenuitem">Open</span></td></tr>
<tr><td><span class="guimenuitem">—</span></td></tr>
<tr><td><span class="guimenuitem">Exit</span></td></tr>
</table>
</li>
<li class="listitem">
<p><span class="guimenu">View</span></p>
<table border="0" summary="Simple list" class="simplelist">
<tr><td><span class="guimenuitem">Zoom In</span></td></tr>
<tr><td><span class="guimenuitem">Zoom Out</span></td></tr>
<tr><td><span class="guimenuitem">—</span></td></tr>
<tr><td><span class="guimenuitem">[ ] Full Screen</span></td></tr>
<tr><td><span class="guimenuitem">—</span></td></tr>
<tr><td><span class="guimenuitem">( ) High Quality</span></td></tr>
<tr><td><span class="guimenuitem">( ) Normal Quality</span></td></tr>
<tr><td><span class="guimenuitem">( ) Low Quality</span></td></tr>
</table>
</li>
</ul></div>
<pre class="programlisting">
static GnomeUIInfo file_menu_items[] = {
{ GNOME_APP_UI_ITEM, "_Open", "Open a file",
open_callback, NULL, NULL, GNOME_APP_PIXMAP_STOCK, GTK_STOCK_OPEN,
'o', GDK_CONTROL_MASK, NULL },
{ GNOME_APP_UI_SEPARATOR },
{ GNOME_APP_UI_ITEM, "E_xit", "Exit the program",
exit_callback, NULL, NULL, GNOME_APP_PIXMAP_STOCK, GTK_STOCK_QUIT,
'q', GDK_CONTROL_MASK, NULL},
{ GNOME_APP_UI_ENDOFINFO }
};
static GnomeUIInfo view_radio_items[] = {
{ GNOME_APP_UI_ITEM, "_High Quality", "Display images in high quality, slow mode",
high_quality_callback, NULL, NULL, GNOME_APP_PIXMAP_FILENAME, "high-quality.png",
0, 0, NULL },
{ GNOME_APP_UI_ITEM, "_Normal Quality", "Display images in normal quality",
normal_quality_callback, NULL, NULL, GNOME_APP_PIXMAP_FILENAME, "normal-quality.png",
0, 0, NULL },
{ GNOME_APP_UI_ITEM, "_Low Quality", "Display images in low quality, fast mode",
low_quality_callback, NULL, NULL, GNOME_APP_PIXMAP_FILENAME, "low-quality.png",
0, 0, NULL },
{ GNOME_APP_UI_ENDOFINFO }
};
static GnomeUIInfo view_menu_items[] = {
{ GNOME_APP_UI_ITEM, "Zoom _In", "Zoom into the image",
zoom_in_callback, NULL, NULL, GNOME_APP_PIXMAP_STOCK, GTK_STOCK_ZOOM_IN,
GDK_PLUS, 0, NULL },
{ GNOME_APP_UI_ITEM, "Zoom _Out", "Zoom away from the image",
zoom_out_callback, NULL, NULL, GNOME_APP_PIXMAP_STOCK, GTK_STOCK_ZOOM_OUT,
GDK_MINUS, 0, NULL },
{ GNOME_APP_UI_SEPARATOR },
{ GNOME_APP_UI_TOGGLEITEM, "_Full Screen", "Switch between full screen and windowed mode",
full_screen_callback, NULL, NULL, GNOME_APP_PIXMAP_NONE, NULL,
GDK_F11, 0, NULL },
{ GNOME_APP_UI_SEPARATOR },
{ GNOME_APP_UI_RADIOITEMS, NULL, NULL, view_radio_items },
{ GNOME_APP_UI_ENDOFINFO }
};
static GnomeUIInfo menubar[] = {
{ GNOME_APP_UI_SUBTREE, "_File", NULL, file_menu_items },
{ GNOME_APP_UI_SUBTREE, "_View", NULL, view_menu_items },
{ GNOME_APP_UI_ENDOFINFO }
}
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="gnomeuiinfo-action-entries"></a><p class="title"><b>Example 18. <span class="structname">GtkActionEntry</span> Structures</b></p>
<div class="example-contents">
<p>
The following code is the set of actions that are present in
the <a class="link" href="migrating-gnomeuiinfo.html#gnomeuiinfo-example" title="Example 17. GnomeUIInfo Example">previous
example</a>. Note that the toggle and radio entries are
separate from normal actions. Also, note that <a class="link" href="GtkActionGroup.html#GtkActionEntry" title="struct GtkActionEntry"><span class="type">GtkActionEntry</span></a>
structures take key names in the format of <a class="link" href="gtk2-Keyboard-Accelerators.html#gtk-accelerator-parse" title="gtk_accelerator_parse ()"><code class="function">gtk_accelerator_parse()</code></a>
rather than key values plus modifiers; you will have to convert these
values by hand. For example, <code class="literal">GDK_F11</code> with no modifiers is equivalent
to a key name of <code class="literal">"F11"</code>. Likewise, <code class="literal">"o"</code>
with <a href="../html/gdk2-Windows.html#GDK-CONTROL-MASK:CAPS"><code class="literal">GDK_CONTROL_MASK</code></a> is equivalent to <code class="literal">"<ontrol>O"</code>.
</p>
<pre class="programlisting">
/* Normal items */
static const GtkActionEntry entries[] = {
{ "FileMenu", NULL, "_File" },
{ "ViewMenu", NULL, "_View" },
{ "Open", GTK_STOCK_OPEN, "_Open", "<control>O", "Open a file", open_action_callback },
{ "Exit", GTK_STOCK_QUIT, "E_xit", "<control>Q", "Exit the program", exit_action_callback },
{ "ZoomIn", GTK_STOCK_ZOOM_IN, "Zoom _In", "plus", "Zoom into the image", zoom_in_action_callback },
{ "ZoomOut", GTK_STOCK_ZOOM_OUT, "Zoom _Out", "minus", "Zoom away from the image", zoom_out_action_callback },
};
/* Toggle items */
static const GtkToggleActionEntry toggle_entries[] = {
{ "FullScreen", NULL, "_Full Screen", "F11", "Switch between full screen and windowed mode", full_screen_action_callback, FALSE }
};
/* Radio items */
static const GtkRadioActionEntry radio_entries[] = {
{ "HighQuality", "my-stock-high-quality", "_High Quality", NULL, "Display images in high quality, slow mode", 0 },
{ "NormalQuality", "my-stock-normal-quality", "_Normal Quality", NULL, "Display images in normal quality", 1 },
{ "LowQuality", "my-stock-low-quality", "_Low Quality", NULL, "Display images in low quality, fast mode", 2 }
};
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="gnomeuiinfo-xml"></a><p class="title"><b>Example 19. XML Description</b></p>
<div class="example-contents">
<p>
After extracting the actions, you will need to create an XML
description of the actual layout of your menus and toolbars
for use with <a class="link" href="GtkUIManager.html" title="GtkUIManager"><span class="type">GtkUIManager</span></a>. The following code shows a simple
menu bar that corresponds to the <a class="link" href="migrating-gnomeuiinfo.html#gnomeuiinfo-example" title="Example 17. GnomeUIInfo Example">previous
example</a>. Note that the <span class="guimenu">File</span> and
<span class="guimenu">View</span> menus have their names specified in
the <a class="link" href="migrating-gnomeuiinfo.html#gnomeuiinfo-action-entries" title="Example 18. GtkActionEntry Structures">action
entries</a>, not in the XML itself. This is because the
XML description only contains <span class="emphasis"><em>identifiers</em></span>
for the items in the GUI, rather than human-readable names.
</p>
<pre class="programlisting">
static const char *ui_description =
"<ui>"
" <menubar name='MainMenu'>"
" <menu action='FileMenu'>"
" <menuitem action='Open'/>"
" <menuitem action='Exit'/>"
" </menu>"
" <menu action='ViewMenu'>"
" <menuitem action='ZoomIn'/>"
" <menuitem action='ZoomOut'/>"
" <separator/>"
" <menuitem action='FullScreen'/>"
" <separator/>"
" <menuitem action='HighQuality'/>"
" <menuitem action='NormalQuality'/>"
" <menuitem action='LowQuality'/>"
" </menu>"
" </menubar>"
"</ui>";
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="gnomeuiinfo-code"></a><p class="title"><b>Example 20. Creating the Menu Bar</b></p>
<div class="example-contents">
<p>
In this last example, we will create a <a class="link" href="GtkActionGroup.html" title="GtkActionGroup"><span class="type">GtkActionGroup</span></a> based on the
<a class="link" href="migrating-gnomeuiinfo.html#gnomeuiinfo-action-entries" title="Example 18. GtkActionEntry Structures">action entries</a>
we created above. We will then create a <a class="link" href="GtkUIManager.html" title="GtkUIManager"><span class="type">GtkUIManager</span></a> with the <a class="link" href="migrating-gnomeuiinfo.html#gnomeuiinfo-xml" title="Example 19. XML Description">XML description</a> of the menu
layout. We will also extract the accelerator group and the
widgets from the <a class="link" href="GtkUIManager.html" title="GtkUIManager"><span class="type">GtkUIManager</span></a> put them into a window.
</p>
<pre class="programlisting">
GtkWidget *window;
GtkWidget *vbox;
GtkWidget *menubar;
GtkActionGroup *action_group;
GtkUIManager *ui_manager;
GtkAccelGroup *accel_group;
GError *error;
register_my_stock_icons ();
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
vbox = gtk_vbox_new (FALSE, 0);
gtk_container_add (GTK_CONTAINER (window), vbox);
action_group = gtk_action_group_new ("MenuActions");
gtk_action_group_add_actions (action_group, entries, G_N_ELEMENTS (entries), window);
gtk_action_group_add_toggle_actions (action_group, toggle_entries, G_N_ELEMENTS (toggle_entries), window);
gtk_action_group_add_radio_actions (action_group, radio_entries, G_N_ELEMENTS (radio_entries), 0, radio_action_callback, window);
ui_manager = gtk_ui_manager_new ();
gtk_ui_manager_insert_action_group (ui_manager, action_group, 0);
accel_group = gtk_ui_manager_get_accel_group (ui_manager);
gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
error = NULL;
if (!gtk_ui_manager_add_ui_from_string (ui_manager, ui_description, -1, &error))
{
g_message ("building menus failed: %s", error->message);
g_error_free (error);
exit (EXIT_FAILURE);
}
menubar = gtk_ui_manager_get_widget (ui_manager, "/MainMenu");
gtk_box_pack_start (GTK_BOX (vbox), menubar, FALSE, FALSE, 0);
gtk_widget_show_all (window);
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="gnomeuiinfo-icons"></a><p class="title"><b>Example 21. Registering the icons</b></p>
<div class="example-contents">
<p>
Here we show how the <code class="function">register_my_stock_icons()</code> function
used in the previous example could look like.
</p>
<pre class="programlisting">
static struct {
gchar *filename;
gchar *stock_id;
} stock_icons[] = {
{ "high-quality.png", "my-stock-high-quality" },
{ "normal-quality.png", "my-stock-normal-quality" },
{ "low-quality.png", "my-stock-low-quality" },
};
static gint n_stock_icons = G_N_ELEMENTS (stock_icons);
static void
register_my_stock_icons (void)
{
GtkIconFactory *icon_factory;
GtkIconSet *icon_set;
GtkIconSource *icon_source;
gint i;
icon_factory = gtk_icon_factory_new ();
for (i = 0; i < n_stock_icons; i++)
{
icon_set = gtk_icon_set_new ();
icon_source = gtk_icon_source_new ();
gtk_icon_source_set_filename (icon_source, stock_icons[i].filename);
gtk_icon_set_add_source (icon_set, icon_source);
gtk_icon_source_free (icon_source);
gtk_icon_factory_add (icon_factory, stock_icons[i].stock_id, icon_set);
gtk_icon_set_unref (icon_set);
}
gtk_icon_factory_add_default (icon_factory);
g_object_unref (icon_factory);
}
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.0</div>
</body>
</html>
|
