DropDown
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
Methods
- class DropDown
-
- 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_search_match_mode() StringFilterMatchMode
Returns the match mode that the search filter is using.
Added in version 4.12.
- get_selected_item() Object | None
Gets the selected item. If no item is selected,
None
is returned.
- 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
Properties
- class DropDown
- props.enable_search: bool
Whether to show a search entry in the popup.
Note that search requires
expression
to be set.
- props.expression: Expression
An expression to evaluate to obtain strings to match against the search term.
See
enable_search
for how to enable search. Iffactory
is not set, the expression is also used to bind strings to labels produced by a default factory.
- props.factory: ListItemFactory
Factory for populating list items.
- props.header_factory: ListItemFactory
The factory for creating header widgets for the popup.
Added in version 4.12.
- props.list_factory: ListItemFactory
The factory for populating list items in the popup.
If this is not set,
factory
is used.
- props.search_match_mode: StringFilterMatchMode
The match mode for the search filter.
Added in version 4.12.
- props.selected: int
The position of the selected item.
If no item is selected, the property has the value
INVALID_LIST_POSITION
.