Allows the user to choose an item from a list of options.
<picture> <source srcset="drop-down-dark.png"
media="(prefers-color-scheme: dark)"> <img alt="An example
GtkDropDown" src="drop-down.png"> </picture>
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
dropDownSetFactory. It is possible
to use a separate factory for the items in the popup, with
dropDownSetListFactory.
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
dropDownSetExpression.
GtkDropDown can optionally allow search in the popup, which
is useful if the list of options is long. To enable the search entry,
use
dropDownSetEnableSearch.
Here is a UI definition example for
GtkDropDown with a simple
model:
xml code
<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
dropDownNewFromStrings, for instance, the object returned from
dropDownGetSelectedItem 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
AccessibleRoleComboBox role.