Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkcombobox.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkComboBox
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A widget used to choose from a list of items
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GtkComboBox is a widget that allows the user to choose from a
  10 list of valid choices.  The #GtkComboBox displays the selected
  11 choice.  When activated, the #GtkComboBox displays a popup
  12 which allows the user to make a new choice. The style in which
  13 the selected value is displayed, and the style of the popup is
  14 determined by the current theme. It may be similar to a #GtkOptionMenu,
  15 or similar to a Windows-style combo box.
  16 </para>
  17
  18 <para>
  19 Unlike its predecessors #GtkCombo and #GtkOptionMenu, the #GtkComboBox
  20 uses the model-view pattern; the list of valid choices is specified in the
  21 form of a tree model, and the display of the choices can be adapted to
  22 the data in the model by using cell renderers, as you would in a tree view.
  23 This is possible since #GtkComboBox implements the #GtkCellLayout interface.
  24 The tree model holding the valid choices is not restricted to a flat list,
  25 it can be a real tree, and the popup will reflect the tree structure.
  26 </para>
  27
  28 <para>
  29 In addition to the model-view API, #GtkComboBox offers a simple API which
  30 is suitable for text-only combo boxes, and hides the complexity of managing
  31 the data in a model. It consists of the functions gtk_combo_box_new_text(),
  32 gtk_combo_box_append_text(), gtk_combo_box_insert_text(),
  33 gtk_combo_box_prepend_text(), gtk_combo_box_remove_text() and
  34 gtk_combo_box_get_active_text().
  35 </para>
  36
  37 <!-- ##### SECTION See_Also ##### -->
  38 <para>
  39 #GtkComboBoxEntry, #GtkTreeModel, #GtkCellRenderer
  40 </para>
  41
  42 <!-- ##### SECTION Stability_Level ##### -->
  43
  44
  45 <!-- ##### STRUCT GtkComboBox ##### -->
  46 <para>
  47
  48 </para>
  49
  50
  51 <!-- ##### SIGNAL GtkComboBox::changed ##### -->
  52 <para>
  53
  54 </para>
  55
  56 @combobox: the object which received the signal.
  57
  58 <!-- ##### SIGNAL GtkComboBox::move-active ##### -->
  59 <para>
  60
  61 </para>
  62
  63 @combobox: the object which received the signal.
  64 @arg1:
  65
  66 <!-- ##### SIGNAL GtkComboBox::popdown ##### -->
  67 <para>
  68
  69 </para>
  70
  71 @combobox: the object which received the signal.
  72 @Returns:
  73
  74 <!-- ##### SIGNAL GtkComboBox::popup ##### -->
  75 <para>
  76
  77 </para>
  78
  79 @combobox: the object which received the signal.
  80
  81 <!-- ##### ARG GtkComboBox:active ##### -->
  82 <para>
  83
  84 </para>
  85
  86 <!-- ##### ARG GtkComboBox:add-tearoffs ##### -->
  87 <para>
  88
  89 </para>
  90
  91 <!-- ##### ARG GtkComboBox:button-sensitivity ##### -->
  92 <para>
  93
  94 </para>
  95
  96 <!-- ##### ARG GtkComboBox:column-span-column ##### -->
  97 <para>
  98
  99 </para>
 100
 101 <!-- ##### ARG GtkComboBox:focus-on-click ##### -->
 102 <para>
 103
 104 </para>
 105
 106 <!-- ##### ARG GtkComboBox:has-frame ##### -->
 107 <para>
 108
 109 </para>
 110
 111 <!-- ##### ARG GtkComboBox:model ##### -->
 112 <para>
 113
 114 </para>
 115
 116 <!-- ##### ARG GtkComboBox:popup-shown ##### -->
 117 <para>
 118
 119 </para>
 120
 121 <!-- ##### ARG GtkComboBox:row-span-column ##### -->
 122 <para>
 123
 124 </para>
 125
 126 <!-- ##### ARG GtkComboBox:tearoff-title ##### -->
 127 <para>
 128
 129 </para>
 130
 131 <!-- ##### ARG GtkComboBox:wrap-width ##### -->
 132 <para>
 133
 134 </para>
 135
 136 <!-- ##### ARG GtkComboBox:appears-as-list ##### -->
 137 <para>
 138
 139 </para>
 140
 141 <!-- ##### ARG GtkComboBox:arrow-size ##### -->
 142 <para>
 143
 144 </para>
 145
 146 <!-- ##### ARG GtkComboBox:shadow-type ##### -->
 147 <para>
 148
 149 </para>
 150
 151 <!-- ##### FUNCTION gtk_combo_box_new ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @Returns:
 157
 158
 159 <!-- ##### FUNCTION gtk_combo_box_new_with_model ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @model:
 165 @Returns:
 166
 167
 168 <!-- ##### FUNCTION gtk_combo_box_get_wrap_width ##### -->
 169 <para>
 170
 171 </para>
 172
 173 @combo_box:
 174 @Returns:
 175
 176
 177 <!-- ##### FUNCTION gtk_combo_box_set_wrap_width ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @combo_box:
 183 @width:
 184
 185
 186 <!-- ##### FUNCTION gtk_combo_box_get_row_span_column ##### -->
 187 <para>
 188
 189 </para>
 190
 191 @combo_box:
 192 @Returns:
 193
 194
 195 <!-- ##### FUNCTION gtk_combo_box_set_row_span_column ##### -->
 196 <para>
 197
 198 </para>
 199
 200 @combo_box:
 201 @row_span:
 202
 203
 204 <!-- ##### FUNCTION gtk_combo_box_get_column_span_column ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @combo_box:
 210 @Returns:
 211
 212
 213 <!-- ##### FUNCTION gtk_combo_box_set_column_span_column ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @combo_box:
 219 @column_span:
 220
 221
 222 <!-- ##### FUNCTION gtk_combo_box_get_active ##### -->
 223 <para>
 224
 225 </para>
 226
 227 @combo_box:
 228 @Returns:
 229
 230
 231 <!-- ##### FUNCTION gtk_combo_box_set_active ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @combo_box:
 237 @index_:
 238
 239
 240 <!-- ##### FUNCTION gtk_combo_box_get_active_iter ##### -->
 241 <para>
 242
 243 </para>
 244
 245 @combo_box:
 246 @iter:
 247 @Returns:
 248
 249
 250 <!-- ##### FUNCTION gtk_combo_box_set_active_iter ##### -->
 251 <para>
 252
 253 </para>
 254
 255 @combo_box:
 256 @iter:
 257
 258
 259 <!-- ##### FUNCTION gtk_combo_box_get_model ##### -->
 260 <para>
 261
 262 </para>
 263
 264 @combo_box:
 265 @Returns:
 266
 267
 268 <!-- ##### FUNCTION gtk_combo_box_set_model ##### -->
 269 <para>
 270
 271 </para>
 272
 273 @combo_box:
 274 @model:
 275
 276
 277 <!-- ##### FUNCTION gtk_combo_box_new_text ##### -->
 278 <para>
 279
 280 </para>
 281
 282 @Returns:
 283
 284
 285 <!-- ##### FUNCTION gtk_combo_box_append_text ##### -->
 286 <para>
 287
 288 </para>
 289
 290 @combo_box:
 291 @text:
 292
 293
 294 <!-- ##### FUNCTION gtk_combo_box_insert_text ##### -->
 295 <para>
 296
 297 </para>
 298
 299 @combo_box:
 300 @position:
 301 @text:
 302
 303
 304 <!-- ##### FUNCTION gtk_combo_box_prepend_text ##### -->
 305 <para>
 306
 307 </para>
 308
 309 @combo_box:
 310 @text:
 311
 312
 313 <!-- ##### FUNCTION gtk_combo_box_remove_text ##### -->
 314 <para>
 315
 316 </para>
 317
 318 @combo_box:
 319 @position:
 320
 321
 322 <!-- ##### FUNCTION gtk_combo_box_get_active_text ##### -->
 323 <para>
 324
 325 </para>
 326
 327 @combo_box:
 328 @Returns:
 329
 330
 331 <!-- ##### FUNCTION gtk_combo_box_popup ##### -->
 332 <para>
 333
 334 </para>
 335
 336 @combo_box:
 337
 338
 339 <!-- ##### FUNCTION gtk_combo_box_popdown ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @combo_box:
 345
 346
 347 <!-- ##### FUNCTION gtk_combo_box_get_popup_accessible ##### -->
 348 <para>
 349
 350 </para>
 351
 352 @combo_box:
 353 @Returns:
 354
 355
 356 <!-- ##### FUNCTION gtk_combo_box_get_row_separator_func ##### -->
 357 <para>
 358
 359 </para>
 360
 361 @combo_box:
 362 @Returns:
 363
 364
 365 <!-- ##### FUNCTION gtk_combo_box_set_row_separator_func ##### -->
 366 <para>
 367
 368 </para>
 369
 370 @combo_box:
 371 @func:
 372 @data:
 373 @destroy:
 374
 375
 376 <!-- ##### FUNCTION gtk_combo_box_set_add_tearoffs ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @combo_box:
 382 @add_tearoffs:
 383
 384
 385 <!-- ##### FUNCTION gtk_combo_box_get_add_tearoffs ##### -->
 386 <para>
 387
 388 </para>
 389
 390 @combo_box:
 391 @Returns:
 392
 393
 394 <!-- ##### FUNCTION gtk_combo_box_set_title ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @combo_box:
 400 @title:
 401
 402
 403 <!-- ##### FUNCTION gtk_combo_box_get_title ##### -->
 404 <para>
 405
 406 </para>
 407
 408 @combo_box:
 409 @Returns:
 410
 411
 412 <!-- ##### FUNCTION gtk_combo_box_set_focus_on_click ##### -->
 413 <para>
 414
 415 </para>
 416
 417 @combo:
 418 @focus_on_click:
 419
 420
 421 <!-- ##### FUNCTION gtk_combo_box_get_focus_on_click ##### -->
 422 <para>
 423
 424 </para>
 425
 426 @combo:
 427 @Returns:
 428
 429
 430 <!-- ##### FUNCTION gtk_combo_box_set_button_sensitivity ##### -->
 431 <para>
 432
 433 </para>
 434
 435 @combo_box:
 436 @sensitivity:
 437
 438
 439 <!-- ##### FUNCTION gtk_combo_box_get_button_sensitivity ##### -->
 440 <para>
 441
 442 </para>
 443
 444 @combo_box:
 445 @Returns:
 446
 447