DropDown

class DropDown(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

GtkDropDown is a widget that allows the user to choose an item from a list of options.

The GtkDropDown displays the [selected]:obj: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 set_factory. It is possible to use a separate factory for the items in the popup, with 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 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 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 new_from_strings, for instance, the object returned from 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 COMBO_BOX role.

Constructors

class DropDown

classmethod new(model: ListModel | None = None, expression: Expression | None = None) → Widget

Creates a new GtkDropDown.

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

Parameters:

• model – the model to use

• expression – the expression to use

classmethod new_from_strings(strings: list[str]) → Widget

Creates a new GtkDropDown that is populated with the strings.

Parameters:

strings – The strings to put in the dropdown

Methods

class DropDown

get_enable_search() → bool

Returns whether search is enabled.

get_expression() → Expression | None

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

See set_expression.

get_factory() → 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 list_factory is not set.

get_header_factory() → ListItemFactory | None

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

Added in version 4.12.

get_list_factory() → ListItemFactory | None

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

get_model() → ListModel | None

Gets the model that provides the displayed items.

get_search_match_mode() → StringFilterMatchMode

Returns the match mode that the search filter is using.

Added in version 4.12.

get_selected() → int

Gets the position of the selected item.

get_selected_item() → Object | None

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

get_show_arrow() → bool

Returns whether to show an arrow within the widget.

Added in version 4.6.

set_enable_search(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 expression must be set for search to work.

Parameters:

enable_search – whether to enable search

set_expression(expression: Expression | None = 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 str.

Parameters:

expression – a GtkExpression

set_factory(factory: ListItemFactory | None = None) → None

Sets the GtkListItemFactory to use for populating list items.

Parameters:

factory – the factory to use

set_header_factory(factory: ListItemFactory | None = None) → None

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

Added in version 4.12.

Parameters:

factory – the factory to use

set_list_factory(factory: ListItemFactory | None = None) → None

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

Parameters:

factory – the factory to use

set_model(model: ListModel | None = None) → None

Sets the GListModel to use.

Parameters:

model – the model to use

set_search_match_mode(search_match_mode: StringFilterMatchMode) → None

Sets the match mode for the search filter.

Added in version 4.12.

Parameters:

search_match_mode – the new match mode

set_selected(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(show_arrow: bool) → None

Sets whether an arrow will be displayed within the widget.

Added in version 4.6.

Parameters:

show_arrow – whether to show an arrow within the widget

Properties

class DropDown

props.enable_search: bool

The type of the None singleton.

props.expression: Expression

The type of the None singleton.

props.factory: ListItemFactory

The type of the None singleton.

props.header_factory: ListItemFactory

The type of the None singleton.

Added in version 4.12.

props.list_factory: ListItemFactory

The type of the None singleton.

props.model: ListModel

The type of the None singleton.

props.search_match_mode: StringFilterMatchMode

The type of the None singleton.

Added in version 4.12.

props.selected: int

The type of the None singleton.

props.selected_item: Object

The type of the None singleton.

props.show_arrow: bool

The type of the None singleton.

Added in version 4.6.

Signals

class DropDown.signals

activate() → 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.

Added in version 4.6.