:right-sidebar: True DropDown =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: DropDown(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget` ``GtkDropDown`` is a widget that allows the user to choose an item from a list of options. .. image:: https://docs.gtk.org/gtk4/drop-down.png The ``GtkDropDown`` displays the [selected]:obj:`~gi.repository.Gtk.DropDown.props.selected` choice. The options are given to ``GtkDropDown`` in the form of ``GListModel`` and how the individual options are represented is determined by a :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.DropDown.set_factory`\. It is possible to use a separate factory for the items in the popup, with :obj:`~gi.repository.Gtk.DropDown.set_list_factory`\. ``GtkDropDown`` knows how to obtain strings from the items in a :obj:`~gi.repository.Gtk.StringList`\; for other models, you have to provide an expression to find the strings via :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.DropDown.set_enable_search`\. Here is a UI definition example for ``GtkDropDown`` with a simple model: .. code-block:: xml :dedent: Factory Home Subway If a ``GtkDropDown`` is created in this manner, or with :obj:`~gi.repository.Gtk.DropDown.new_from_strings`\, for instance, the object returned from :obj:`~gi.repository.Gtk.DropDown.get_selected_item` will be a :obj:`~gi.repository.Gtk.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 :const:`~gi.repository.Gtk.AccessibleRole.COMBO_BOX` role. Constructors ------------ .. rst-class:: interim-class .. class:: DropDown :no-index: .. classmethod:: new(model: ~gi.repository.Gio.ListModel | None = None, expression: ~gi.repository.Gtk.Expression | None = None) -> ~gi.repository.Gtk.Widget Creates a new ``GtkDropDown``\. You may want to call :obj:`~gi.repository.Gtk.DropDown.set_factory` to set up a way to map its items to widgets. :param model: the model to use :param expression: the expression to use .. classmethod:: new_from_strings(strings: list[str]) -> ~gi.repository.Gtk.Widget Creates a new ``GtkDropDown`` that is populated with the strings. :param strings: The strings to put in the dropdown Methods ------- .. rst-class:: interim-class .. class:: DropDown :no-index: .. method:: get_enable_search() -> bool Returns whether search is enabled. .. method:: get_expression() -> ~gi.repository.Gtk.Expression | None Gets the expression set that is used to obtain strings from items. See :obj:`~gi.repository.Gtk.DropDown.set_expression`\. .. method:: get_factory() -> ~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.DropDown.props.list_factory` is not set. .. method:: get_header_factory() -> ~gi.repository.Gtk.ListItemFactory | None Gets the factory that's currently used to create header widgets for the popup. .. versionadded:: 4.12 .. method:: get_list_factory() -> ~gi.repository.Gtk.ListItemFactory | None Gets the factory that's currently used to populate list items in the popup. .. method:: get_model() -> ~gi.repository.Gio.ListModel | None Gets the model that provides the displayed items. .. method:: get_search_match_mode() -> ~gi.repository.Gtk.StringFilterMatchMode Returns the match mode that the search filter is using. .. versionadded:: 4.12 .. method:: get_selected() -> int Gets the position of the selected item. .. method:: get_selected_item() -> ~gi.repository.GObject.Object | None Gets the selected item. If no item is selected, :const:`None` is returned. .. method:: get_show_arrow() -> bool Returns whether to show an arrow within the widget. .. versionadded:: 4.6 .. method:: 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 :obj:`~gi.repository.Gtk.DropDown.props.expression` must be set for search to work. :param enable_search: whether to enable search .. method:: set_expression(expression: ~gi.repository.Gtk.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 :obj:`str`. :param expression: a ``GtkExpression`` .. method:: set_factory(factory: ~gi.repository.Gtk.ListItemFactory | None = None) -> None Sets the ``GtkListItemFactory`` to use for populating list items. :param factory: the factory to use .. method:: set_header_factory(factory: ~gi.repository.Gtk.ListItemFactory | None = None) -> None Sets the ``GtkListItemFactory`` to use for creating header widgets for the popup. .. versionadded:: 4.12 :param factory: the factory to use .. method:: set_list_factory(factory: ~gi.repository.Gtk.ListItemFactory | None = None) -> None Sets the ``GtkListItemFactory`` to use for populating list items in the popup. :param factory: the factory to use .. method:: set_model(model: ~gi.repository.Gio.ListModel | None = None) -> None Sets the ``GListModel`` to use. :param model: the model to use .. method:: set_search_match_mode(search_match_mode: ~gi.repository.Gtk.StringFilterMatchMode) -> None Sets the match mode for the search filter. .. versionadded:: 4.12 :param search_match_mode: the new match mode .. method:: set_selected(position: int) -> None Selects the item at the given position. :param position: the position of the item to select, or :const:`~gi.repository.Gtk.INVALID_LIST_POSITION` .. method:: set_show_arrow(show_arrow: bool) -> None Sets whether an arrow will be displayed within the widget. .. versionadded:: 4.6 :param show_arrow: whether to show an arrow within the widget Properties ---------- .. rst-class:: interim-class .. class:: DropDown :no-index: .. attribute:: props.enable_search :type: bool The type of the None singleton. .. attribute:: props.expression :type: ~gi.repository.Gtk.Expression The type of the None singleton. .. attribute:: props.factory :type: ~gi.repository.Gtk.ListItemFactory The type of the None singleton. .. attribute:: props.header_factory :type: ~gi.repository.Gtk.ListItemFactory The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.list_factory :type: ~gi.repository.Gtk.ListItemFactory The type of the None singleton. .. attribute:: props.model :type: ~gi.repository.Gio.ListModel The type of the None singleton. .. attribute:: props.search_match_mode :type: ~gi.repository.Gtk.StringFilterMatchMode The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.selected :type: int The type of the None singleton. .. attribute:: props.selected_item :type: ~gi.repository.GObject.Object The type of the None singleton. .. attribute:: props.show_arrow :type: bool The type of the None singleton. .. versionadded:: 4.6 Signals ------- .. rst-class:: interim-class .. class:: DropDown.signals :no-index: .. method:: 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. .. versionadded:: 4.6