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 <!-- ##### SECTION Image ##### -->
  46
  47
  48 <!-- ##### STRUCT GtkComboBox ##### -->
  49 <para>
  50
  51 </para>
  52
  53
  54 <!-- ##### SIGNAL GtkComboBox::changed ##### -->
  55 <para>
  56
  57 </para>
  58
  59 @combobox: the object which received the signal.
  60
  61 <!-- ##### SIGNAL GtkComboBox::move-active ##### -->
  62 <para>
  63
  64 </para>
  65
  66 @combobox: the object which received the signal.
  67 @arg1:
  68
  69 <!-- ##### SIGNAL GtkComboBox::popdown ##### -->
  70 <para>
  71
  72 </para>
  73
  74 @combobox: the object which received the signal.
  75 @Returns:
  76
  77 <!-- ##### SIGNAL GtkComboBox::popup ##### -->
  78 <para>
  79
  80 </para>
  81
  82 @combobox: the object which received the signal.
  83
  84 <!-- ##### ARG GtkComboBox:active ##### -->
  85 <para>
  86
  87 </para>
  88
  89 <!-- ##### ARG GtkComboBox:add-tearoffs ##### -->
  90 <para>
  91
  92 </para>
  93
  94 <!-- ##### ARG GtkComboBox:button-sensitivity ##### -->
  95 <para>
  96
  97 </para>
  98
  99 <!-- ##### ARG GtkComboBox:column-span-column ##### -->
 100 <para>
 101
 102 </para>
 103
 104 <!-- ##### ARG GtkComboBox:focus-on-click ##### -->
 105 <para>
 106
 107 </para>
 108
 109 <!-- ##### ARG GtkComboBox:has-frame ##### -->
 110 <para>
 111
 112 </para>
 113
 114 <!-- ##### ARG GtkComboBox:model ##### -->
 115 <para>
 116
 117 </para>
 118
 119 <!-- ##### ARG GtkComboBox:popup-shown ##### -->
 120 <para>
 121
 122 </para>
 123
 124 <!-- ##### ARG GtkComboBox:row-span-column ##### -->
 125 <para>
 126
 127 </para>
 128
 129 <!-- ##### ARG GtkComboBox:tearoff-title ##### -->
 130 <para>
 131
 132 </para>
 133
 134 <!-- ##### ARG GtkComboBox:wrap-width ##### -->
 135 <para>
 136
 137 </para>
 138
 139 <!-- ##### ARG GtkComboBox:appears-as-list ##### -->
 140 <para>
 141
 142 </para>
 143
 144 <!-- ##### ARG GtkComboBox:arrow-size ##### -->
 145 <para>
 146
 147 </para>
 148
 149 <!-- ##### ARG GtkComboBox:shadow-type ##### -->
 150 <para>
 151
 152 </para>
 153
 154 <!-- ##### FUNCTION gtk_combo_box_new ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @void:
 160 @Returns:
 161
 162
 163 <!-- ##### FUNCTION gtk_combo_box_new_with_model ##### -->
 164 <para>
 165
 166 </para>
 167
 168 @model:
 169 @Returns:
 170
 171
 172 <!-- ##### FUNCTION gtk_combo_box_get_wrap_width ##### -->
 173 <para>
 174
 175 </para>
 176
 177 @combo_box:
 178 @Returns:
 179
 180
 181 <!-- ##### FUNCTION gtk_combo_box_set_wrap_width ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @combo_box:
 187 @width:
 188
 189
 190 <!-- ##### FUNCTION gtk_combo_box_get_row_span_column ##### -->
 191 <para>
 192
 193 </para>
 194
 195 @combo_box:
 196 @Returns:
 197
 198
 199 <!-- ##### FUNCTION gtk_combo_box_set_row_span_column ##### -->
 200 <para>
 201
 202 </para>
 203
 204 @combo_box:
 205 @row_span:
 206
 207
 208 <!-- ##### FUNCTION gtk_combo_box_get_column_span_column ##### -->
 209 <para>
 210
 211 </para>
 212
 213 @combo_box:
 214 @Returns:
 215
 216
 217 <!-- ##### FUNCTION gtk_combo_box_set_column_span_column ##### -->
 218 <para>
 219
 220 </para>
 221
 222 @combo_box:
 223 @column_span:
 224
 225
 226 <!-- ##### FUNCTION gtk_combo_box_get_active ##### -->
 227 <para>
 228
 229 </para>
 230
 231 @combo_box:
 232 @Returns:
 233
 234
 235 <!-- ##### FUNCTION gtk_combo_box_set_active ##### -->
 236 <para>
 237
 238 </para>
 239
 240 @combo_box:
 241 @index_:
 242
 243
 244 <!-- ##### FUNCTION gtk_combo_box_get_active_iter ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @combo_box:
 250 @iter:
 251 @Returns:
 252
 253
 254 <!-- ##### FUNCTION gtk_combo_box_set_active_iter ##### -->
 255 <para>
 256
 257 </para>
 258
 259 @combo_box:
 260 @iter:
 261
 262
 263 <!-- ##### FUNCTION gtk_combo_box_get_model ##### -->
 264 <para>
 265
 266 </para>
 267
 268 @combo_box:
 269 @Returns:
 270
 271
 272 <!-- ##### FUNCTION gtk_combo_box_set_model ##### -->
 273 <para>
 274
 275 </para>
 276
 277 @combo_box:
 278 @model:
 279
 280
 281 <!-- ##### FUNCTION gtk_combo_box_new_text ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @void:
 287 @Returns:
 288
 289
 290 <!-- ##### FUNCTION gtk_combo_box_append_text ##### -->
 291 <para>
 292
 293 </para>
 294
 295 @combo_box:
 296 @text:
 297
 298
 299 <!-- ##### FUNCTION gtk_combo_box_insert_text ##### -->
 300 <para>
 301
 302 </para>
 303
 304 @combo_box:
 305 @position:
 306 @text:
 307
 308
 309 <!-- ##### FUNCTION gtk_combo_box_prepend_text ##### -->
 310 <para>
 311
 312 </para>
 313
 314 @combo_box:
 315 @text:
 316
 317
 318 <!-- ##### FUNCTION gtk_combo_box_remove_text ##### -->
 319 <para>
 320
 321 </para>
 322
 323 @combo_box:
 324 @position:
 325
 326
 327 <!-- ##### FUNCTION gtk_combo_box_get_active_text ##### -->
 328 <para>
 329
 330 </para>
 331
 332 @combo_box:
 333 @Returns:
 334
 335
 336 <!-- ##### FUNCTION gtk_combo_box_popup ##### -->
 337 <para>
 338
 339 </para>
 340
 341 @combo_box:
 342
 343
 344 <!-- ##### FUNCTION gtk_combo_box_popdown ##### -->
 345 <para>
 346
 347 </para>
 348
 349 @combo_box:
 350
 351
 352 <!-- ##### FUNCTION gtk_combo_box_get_popup_accessible ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @combo_box:
 358 @Returns:
 359
 360
 361 <!-- ##### FUNCTION gtk_combo_box_get_row_separator_func ##### -->
 362 <para>
 363
 364 </para>
 365
 366 @combo_box:
 367 @Returns:
 368
 369
 370 <!-- ##### FUNCTION gtk_combo_box_set_row_separator_func ##### -->
 371 <para>
 372
 373 </para>
 374
 375 @combo_box:
 376 @func:
 377 @data:
 378 @destroy:
 379
 380
 381 <!-- ##### FUNCTION gtk_combo_box_set_add_tearoffs ##### -->
 382 <para>
 383
 384 </para>
 385
 386 @combo_box:
 387 @add_tearoffs:
 388
 389
 390 <!-- ##### FUNCTION gtk_combo_box_get_add_tearoffs ##### -->
 391 <para>
 392
 393 </para>
 394
 395 @combo_box:
 396 @Returns:
 397
 398
 399 <!-- ##### FUNCTION gtk_combo_box_set_title ##### -->
 400 <para>
 401
 402 </para>
 403
 404 @combo_box:
 405 @title:
 406
 407
 408 <!-- ##### FUNCTION gtk_combo_box_get_title ##### -->
 409 <para>
 410
 411 </para>
 412
 413 @combo_box:
 414 @Returns:
 415
 416
 417 <!-- ##### FUNCTION gtk_combo_box_set_focus_on_click ##### -->
 418 <para>
 419
 420 </para>
 421
 422 @combo:
 423 @focus_on_click:
 424
 425
 426 <!-- ##### FUNCTION gtk_combo_box_get_focus_on_click ##### -->
 427 <para>
 428
 429 </para>
 430
 431 @combo:
 432 @Returns:
 433
 434
 435 <!-- ##### FUNCTION gtk_combo_box_set_button_sensitivity ##### -->
 436 <para>
 437
 438 </para>
 439
 440 @combo_box:
 441 @sensitivity:
 442
 443
 444 <!-- ##### FUNCTION gtk_combo_box_get_button_sensitivity ##### -->
 445 <para>
 446
 447 </para>
 448
 449 @combo_box:
 450 @Returns:
 451
 452