DropDown

Gtk.DropDown allows the user to choose an item from a list of options. They are preferable to having many radio buttons on screen as they take up less room.

To populate its options Gtk.DropDown uses a Gio.ListModel. Gio.ListModel it’s an interface that represents a mutable list of GObject.Objects. For text-only uses cases GTK provides Gtk.StringList, a list model that wraps an array of strings wrapped on Gtk.StringObject and Gtk.DropDown knows how to use it.

Gtk.DropDown can optionally allow search in the popup, which is useful if the list of options is long. To enable the search entry, use Gtk.DropDown.props.enable_search.

Attention

If you use custom list models with custom gobjects you must provide a Gtk.Expression through Gtk.DropDown.props.expression so Gtk.DropDown can know how to filter the gobjects. Gtk.Expression has been supported in PyGObject since release 3.48.

Gtk.DropDown stores the selected item from the list model in Gtk.DropDown.props.selected_item, and the position of that item on Gtk.DropDown.props.selected. To know when the selection has changed just connect to notify::selected-item or notify::selected.

Example

We are creating a simple Gtk.DropDown using Gtk.StringList.

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class DropDownWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='DropDown Demo')

        dropdown = Gtk.DropDown()
        dropdown.connect('notify::selected-item', self.on_string_selected)
        self.set_child(dropdown)

        strings = Gtk.StringList()
        dropdown.props.model = strings
        items = 'This is a long list of words to populate the dropdown'.split()

        # Populate the list
        for item in items:
            strings.append(item)

    def on_string_selected(self, dropdown, _pspec):
        # Selected Gtk.StringObject
        selected = dropdown.props.selected_item
        if selected is not None:
            print('Selected', selected.props.string)


def on_activate(app):
    win = DropDownWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)