: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::
   :dedent:

   <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
: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 <section-list-widget.html>`_.

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: ~typing.Sequence[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

      Whether to show a search entry in the popup.

      Note that search requires :obj:`~gi.repository.Gtk.DropDown.props.expression`
      to be set.







   .. attribute:: props.expression
      :type: ~gi.repository.Gtk.Expression

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

      See :obj:`~gi.repository.Gtk.DropDown.props.enable_search` for how to enable search.
      If :obj:`~gi.repository.Gtk.DropDown.props.factory` is not set, the expression is also
      used to bind strings to labels produced by a default factory.







   .. attribute:: props.factory
      :type: ~gi.repository.Gtk.ListItemFactory

      Factory for populating list items.







   .. attribute:: props.header_factory
      :type: ~gi.repository.Gtk.ListItemFactory

      The factory for creating header widgets for the popup.



      .. versionadded:: 4.12





   .. attribute:: props.list_factory
      :type: ~gi.repository.Gtk.ListItemFactory

      The factory for populating list items in the popup.

      If this is not set, :obj:`~gi.repository.Gtk.DropDown.props.factory` is used.







   .. attribute:: props.model
      :type: ~gi.repository.Gio.ListModel

      Model for the displayed items.







   .. attribute:: props.search_match_mode
      :type: ~gi.repository.Gtk.StringFilterMatchMode

      The match mode for the search filter.



      .. versionadded:: 4.12





   .. attribute:: props.selected
      :type: int

      The position of the selected item.

      If no item is selected, the property has the value
      :const:`~gi.repository.Gtk.INVALID_LIST_POSITION`.







   .. attribute:: props.selected_item
      :type: ~gi.repository.GObject.Object

      The selected item.







   .. attribute:: props.show_arrow
      :type: bool

      Whether to show an arrow within the GtkDropDown widget.



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