DropDown — PyGObject

Skip to main content
`Ctrl`+`K`

# 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 constructing a simple `Gtk.DropDown` with `Gtk.DropDown.new_from_strings()` which creates a `Gtk.StringList` to use as its model.

     1import gi
     2
     3gi.require_version("Gtk", "4.0")
     4from gi.repository import Gtk
     5
     6
     7class DropDownWindow(Gtk.ApplicationWindow):
     8    def __init__(self, **kargs):
     9        super().__init__(**kargs, title="DropDown Demo")
    10
    11        items = "This is a long list of words to populate the dropdown".split()
    12        dropdown = Gtk.DropDown.new_from_strings(items)
    13        dropdown.connect("notify::selected-item", self.on_string_selected)
    14        self.set_child(dropdown)
    15
    16    def on_string_selected(self, dropdown, _pspec):
    17        # Selected Gtk.StringObject
    18        if selected := dropdown.get_selected_item():
    19            print("Selected", selected.get_string())
    20
    21
    22def on_activate(app):
    23    win = DropDownWindow(application=app)
    24    win.present()
    25
    26
    27app = Gtk.Application(application_id="com.example.App")
    28app.connect("activate", on_activate)
    29
    30app.run(None)