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
|
<!-- ##### SECTION Title ##### -->
GtkCombo
<!-- ##### SECTION Short_Description ##### -->
a text entry field with a dropdown list.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkCombo widget consists of a single-line text entry field and a drop-down
list. The drop-down list is displayed when the user clicks on a small arrow
button to the right of the entry field.
</para>
<para>
The drop-down list is a #GtkList widget and can be accessed using the
<structfield>list</structfield> member of the #GtkCombo-struct.
List elements can contain arbitrary widgets, but if an element is not a
plain label, then you must use the gtk_list_set_item_string() function.
This sets the string which will be placed in the text entry field when the
item is selected.
</para>
<para>
By default, the user can step through the items in the list using the
arrow (cursor) keys, though this behaviour can be turned off with
gtk_combo_set_use_arrows().
</para>
<para>
Normally the arrow keys are only active when the contents of the text entry
field matches one of the items in the list. If the contents of the entry field
do not match any of the list items, then pressing the arrow keys does nothing.
However, by calling gtk_combo_set_use_arrows_always() you can specify that the
arrow keys are always active. If the contents of the entry field does not match
any of the items in the list, then pressing the up or down arrow key will set
the entry field to the last or first item in the list, respectively.
</para>
<example id="gtkcombo-simple-example">
<title>Creating a <structname>GtkCombo</structname> widget with simple text
items.</title>
<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");
items = g_list_append (items, "Fourth Item");
items = g_list_append (items, "Fifth Item");
combo = gtk_combo_new (<!-- -->);
gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
</programlisting>
</example>
<example>
<title>Creating a <structname>GtkCombo</structname> widget with a complex item.</title>
<programlisting>
GtkWidget *combo, *item, *hbox, *arrow, *label;
combo = gtk_combo_new (<!-- -->);
item = gtk_list_item_new (<!-- -->);
gtk_widget_show (item);
/* You can put almost anything into the GtkListItem widget. Here we will use
a horizontal box with an arrow and a label in it. */
hbox = gtk_hbox_new (FALSE, 3);
gtk_container_add (GTK_CONTAINER (item), hbox);
gtk_widget_show (hbox);
arrow = gtk_arrow_new (GTK_ARROW_RIGHT, GTK_SHADOW_OUT);
gtk_widget_show (arrow);
gtk_box_pack_start (GTK_BOX (hbox), pixmap, FALSE, FALSE, 0);
label = gtk_label_new ("First Item");
gtk_widget_show (label);
gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);
/* You must set the string to display in the entry field when the item is
selected. */
gtk_combo_set_item_string (GTK_COMBO (combo), GTK_ITEM (item), "1st Item");
/* Now we simply add the item to the combo's list. */
gtk_container_add (GTK_CONTAINER (GTK_COMBO (combo)->list), item);
</programlisting>
</example>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### STRUCT GtkCombo ##### -->
<para>
The #GtkFixedChild-struct struct contains the following fields.
(These fields should be considered read-only. They should never be set by
an application.)
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>#GtkWidget *entry;</entry>
<entry>the text entry field.</entry>
</row>
<row>
<entry>#GtkWidget *list;</entry>
<entry>the list shown in the drop-down window.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
<!-- ##### FUNCTION gtk_combo_new ##### -->
<para>
Creates a new #GtkCombo.
</para>
@Returns: a new #GtkCombo.
<!-- ##### FUNCTION gtk_combo_set_popdown_strings ##### -->
<para>
Convenience function to set all of the items in the popup list.
(See the <link linkend="gtkcombo-simple-example">example</link> above.)
</para>
@combo: a #GtkCombo.
@strings: a list of strings.
<!-- ##### FUNCTION gtk_combo_set_value_in_list ##### -->
<para>
Specifies whether the value entered in the text entry field must match one of
the values in the list. If this is set then the user will not be able to
perform any other action until a valid value has been entered.
</para>
<para>
If an empty field is acceptable, the @ok_if_empty parameter should be %TRUE.
</para>
@combo: a #GtkCombo.
@val: %TRUE if the value entered must match one of the values in the list.
@ok_if_empty: %TRUE if an empty value is considered valid.
<!-- ##### FUNCTION gtk_combo_set_use_arrows ##### -->
<para>
Specifies if the arrow (cursor) keys can be used to step through the items in
the list. This is on by default.
</para>
@combo: a #GtkCombo.
@val: %TRUE if the arrow keys can be used to step through the items in the list.
<!-- ##### FUNCTION gtk_combo_set_use_arrows_always ##### -->
<para>
Specifies if the arrow keys will still work even if the current contents of the
#GtkEntry field do not match any of the list items.
</para>
@combo: a #GtkCombo.
@val: %TRUE if the arrow keys will still work even if the current contents of
the #GtkEntry field do not match any of the list items.
<!-- ##### FUNCTION gtk_combo_set_case_sensitive ##### -->
<para>
Specifies whether the text entered into the #GtkEntry field and the text in
the list items is case sensitive.
</para>
<para>
This may be useful, for example, when you have called
gtk_combo_set_value_in_list() to limit the values entered, but you are not
worried about differences in case.
</para>
@combo: a #GtkCombo.
@val: %TRUE if the text in the list items is case sensitive.
<!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
<para>
Sets the string to place in the #GtkEntry field when a particular list item is
selected. This is needed if the list item is not a simple label.
</para>
@combo: a #GtkCombo.
@item: a #GtkItem.
@item_value: the string to place in the #GtkEntry when @item is selected.
<!-- ##### FUNCTION gtk_combo_disable_activate ##### -->
<para>
Stops the #GtkCombo widget from showing the popup list when the #GtkEntry
emits the "activate" signal, i.e. when the Return key is pressed.
This may be useful if, for example, you want the Return key to close a dialog
instead.
</para>
@combo: a #GtkCombo.
<!-- ##### ARG GtkCombo:enable-arrow-keys ##### -->
<para>
</para>
<!-- ##### ARG GtkCombo:enable-arrows-always ##### -->
<para>
</para>
<!-- ##### ARG GtkCombo:case-sensitive ##### -->
<para>
</para>
<!-- ##### ARG GtkCombo:allow-empty ##### -->
<para>
</para>
<!-- ##### ARG GtkCombo:value-in-list ##### -->
<para>
</para>
|
