Description

Gnome::Gtk4::DropDown is a widget that allows the user to choose an item from a list of options.

The Gnome::Gtk4::DropDown displays the [selected]selected choice.

The options are given to Gnome::Gtk4::DropDown in the form of Gnome::Gio::R-ListModel and how the individual options are represented is determined by a Gnome::Gtk4::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().

Gnome::Gtk4::DropDown knows how to obtain strings from the items in a Gnome::Gtk4::StringList; for other models, you have to provide an expression to find the strings via .set-expression().

Gnome::Gtk4::DropDown 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 Gnome::Gtk4::DropDown with a simple model:

If a Gnome::Gtk4::DropDown is created in this manner, or with .new-from-strings(), for instance, the object returned from .get-selected-item() will be a Gnome::Gtk4::StringObject.

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

CSS nodes

Gnome::Gtk4::DropDown has a single CSS node with name dropdown, with the button and popover nodes as children.

Accessibility

Gnome::Gtk4::DropDown uses the GTK_ACCESSIBLE_ROLE_COMBO_BOX role.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-dropdown

Creates a new Gnome::Gtk4::DropDown.

You may want to call .set-factory() to set up a way to map its items to widgets.

method new-dropdown ( N-List() $model, N-Object() $expression --> Gnome::Gtk4::DropDown \)

• $model; (transfer ownership: full) the model to use.

• $expression; (transfer ownership: full) the expression to use.

new-from-strings

Creates a new Gnome::Gtk4::DropDown that is populated with the strings.

method new-from-strings ( Array[Str] $strings --> Gnome::Gtk4::DropDown \)

• $strings; The strings to put in the dropdown.

Methods

get-enable-search

Returns whether search is enabled.

method get-enable-search (--> Bool )

Return value; True if the popup includes a search entry.

get-expression

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

See .set-expression().

method get-expression (--> N-Object )

Return value; a Gnome::Gtk4::Expression.

get-factory

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.

method get-factory (--> N-Object )

Return value; The factory in use.

get-header-factory

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

method get-header-factory (--> N-Object )

Return value; The factory in use.

get-list-factory

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

method get-list-factory (--> N-Object )

Return value; The factory in use.

get-model

Gets the model that provides the displayed items.

method get-model (--> N-List )

Return value; The model in use.

get-search-match-mode

Returns the match mode that the search filter is using.

method get-search-match-mode (--> GtkStringFilterMatchMode )

Return value; the match mode of the search filter.

get-selected

Gets the position of the selected item.

method get-selected (--> UInt )

Return value; the position of the selected item, or GTK_INVALID_LIST_POSITION if not item is selected.

get-selected-item

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

method get-selected-item (--> gpointer )

Return value; The selected item.

get-show-arrow

Returns whether to show an arrow within the widget.

method get-show-arrow (--> Bool )

Return value; True if an arrow will be shown..

set-enable-search

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.

method set-enable-search ( Bool() $enable-search )

• $enable-search; whether to enable search.

set-expression

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 G_TYPE_STRING.

method set-expression ( N-Object() $expression )

• $expression; a Gnome::Gtk4::Expression.

set-factory

Sets the Gnome::Gtk4::ListItemFactory to use for populating list items.

method set-factory ( N-Object() $factory )

• $factory; the factory to use.

set-header-factory

Sets the Gnome::Gtk4::ListItemFactory to use for creating header widgets for the popup.

method set-header-factory ( N-Object() $factory )

• $factory; the factory to use.

set-list-factory

Sets the Gnome::Gtk4::ListItemFactory to use for populating list items in the popup.

method set-list-factory ( N-Object() $factory )

• $factory; the factory to use.

set-model

Sets the Gnome::Gio::R-ListModel to use.

method set-model ( N-List() $model )

• $model; the model to use.

set-search-match-mode

Sets the match mode for the search filter.

method set-search-match-mode ( GtkStringFilterMatchMode $search-match-mode )

• $search-match-mode; the new match mode.

set-selected

Selects the item at the given position.

method set-selected ( UInt() $position )

• $position; the position of the item to select, or GTK_INVALID_LIST_POSITION.

set-show-arrow

Sets whether an arrow will be displayed within the widget.

method set-show-arrow ( Bool() $show-arrow )

• $show-arrow; whether to show an arrow within the widget.

Signals

activate

Emitted to when the drop down is activated.

The `::activate` signal on Gnome::Gtk4::DropDown is an action signal and emitting it causes the drop down to pop up its dropdown.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::DropDown :$_widget,
  *C<user>-options
)

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::DropDown object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.