ComboBox

Object Hierarchy:

Description:

[ CCode ( type_id = "gtk_combo_box_get_type ()" ) ]
public class ComboBox : Widget, Accessible, Buildable, CellEditable, CellLayout, ConstraintTarget

A `GtkComboBox` is a widget that allows the user to choose from a list of valid choices.

![An example GtkComboBox](combo-box.png)

The `GtkComboBox` displays the selected choice; when activated, the `GtkComboBox` displays a popup which allows the user to make a new choice.

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 [iface@Gtk.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 [property@Gtk.ComboBox:has-entry] property allows the `GtkComboBox` to contain a [ class@Gtk.Entry]. This entry can be accessed by calling [method@Gtk.ComboBox.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, [class@Gtk.ComboBoxText] offers a simple alternative. Both `GtkComboBox` and `GtkComboBoxText` can contain an entry.

CSS nodes

``` combobox ├── box.linked │ ╰── button.combo │ ╰── box │ ├── cellview │ ╰── arrow ╰── window.popup ```

A normal combobox contains a box with the .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 ```

A `GtkComboBox` with an entry has a single CSS 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 gtk_accessible_role_combo_box role.

All known sub-classes:

ComboBoxText

Namespace: Gtk

Package: gtk4

Content:

Properties:

public int active { get; set; }
The item which is currently active.
public string? active_id { get; set; }
The value of the ID column of the active row.
public SensitivityType button_sensitivity { get; set; }
Whether the dropdown button is sensitive when the model is empty.
public Widget child { get; set; }
The child widget.
public int entry_text_column { get; set; }
The model column to associate with strings from the entry.
public bool has_entry { get; construct; }
Whether the combo box has an entry.
public bool has_frame { get; set; }
The `has-frame` property controls whether a frame is drawn around the entry.
public int id_column { get; set; }
The model column that provides string IDs for the values in the model, if != -1.
public TreeModel model { get; set; }
The model from which the combo box takes its values.
public bool popup_fixed_width { get; set; }
Whether the popup's width should be a fixed width matching the allocated width of the combo box.
public bool popup_shown { get; }
Whether the combo boxes dropdown is popped up.

Creation methods:

public ComboBox ()
Creates a new empty `GtkComboBox`.
public ComboBox.with_entry ()
Creates a new empty `GtkComboBox` with an entry.
public ComboBox.with_model (TreeModel model)
Creates a new `GtkComboBox` with a model.
public ComboBox.with_model_and_entry (TreeModel model)
Creates a new empty `GtkComboBox` with an entry and a model.

Methods:

public int get_active ()
Returns the index of the currently 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.
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 `GtkTreeModel` of this.
public bool get_popup_fixed_width ()
Gets whether the popup uses a fixed width.
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.
public void set_active_iter (TreeIter? iter)
Sets the current active item to be the one referenced by iter.
public void set_button_sensitivity (SensitivityType sensitivity)
Sets whether the dropdown button of the combo box should update its sensitivity depending on the model contents.
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.
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.

Signals:

public virtual signal void activate ()
Emitted to when the combo box is activated.
public virtual signal void changed ()
Emitted when the active item is changed.
public virtual signal string format_entry_text (string path)
Emitted to allow changing how the text in a combo box's entry is displayed.
public signal void move_active (ScrollType scroll_type)
Emitted to move the active selection.
public signal bool popdown ()
Emitted to popdown the combo box list.
public signal void popup ()
Emitted to popup the combo box list.

Inherited Members:

All known members inherited from class Gtk.Widget

All known members inherited from class GLib.Object

All known members inherited from interface Gtk.Accessible

All known members inherited from interface Gtk.Buildable

All known members inherited from interface Gtk.CellEditable

remove_widget

start_editing

All known members inherited from interface Gtk.CellLayout