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: Sequence[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.