GtkComboBox

A gtk.combo_box.ComboBox is a widget that allows the user to choose from a list of valid choices.

The gtk.combo_box.ComboBox displays the selected choice; when activated, the gtk.combo_box.ComboBox displays a popup which allows the user to make a new choice.

The gtk.combo_box.ComboBox 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 gtk.combo_box.ComboBox implements the gtk.cell_layout.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 gtk.combo_box.ComboBox to contain a gtk.entry.Entry. This entry can be accessed by calling gtk.combo_box.ComboBox.getChild on the combo box.

For a simple list of textual choices, the model-view API of gtk.combo_box.ComboBox can be a bit overwhelming. In this case, gtk.combo_box_text.ComboBoxText offers a simple alternative. Both gtk.combo_box.ComboBox and gtk.combo_box_text.ComboBoxText 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 gtk.combo_box.ComboBox 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

gtk.combo_box.ComboBox uses the gtk.types.AccessibleRole.ComboBox role.