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
Windows-style combo box.
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
CellLayout 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.
To allow the user to enter values not in the model, the “has-entry” property allows the GtkComboBox to contain a
Entry. This entry can be accessed by calling
get_child on the combo box.
For a simple list of textual choices, the model-view API of GtkComboBox can be a bit overwhelming. In this case,
ComboBoxText offers a simple alternative. Both GtkComboBox and
ComboBoxText can contain an entry.
CSS nodes
combobox
├── box.linked
│ ╰── button.combo
│ ╰── box
│ ├── cellview
│ ╰── arrow
╰── window.popup
.linked class, a button with the .combo class and inside those buttons, there are a cellview and an arrow.
combobox
├── box.linked
│ ├── entry.combo
│ ╰── button.combo
│ ╰── box
│ ╰── arrow
╰── window.popup
SS node with name combobox. It contains a box with the .linked class. That box contains an entry and a button, both with the .combo class added.
The button also contains another node with name arrow.
Accessibility
GtkComboBox uses the COMBO_BOX role.
- public int get_active ()
Returns the index of the currently active item, or -1 if there’s no active
item.
- public unowned string? get_active_id ()
Returns the ID of the active row of this.
- public bool get_active_iter (out TreeIter iter)
Sets iter
to point to the currently active item, if any item is
active.
- public SensitivityType get_button_sensitivity ()
Returns whether the combo box sets the dropdown button sensitive or not when
there are no items in the model.
- public unowned Widget? get_child ()
Gets the child widget of this.
- public int get_entry_text_column ()
Returns the column which this is using to
get the strings from to display in the internal entry.
- public bool get_has_entry ()
Returns whether the combo box has an entry.
- public int get_id_column ()
Returns the column which this is using to
get string IDs for values from.
- public unowned TreeModel? get_model ()
Returns the TreeModel
which is acting as data source for this.
- public bool get_popup_fixed_width ()
Gets whether the popup uses a fixed width matching the allocated width of
the combo box.
- public unowned TreeViewRowSeparatorFunc? get_row_separator_func ()
Returns the current row separator function.
- public void popup_for_device (Device device)
Pops up the menu of this.
- public void set_active (int index_)
Sets the active item of this to be the
item at index
.
- public bool set_active_id (string? active_id)
Changes the active row of this to the one
that has an ID equal to active_id
, or unsets the active row if active_id
is null
.
- public void set_active_iter (TreeIter? iter)
Sets the current active item to be the one referenced by iter
,
or unsets the active item if iter
is null.
- public void set_button_sensitivity (SensitivityType sensitivity)
Sets whether the dropdown button of the combo box should be always sensitive
(gtk_sensitivity_on), never sensitive (gtk_sensitivity_off) or only if
there is at least one item to display (gtk_sensitivity_auto).
- public void set_child (Widget? child)
Sets the child widget of this.
- public void set_entry_text_column (int text_column)
Sets the model column which this should
use to get strings from to be text_column
.
- public void set_id_column (int id_column)
Sets the model column which this should
use to get string IDs for values from.
- public void set_model (TreeModel? model)
Sets the model used by this to be
model
.
- public void set_popup_fixed_width (bool fixed)
Specifies whether the popup’s width should be a fixed width matching the
allocated width of the combo box.
- public void set_row_separator_func (owned TreeViewRowSeparatorFunc? func)
Sets the row separator function, which is used to determine whether a row
should be drawn as a separator.