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
|
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="gtk-migrating-GtkComboBox">
<title>Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and
GtkComboBoxEntry</title>
<para>
Prior to 2.4, GTK+ offered two widgets for the task of selecting one
item from a list of options. #GtkOptionMenu presents the list of
options as a menu while #GtkCombo presents them in a Windows-style list
popup. The only difference between the two is that a #GtkCombo allows to
manually edit the selected value, while the #GtkOptionMenu does not.
</para>
<para>
In GTK+ 2.4, a unified API for list selection was introduced, with
#GtkComboBox for the non-editable case and #GtkComboBoxEntry for the
editable case.
The selection of the display style — menu or list —
is no longer done at the API level, but has been made themeable via
the style property #GtkComboBox:appearance.
</para>
<section id="migrating-GtkOptionMenu">
<title>Migrating from GtkOptionMenu to GtkComboBox</title>
<para>
Here is an example of a simple, but typical use of
#GtkOptionMenu:
<informalexample><programlisting>
GtkWidget *option_menu, *menu, *menu_item;
option_menu = gtk_option_menu_new (<!-- -->);
menu = gtk_menu_new (<!-- -->);
menu_item = gtk_menu_item_new_with_label ("First Item");
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
gtk_widget_show (menu_item);
menu_item = gtk_menu_item_new_with_label ("Second Item");
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
gtk_widget_show (menu_item);
menu_item = gtk_menu_item_new_with_label ("Third Item");
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
gtk_widget_show (menu_item);
gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
</programlisting></informalexample>
In order to react to the user's selection, connect to the "changed"
signal on the option menu and use gtk_option_menu_get_history()
to retrieve the index of the selected item.
</para>
<para>
And here is how it would be done with a #GtkComboBox:
<informalexample><programlisting>
GtkWidget *combo_box;
combo_box = gtk_combo_box_new_text (<!-- -->);
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
</programlisting></informalexample>
In order to react to the user's selection, connect to the
#GtkComboBox::changed signal and use gtk_combo_box_get_active()
to retrieve the index of the selected item.
</para>
<para>
A slightly more complex example involving images:
<informalexample><programlisting>
GtkWidget *option_menu, *menu, *menu_item;
option_menu = gtk_option_menu_new (<!-- -->);
menu = gtk_menu_new (<!-- -->);
menu_item = gtk_image_menu_item_new_with_label ("First Item");
gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf1));
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
gtk_widget_show (menu_item);
menu_item = gtk_image_menu_item_new_with_label ("Second Item");
gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf2));
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
gtk_widget_show (menu_item);
menu_item = gtk_image_menu_item_new_with_label ("Third Item");
gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf3));
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
gtk_widget_show (menu_item);
gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
</programlisting></informalexample>
</para>
<para>
can be done using a #GtkComboBox as follows:
<informalexample><programlisting>
GtkListStore *store;
GtkTreeIter iter;
GtkCellRenderer *renderer;
GtkWidget *combo_box;
store = gtk_list_store_new (2, GDK_TYPE_PIXBUF, G_TYPE_STRING);
gtk_list_store_append (store, &iter);
gtk_list_store_set (store, &iter, 0, pixbuf1, 1, "First Item", -1);
gtk_list_store_append (store, &iter);
gtk_list_store_set (store, &iter, 0, pixbuf2, 1, "Second Item", -1);
gtk_list_store_append (store, &iter);
gtk_list_store_set (store, &iter, 0, pixbuf3, 1, "Third Item", -1);
combo_box = gtk_combo_box_new_with_model (GTK_TREE_MODEL (store));
renderer = gtk_cell_renderer_pixbuf_new (<!-- -->);
gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, FALSE);
gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer,
"pixbuf", 0,
NULL);
renderer = gtk_cell_renderer_text_new (<!-- -->);
gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, TRUE);
gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer,
"text", 1,
NULL);
</programlisting></informalexample>
</para>
</section>
<section id="migrating-GtkCombo">
<title>Migrating from GtkCombo to GtkComboBoxEntry</title>
<para>
Here is an example of a simple, but typical use of a #GtkCombo:
<informalexample><programlisting>
GtkWidget *combo;
GList *items = NULL;
items = g_list_append (items, "First Item");
items = g_list_append (items, "Second Item");
items = g_list_append (items, "Third Item");
combo = gtk_combo_new (<!-- -->);
gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
</programlisting></informalexample>
In order to react to the user's selection, connect to the "changed"
signal on the combo and use
<literal>gtk_entry_get_text (GTK_ENTRY (combo->entry))</literal>
to retrieve the selected text.
</para>
<para>
And here is how it would be done using #GtkComboBoxEntry:
<informalexample><programlisting>
combo_box = gtk_combo_box_entry_new_text (<!-- -->);
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
</programlisting></informalexample>
In order to react to the user's selection, connect to the "changed"
signal on the combo and use
<literal>gtk_entry_get_text (GTK_ENTRY (GTK_BIN (combo_box)->child))</literal>
to retrieve the selected text.
</para>
</section>
<section id="new-features-GtkComboBox">
<title>New features</title>
<para>
The new widgets have more to offer than a mere combination of the
features of #GtkOptionMenu and #GtkCombo. Notable new features
include:
<variablelist>
<varlistentry>
<term>Grid mode</term>
<listitem><para>Sometimes it is preferable to display the available
options not in a linear list, but in a grid. A typical example
would be a "color combo" where the individual items are small
square color swatches. The new widgets support gridded display
with the functions
gtk_combo_box_set_wrap_width(),
gtk_combo_box_set_row_span_column() and
gtk_combo_box_set_column_span_column().
</para></listitem>
</varlistentry>
<varlistentry>
<term>Display of icons</term>
<listitem><para>An often-heard complaint about #GtkOptionMenu is that
the icons which appear in the image menu items in its menu are not
displayed in the button showing the selected item. This limitation
has been removed in #GtkComboBox; the selected item appears in the
same way as the options in the popup.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Full tree model power</term>
<listitem><para>
Since the new widgets are built around the same models that are
used for #GtkTreeView, all of the powerful machinery of tree models
and cell renderers can be used.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</section>
</chapter>
<!--
Local variables:
mode: sgml
sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
End:
-->
|
