gtkcombobox.sgml 6.54 KB
Newer Older
1 2 3 4
<!-- ##### SECTION Title ##### -->
GtkComboBox

<!-- ##### SECTION Short_Description ##### -->
5
A widget used to choose from a list of items
6 7 8

<!-- ##### SECTION Long_Description ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
9 10 11 12 13 14 15 16
A #GtkComboBox is a widget that allows the user to choose from a
list of valid choices.  The #GtkComboBox displays the selected 
choice.  When activated, the #GtkComboBox displays a popup 
which allows the user to make a new choice. The style in which 
the selected value is displayed, and the style of the popup is
determined by the current theme. It may be similar to a #GtkOptionMenu,
or similar to a Windows-style combo box.
</para>
17

Matthias Clasen's avatar
Matthias Clasen committed
18 19 20 21 22 23 24 25
<para>
Unlike its predecessors #GtkCombo and #GtkOptionMenu, the #GtkComboBox
uses the model-view pattern; the list of valid choices is specified in the
form of a tree model, and the display of the choices can be adapted to
the data in the model by using cell renderers, as you would in a tree view.
This is possible since #GtkComboBox implements the #GtkCellLayout interface.
The tree model holding the valid choices is not restricted to a flat list,
it can be a real tree, and the popup will reflect the tree structure.
26 27 28
</para>

<para>
Matthias Clasen's avatar
Matthias Clasen committed
29 30 31 32 33 34 35
In addition to the model-view API, #GtkComboBox offers a simple API which 
is suitable for text-only combo boxes, and hides the complexity of managing
the data in a model. It consists of the functions gtk_combo_box_new_text(), 
gtk_combo_box_append_text(), gtk_combo_box_insert_text(), 
gtk_combo_box_prepend_text(), gtk_combo_box_remove_text() and 
gtk_combo_box_get_active_text().
</para>
36

Matthias Clasen's avatar
Matthias Clasen committed
37 38 39
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkComboBoxEntry, #GtkTreeModel, #GtkCellRenderer
40 41
</para>

Matthias Clasen's avatar
Matthias Clasen committed
42 43 44
<!-- ##### SECTION Stability_Level ##### -->


45 46 47
<!-- ##### SECTION Image ##### -->


48 49 50 51 52
<!-- ##### STRUCT GtkComboBox ##### -->
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
53

Soeren Sandmann's avatar
Soeren Sandmann committed
54 55 56 57 58 59 60
<!-- ##### SIGNAL GtkComboBox::changed ##### -->
<para>

</para>

@combobox: the object which received the signal.

Tim Janik's avatar
Tim Janik committed
61 62 63 64 65 66 67 68
<!-- ##### SIGNAL GtkComboBox::move-active ##### -->
<para>

</para>

@combobox: the object which received the signal.
@arg1: 

Matthias Clasen's avatar
Matthias Clasen committed
69 70 71 72 73 74 75 76
<!-- ##### SIGNAL GtkComboBox::popdown ##### -->
<para>

</para>

@combobox: the object which received the signal.
@Returns: 

Tim Janik's avatar
Tim Janik committed
77 78 79 80 81 82 83
<!-- ##### SIGNAL GtkComboBox::popup ##### -->
<para>

</para>

@combobox: the object which received the signal.

Soeren Sandmann's avatar
Soeren Sandmann committed
84 85 86 87 88 89 90 91 92 93
<!-- ##### ARG GtkComboBox:active ##### -->
<para>

</para>

<!-- ##### ARG GtkComboBox:add-tearoffs ##### -->
<para>

</para>

Matthias Clasen's avatar
Matthias Clasen committed
94 95 96 97 98
<!-- ##### ARG GtkComboBox:button-sensitivity ##### -->
<para>

</para>

Soeren Sandmann's avatar
Soeren Sandmann committed
99 100 101 102 103
<!-- ##### ARG GtkComboBox:column-span-column ##### -->
<para>

</para>

Matthias Clasen's avatar
Matthias Clasen committed
104 105 106 107 108
<!-- ##### ARG GtkComboBox:focus-on-click ##### -->
<para>

</para>

Soeren Sandmann's avatar
Soeren Sandmann committed
109 110 111 112 113 114 115 116 117 118
<!-- ##### ARG GtkComboBox:has-frame ##### -->
<para>

</para>

<!-- ##### ARG GtkComboBox:model ##### -->
<para>

</para>

Matthias Clasen's avatar
Matthias Clasen committed
119 120 121 122 123
<!-- ##### ARG GtkComboBox:popup-shown ##### -->
<para>

</para>

Soeren Sandmann's avatar
Soeren Sandmann committed
124 125 126 127 128
<!-- ##### ARG GtkComboBox:row-span-column ##### -->
<para>

</para>

Matthias Clasen's avatar
Matthias Clasen committed
129 130 131 132 133
<!-- ##### ARG GtkComboBox:tearoff-title ##### -->
<para>

</para>

Soeren Sandmann's avatar
Soeren Sandmann committed
134 135 136 137 138 139 140 141 142 143
<!-- ##### ARG GtkComboBox:wrap-width ##### -->
<para>

</para>

<!-- ##### ARG GtkComboBox:appears-as-list ##### -->
<para>

</para>

Tim Janik's avatar
Tim Janik committed
144 145 146 147 148
<!-- ##### ARG GtkComboBox:arrow-size ##### -->
<para>

</para>

Matthias Clasen's avatar
Matthias Clasen committed
149 150 151 152 153
<!-- ##### ARG GtkComboBox:shadow-type ##### -->
<para>

</para>

154 155 156 157 158
<!-- ##### FUNCTION gtk_combo_box_new ##### -->
<para>

</para>

159
@void: 
Owen Taylor's avatar
Owen Taylor committed
160 161 162 163 164 165 166 167
@Returns: 


<!-- ##### FUNCTION gtk_combo_box_new_with_model ##### -->
<para>

</para>

168 169 170 171
@model: 
@Returns: 


Matthias Clasen's avatar
Matthias Clasen committed
172 173 174 175 176 177 178 179 180
<!-- ##### FUNCTION gtk_combo_box_get_wrap_width ##### -->
<para>

</para>

@combo_box: 
@Returns: 


181 182 183 184 185 186 187 188 189
<!-- ##### FUNCTION gtk_combo_box_set_wrap_width ##### -->
<para>

</para>

@combo_box: 
@width: 


Matthias Clasen's avatar
Matthias Clasen committed
190 191 192 193 194 195 196 197 198
<!-- ##### FUNCTION gtk_combo_box_get_row_span_column ##### -->
<para>

</para>

@combo_box: 
@Returns: 


199 200 201 202 203 204 205 206 207
<!-- ##### FUNCTION gtk_combo_box_set_row_span_column ##### -->
<para>

</para>

@combo_box: 
@row_span: 


Matthias Clasen's avatar
Matthias Clasen committed
208 209 210 211 212 213 214 215 216
<!-- ##### FUNCTION gtk_combo_box_get_column_span_column ##### -->
<para>

</para>

@combo_box: 
@Returns: 


217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240
<!-- ##### FUNCTION gtk_combo_box_set_column_span_column ##### -->
<para>

</para>

@combo_box: 
@column_span: 


<!-- ##### FUNCTION gtk_combo_box_get_active ##### -->
<para>

</para>

@combo_box: 
@Returns: 


<!-- ##### FUNCTION gtk_combo_box_set_active ##### -->
<para>

</para>

@combo_box: 
Matthias Clasen's avatar
Matthias Clasen committed
241
@index_: 
242 243


Owen Taylor's avatar
Owen Taylor committed
244
<!-- ##### FUNCTION gtk_combo_box_get_active_iter ##### -->
245 246 247 248 249
<para>

</para>

@combo_box: 
Owen Taylor's avatar
Owen Taylor committed
250
@iter: 
251 252 253
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
254
<!-- ##### FUNCTION gtk_combo_box_set_active_iter ##### -->
255 256 257 258
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
259 260
@combo_box: 
@iter: 
261 262


Owen Taylor's avatar
Owen Taylor committed
263
<!-- ##### FUNCTION gtk_combo_box_get_model ##### -->
264 265 266 267 268
<para>

</para>

@combo_box: 
Owen Taylor's avatar
Owen Taylor committed
269
@Returns: 
270 271


Owen Taylor's avatar
Owen Taylor committed
272
<!-- ##### FUNCTION gtk_combo_box_set_model ##### -->
273 274 275 276 277
<para>

</para>

@combo_box: 
Owen Taylor's avatar
Owen Taylor committed
278
@model: 
279 280


Owen Taylor's avatar
Owen Taylor committed
281
<!-- ##### FUNCTION gtk_combo_box_new_text ##### -->
282 283 284 285
<para>

</para>

286
@void: 
Owen Taylor's avatar
Owen Taylor committed
287
@Returns: 
288 289


Owen Taylor's avatar
Owen Taylor committed
290
<!-- ##### FUNCTION gtk_combo_box_append_text ##### -->
291 292 293 294
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
295 296
@combo_box: 
@text: 
297

Owen Taylor's avatar
Owen Taylor committed
298 299

<!-- ##### FUNCTION gtk_combo_box_insert_text ##### -->
300 301 302 303
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
304 305 306
@combo_box: 
@position: 
@text: 
307 308


Owen Taylor's avatar
Owen Taylor committed
309
<!-- ##### FUNCTION gtk_combo_box_prepend_text ##### -->
310 311 312 313
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
314 315
@combo_box: 
@text: 
316 317


Owen Taylor's avatar
Owen Taylor committed
318
<!-- ##### FUNCTION gtk_combo_box_remove_text ##### -->
319 320 321 322
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
323 324
@combo_box: 
@position: 
325 326


Matthias Clasen's avatar
Matthias Clasen committed
327 328 329 330 331 332 333 334 335
<!-- ##### FUNCTION gtk_combo_box_get_active_text ##### -->
<para>

</para>

@combo_box: 
@Returns: 


Matthias Clasen's avatar
Matthias Clasen committed
336 337 338 339 340 341 342 343 344
<!-- ##### FUNCTION gtk_combo_box_popup_for_device ##### -->
<para>

</para>

@combo_box: 
@device: 


345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360
<!-- ##### FUNCTION gtk_combo_box_popup ##### -->
<para>

</para>

@combo_box: 


<!-- ##### FUNCTION gtk_combo_box_popdown ##### -->
<para>

</para>

@combo_box: 


Matthias Clasen's avatar
Matthias Clasen committed
361 362 363 364 365 366 367 368 369 370
<!-- ##### FUNCTION gtk_combo_box_get_popup_accessible ##### -->
<para>

</para>

@combo_box: 
@Returns: 


<!-- ##### FUNCTION gtk_combo_box_get_row_separator_func ##### -->
Matthias Clasen's avatar
Matthias Clasen committed
371 372 373 374 375 376 377 378
<para>

</para>

@combo_box: 
@Returns: 


Matthias Clasen's avatar
Matthias Clasen committed
379
<!-- ##### FUNCTION gtk_combo_box_set_row_separator_func ##### -->
Matthias Clasen's avatar
Matthias Clasen committed
380 381 382 383 384
<para>

</para>

@combo_box: 
Matthias Clasen's avatar
Matthias Clasen committed
385 386 387
@func: 
@data: 
@destroy: 
Matthias Clasen's avatar
Matthias Clasen committed
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407


<!-- ##### FUNCTION gtk_combo_box_set_add_tearoffs ##### -->
<para>

</para>

@combo_box: 
@add_tearoffs: 


<!-- ##### FUNCTION gtk_combo_box_get_add_tearoffs ##### -->
<para>

</para>

@combo_box: 
@Returns: 


Matthias Clasen's avatar
Matthias Clasen committed
408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425
<!-- ##### FUNCTION gtk_combo_box_set_title ##### -->
<para>

</para>

@combo_box: 
@title: 


<!-- ##### FUNCTION gtk_combo_box_get_title ##### -->
<para>

</para>

@combo_box: 
@Returns: 


Matthias Clasen's avatar
Matthias Clasen committed
426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443
<!-- ##### FUNCTION gtk_combo_box_set_focus_on_click ##### -->
<para>

</para>

@combo: 
@focus_on_click: 


<!-- ##### FUNCTION gtk_combo_box_get_focus_on_click ##### -->
<para>

</para>

@combo: 
@Returns: 


Matthias Clasen's avatar
Matthias Clasen committed
444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461
<!-- ##### FUNCTION gtk_combo_box_set_button_sensitivity ##### -->
<para>

</para>

@combo_box: 
@sensitivity: 


<!-- ##### FUNCTION gtk_combo_box_get_button_sensitivity ##### -->
<para>

</para>

@combo_box: 
@Returns: