13. ComboBox

A Gtk.ComboBox allows for the selection of an item from a dropdown menu. They are preferable to having many radio buttons on screen as they take up less room. If appropriate, it can show extra information about each item, such as text, a picture, a checkbox, or a progress bar.

Gtk.ComboBox is very similar to Gtk.TreeView, as both use 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. If the combo box contains a large number of items, it may be better to display them in a grid rather than a list. This can be done by calling Gtk.ComboBox.set_wrap_width().

The Gtk.ComboBox widget usually restricts the user to the available choices, but it can optionally have an Gtk.Entry, allowing the user to enter arbitrary text if none of the available choices are suitable. To do this, use one of the static methods Gtk.ComboBox.new_with_entry() or Gtk.ComboBox.new_with_model_and_entry() to create an Gtk.ComboBox instance.

For a simple list of textual choices, the model-view API of Gtk.ComboBox can be a bit overwhelming. In this case, Gtk.ComboBoxText offers a simple alternative. Both Gtk.ComboBox and Gtk.ComboBoxText can contain an entry.

13.1. ComboBox objects

class Gtk.ComboBox

static new_with_entry()

Creates a new empty Gtk.ComboBox with an entry.

static new_with_model(model)

Creates a new Gtk.ComboBox with the model initialized to model.

static new_with_model_and_entry(model)

Creates a new Gtk.ComboBox with an entry and the model initialized to model.

get_active_iter()

Returns a Gtk.TreeIter pointing to the current active item. If no active item exists, None is returned.

set_model(model)

Sets the model used by this combo box to be model. Will unset a previously set model (if applicable). If model is None, then it will unset the model. Note that this function does not clear the cell renderers.

get_model()

Returns the Gtk.TreeModel which is acting as data source for this combo box.

set_entry_text_column(text_column)

Sets the model column which this combo box should use to get strings from to be text_column. The column text_column in the model of this combo box must be of type str.

This is only relevant if this combo box has been created with the “has-entry” property set to True.

set_wrap_width(width)

Sets the wrap width of this combo box to be width. The wrap width is basically the preferred number of columns when you want the popup to be layed out in a grid.

13.2. ComboBoxText objects

class Gtk.ComboBoxText

static new_with_entry()

Creates a new empty Gtk.ComboBoxText with an entry.

append_text(text)

Appends text to the list of strings stored in this combo box.

get_active_text()

Returns the currently active string in this combo box, or None if none is selected. If this combo box contains an entry, this function will return its contents (which will not necessarily be an item from the list).

13.3. Example

from gi.repository import Gtk

class ComboBoxWindow(Gtk.Window):

    def __init__(self):
        Gtk.Window.__init__(self, title="ComboBox Example")

        self.set_border_width(10)

        name_store = Gtk.ListStore(int, str)
        name_store.append([1, "Billy Bob"])
        name_store.append([11, "Billy Bob Junior"])
        name_store.append([12, "Sue Bob"])
        name_store.append([2, "Joey Jojo"])
        name_store.append([3, "Rob McRoberts"])
        name_store.append([31, "Xavier McRoberts"])

        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)

        name_combo = Gtk.ComboBox.new_with_model_and_entry(name_store)
        name_combo.connect("changed", self.on_name_combo_changed)
        name_combo.set_entry_text_column(1)
        vbox.pack_start(name_combo, False, False, 0)

        country_store = Gtk.ListStore(str)
        countries = ["Austria", "Brazil", "Belgium", "France", "Germany",
            "Switzerland", "United Kingdom", "United States of America", "Uruguay"]
        for country in countries:
            country_store.append([country])

        country_combo = Gtk.ComboBox.new_with_model(country_store)
        country_combo.connect("changed", self.on_country_combo_changed)
        renderer_text = Gtk.CellRendererText()
        country_combo.pack_start(renderer_text, True)
        country_combo.add_attribute(renderer_text, "text", 0)
        vbox.pack_start(country_combo, False, False, True)

        currencies = ["Euro", "US Dollars", "British Pound", "Japanese Yen",
            "Russian Ruble", "Mexican peso", "Swiss franc"]
        currency_combo = Gtk.ComboBoxText()
        currency_combo.set_entry_text_column(0)
        currency_combo.connect("changed", self.on_currency_combo_changed)
        for currency in currencies:
            currency_combo.append_text(currency)

        vbox.pack_start(currency_combo, False, False, 0)

        self.add(vbox)

    def on_name_combo_changed(self, combo):
        tree_iter = combo.get_active_iter()
        if tree_iter != None:
            model = combo.get_model()
            row_id, name = model[tree_iter][:2]
            print "Selected: ID=%d, name=%s" % (row_id, name)
        else:
            entry = combo.get_child()
            print "Entered: %s" % entry.get_text()

    def on_country_combo_changed(self, combo):
        tree_iter = combo.get_active_iter()
        if tree_iter != None:
            model = combo.get_model()
            country = model[tree_iter][0]
            print "Selected: country=%s" % country

    def on_currency_combo_changed(self, combo):
        text = combo.get_active_text()
        if text != None:
            print "Selected: currency=%s" % text

win = ComboBoxWindow()
win.connect("delete-event", Gtk.main_quit)
win.show_all()
Gtk.main()