Gtk.DropDown¶

class — extends Widget, Accessible, Buildable, ConstraintTarget

Allows the user to choose an item from a list of options.

The GtkDropDown displays the [selected]DropDown.selected choice.

The options are given to GtkDropDown in the form of GListModel and how the individual options are represented is determined by a ListItemFactory. The default factory displays simple strings, and adds a checkmark to the selected item in the popup.

To set your own factory, use DropDown.set_factory. It is possible to use a separate factory for the items in the popup, with DropDown.set_list_factory.

GtkDropDown knows how to obtain strings from the items in a StringList; for other models, you have to provide an expression to find the strings via DropDown.set_expression.

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

Here is a UI definition example for GtkDropDown with a simple model:

<object class="GtkDropDown">
  <property name="model">
    <object class="GtkStringList">
      <items>
        <item translatable="yes">Factory</item>
        <item translatable="yes">Home</item>
        <item translatable="yes">Subway</item>
      </items>
    </object>
  </property>
</object>

If a GtkDropDown is created in this manner, or with DropDown.new_from_strings, for instance, the object returned from DropDown.get_selected_item will be a StringObject.

To learn more about the list widget framework, see the overview.

CSS nodes¶

GtkDropDown has a single CSS node with name dropdown, with the button and popover nodes as children.

Accessibility¶

GtkDropDown uses the AccessibleRole.combo_box role.

Constructors¶

new¶

@classmethod
def new(cls, model: Gio.ListModel | None = ..., expression: Expression | None = ...) -> Widget

Creates a new GtkDropDown.

You may want to call DropDown.set_factory to set up a way to map its items to widgets.

Parameters:

model — the model to use
expression — the expression to use

new_from_strings¶

@classmethod
def new_from_strings(cls, strings: list[str]) -> Widget

Creates a new GtkDropDown that is populated with the strings.

Parameters:

strings — The strings to put in the dropdown

Methods¶

get_enable_search¶

def get_enable_search(self) -> bool

Returns whether search is enabled.

get_expression¶

def get_expression(self) -> Expression | None

Gets the expression set that is used to obtain strings from items.

See DropDown.set_expression.

get_factory¶

def get_factory(self) -> ListItemFactory | None

Gets the factory that's currently used to populate list items.

The factory returned by this function is always used for the item in the button. It is also used for items in the popup if DropDown.list-factory is not set.

get_header_factory¶

def get_header_factory(self) -> ListItemFactory | None

Gets the factory that's currently used to create header widgets for the popup.

get_list_factory¶

def get_list_factory(self) -> ListItemFactory | None

Gets the factory that's currently used to populate list items in the popup.

get_model¶

def get_model(self) -> Gio.ListModel | None

Gets the model that provides the displayed items.

get_search_match_mode¶

def get_search_match_mode(self) -> StringFilterMatchMode

Returns the match mode that the search filter is using.

get_selected¶

def get_selected(self) -> int

Gets the position of the selected item.

get_selected_item¶

def get_selected_item(self) -> GObject.Object | None

Gets the selected item. If no item is selected, None is returned.

get_show_arrow¶

def get_show_arrow(self) -> bool

Returns whether to show an arrow within the widget.

set_enable_search¶

def set_enable_search(self, enable_search: bool) -> None

Sets whether a search entry will be shown in the popup that allows to search for items in the list.

Note that DropDown.expression must be set for search to work.

Parameters:

enable_search — whether to enable search

set_expression¶

def set_expression(self, expression: Expression | None = ...) -> None

Sets the expression that gets evaluated to obtain strings from items.

This is used for search in the popup. The expression must have a value type of G_TYPE_STRING.

Parameters:

expression — a GtkExpression

set_factory¶

def set_factory(self, factory: ListItemFactory | None = ...) -> None

Sets the GtkListItemFactory to use for populating list items.

Parameters:

factory — the factory to use

set_header_factory¶

def set_header_factory(self, factory: ListItemFactory | None = ...) -> None

Sets the GtkListItemFactory to use for creating header widgets for the popup.

Parameters:

factory — the factory to use

set_list_factory¶

def set_list_factory(self, factory: ListItemFactory | None = ...) -> None

Sets the GtkListItemFactory to use for populating list items in the popup.

Parameters:

factory — the factory to use

set_model¶

def set_model(self, model: Gio.ListModel | None = ...) -> None

Sets the GListModel to use.

Parameters:

model — the model to use

set_search_match_mode¶

def set_search_match_mode(self, search_match_mode: StringFilterMatchMode | int) -> None

Sets the match mode for the search filter.

Parameters:

search_match_mode — the new match mode

set_selected¶

def set_selected(self, position: int) -> None

Selects the item at the given position.

Parameters:

position — the position of the item to select, or INVALID_LIST_POSITION

set_show_arrow¶

def set_show_arrow(self, show_arrow: bool) -> None

Sets whether an arrow will be displayed within the widget.

Parameters:

show_arrow — whether to show an arrow within the widget

Properties¶

enable_search¶

enable_search: bool  # read/write

Whether to show a search entry in the popup.

Note that search requires DropDown.expression to be set.

expression¶

expression: Expression  # read/write

An expression to evaluate to obtain strings to match against the search term.

See DropDown.enable-search for how to enable search. If DropDown.factory is not set, the expression is also used to bind strings to labels produced by a default factory.

factory¶

factory: ListItemFactory  # read/write

Factory for populating list items.

header_factory¶

header_factory: ListItemFactory  # read/write

The factory for creating header widgets for the popup.

list_factory¶

list_factory: ListItemFactory  # read/write

The factory for populating list items in the popup.

If this is not set, DropDown.factory is used.

model¶

model: Gio.ListModel  # read/write

Model for the displayed items.

search_match_mode¶

search_match_mode: StringFilterMatchMode | int  # read/write

The match mode for the search filter.

selected¶

selected: int  # read/write

The position of the selected item.

If no item is selected, the property has the value INVALID_LIST_POSITION.

selected_item¶

selected_item: GObject.Object  # read-only

The selected item.

show_arrow¶

show_arrow: bool  # read/write

Whether to show an arrow within the GtkDropDown widget.

Signals¶

activate¶

def on_activate(self) -> None: ...

Emitted to when the drop down is activated.

The ::activate signal on GtkDropDown is an action signal and emitting it causes the drop down to pop up its dropdown.