Gtk.DropDown¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` (model, expression)
class	`new_from_strings` (strings)
	`get_enable_search` ()
	`get_expression` ()
	`get_factory` ()
	`get_header_factory` ()
	`get_list_factory` ()
	`get_model` ()
	`get_search_match_mode` ()
	`get_selected` ()
	`get_selected_item` ()
	`get_show_arrow` ()
	`set_enable_search` (enable_search)
	`set_expression` (expression)
	`set_factory` (factory)
	`set_header_factory` (factory)
	`set_list_factory` (factory)
	`set_model` (model)
	`set_search_match_mode` (search_match_mode)
	`set_selected` (position)
	`set_show_arrow` (show_arrow)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9)

Properties¶

Inherited:: Gtk.Widget (34), Gtk.Accessible (1)

Name	Type	Flags
`enable-search`	`bool`	r/w/en
`expression`	`Gtk.Expression`	r/w/en
`factory`	`Gtk.ListItemFactory`	r/w/en
`header-factory`	`Gtk.ListItemFactory`	r/w/en
`list-factory`	`Gtk.ListItemFactory`	r/w/en
`model`	`Gio.ListModel`	r/w/en
`search-match-mode`	`Gtk.StringFilterMatchMode`	r/w/en
`selected`	`int`	r/w/en
`selected-item`	`GObject.Object`	r
`show-arrow`	`bool`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`activate`	Emitted to when the drop down is activated.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Gtk.DropDown(**kwargs)¶

Bases:: Gtk.Widget
Abstract:: No
Structure:: Gtk.DropDownClass

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

An example Gtk.DropDown

The GtkDropDown displays the ‘selected [property@Gtk.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 [class`Gtk`.ListItemFactory]. The default factory displays simple strings, and adds a checkmark to the selected item in the popup.

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

GtkDropDown knows how to obtain strings from the items in a [class`Gtk`.StringList]; for other models, you have to provide an expression to find the strings via [method`Gtk`.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 [method`Gtk`.DropDown.set_enable_search].

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

```xml

<items> Factory</item> Home</item> Subway</item> </items> </object>

/object ```

To learn more about the list widget framework, see the [overview](section-list-widget.html).

## CSS nodes

`:obj:Gtk.DropDown` has a single CSS node with name dropdown, with the button and popover nodes as children.

## Accessibility

`:obj:Gtk.DropDown` uses the Gtk.AccessibleRole.COMBO_BOX role.

classmethod new(model, expression)[source]¶

Parameters:

model (Gio.ListModel or None) – the model to use
expression (Gtk.Expression or None) – the expression to use

Returns:

a new GtkDropDown

Return type:

Gtk.Widget

Creates a new GtkDropDown.

You may want to call [method`Gtk`.DropDown.set_factory] to set up a way to map its items to widgets.

classmethod new_from_strings(strings)[source]¶

Parameters:: strings ([str]) – The strings to put in the dropdown
Returns:: a new GtkDropDown
Return type:: Gtk.Widget

Creates a new GtkDropDown that is populated with the strings.

get_enable_search()[source]¶

Returns:: True if the popup includes a search entry
Return type:: bool

Returns whether search is enabled.

get_expression()[source]¶

Returns:: a GtkExpression
Return type:: Gtk.Expression or None

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

See [method`Gtk`.DropDown.set_expression].

get_factory()[source]¶

Returns:: The factory in use
Return type:: Gtk.ListItemFactory or 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 [property`Gtk`.DropDown:list-factory] is not set.

get_header_factory()[source]¶

Returns:: The factory in use
Return type:: Gtk.ListItemFactory or None

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

New in version 4.12.

get_list_factory()[source]¶

Returns:: The factory in use
Return type:: Gtk.ListItemFactory or None

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

get_model()[source]¶

Returns:: The model in use
Return type:: Gio.ListModel or None

Gets the model that provides the displayed items.

get_search_match_mode()[source]¶

Returns:: the match mode of the search filter
Return type:: Gtk.StringFilterMatchMode

Returns the match mode that the search filter is using.

New in version 4.12.

get_selected()[source]¶

Returns:: the position of the selected item, or Gtk.INVALID_LIST_POSITION if not item is selected
Return type:: int

Gets the position of the selected item.

get_selected_item()[source]¶

Returns:: The selected item
Return type:: GObject.Object or None

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

get_show_arrow()[source]¶

Returns:: True if an arrow will be shown.
Return type:: bool

Returns whether to show an arrow within the widget.

New in version 4.6.

set_enable_search(enable_search)[source]¶

Parameters:: enable_search (bool) – whether to enable search

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

Note that [property`Gtk`.DropDown:expression] must be set for search to work.

set_expression(expression)[source]¶

Parameters:: expression (Gtk.Expression or None) – a GtkExpression

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 GObject.TYPE_STRING.

set_factory(factory)[source]¶

Parameters:: factory (Gtk.ListItemFactory or None) – the factory to use

Sets the GtkListItemFactory to use for populating list items.

set_header_factory(factory)[source]¶

Parameters:: factory (Gtk.ListItemFactory or None) – the factory to use

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

New in version 4.12.

set_list_factory(factory)[source]¶

Parameters:: factory (Gtk.ListItemFactory or None) – the factory to use

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

set_model(model)[source]¶

Parameters:: model (Gio.ListModel or None) – the model to use

Sets the GListModel to use.

set_search_match_mode(search_match_mode)[source]¶

Parameters:: search_match_mode (Gtk.StringFilterMatchMode) – the new match mode

Sets the match mode for the search filter.

New in version 4.12.

set_selected(position)[source]¶

Parameters:: position (int) – the position of the item to select, or Gtk.INVALID_LIST_POSITION

Selects the item at the given position.

set_show_arrow(show_arrow)[source]¶

Parameters:: show_arrow (bool) – whether to show an arrow within the widget

Sets whether an arrow will be displayed within the widget.

New in version 4.6.

Signal Details¶

Gtk.DropDown.signals.activate(drop_down)¶

Signal Name:: activate
Flags:: RUN_FIRST, ACTION
Parameters:: drop_down (Gtk.DropDown) – The object which received the signal

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.

New in version 4.6.

Property Details¶

Gtk.DropDown.props.enable_search¶

Name:: enable-search
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to show a search entry in the popup.

Note that search requires [property`Gtk`.DropDown:expression] to be set.

Gtk.DropDown.props.expression¶

Name:: expression
Type:: Gtk.Expression
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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

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

Gtk.DropDown.props.factory¶

Name:: factory
Type:: Gtk.ListItemFactory
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Factory for populating list items.

Gtk.DropDown.props.header_factory¶

Name:: header-factory
Type:: Gtk.ListItemFactory
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The factory for creating header widgets for the popup.

New in version 4.12.

Gtk.DropDown.props.list_factory¶

Name:: list-factory
Type:: Gtk.ListItemFactory
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The factory for populating list items in the popup.

If this is not set, [property`Gtk`.DropDown:factory] is used.

Gtk.DropDown.props.model¶

Name:: model
Type:: Gio.ListModel
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Model for the displayed items.

Gtk.DropDown.props.search_match_mode¶

Name:: search-match-mode
Type:: Gtk.StringFilterMatchMode
Default Value:: Gtk.StringFilterMatchMode.PREFIX
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The match mode for the search filter.

New in version 4.12.

Gtk.DropDown.props.selected¶

Name:: selected
Type:: int
Default Value:: 4294967295
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The position of the selected item.

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

Gtk.DropDown.props.selected_item¶

Name:: selected-item
Type:: GObject.Object
Default Value:: None
Flags:: READABLE

The selected item.

Gtk.DropDown.props.show_arrow¶

Name:: show-arrow
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to show an arrow within the Gtk.DropDown widget.

New in version 4.6.