:right-sidebar: True

SearchEntry
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: SearchEntry(**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`, :class:`~gi.repository.Gtk.Editable`



:Constructors:

::

    SearchEntry(**properties)
    new() -> Gtk.Widget



Constructors
------------

.. rst-class:: interim-class

.. class:: SearchEntry
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a ``GtkSearchEntry``.














Methods
-------

.. rst-class:: interim-class

.. class:: SearchEntry
   :no-index:


   .. method:: get_input_hints() -> ~gi.repository.Gtk.InputHints

      Gets the input purpose for ``entry``.



      .. versionadded:: 4.14








   .. method:: get_input_purpose() -> ~gi.repository.Gtk.InputPurpose

      Gets the input purpose of ``entry``.



      .. versionadded:: 4.14








   .. method:: get_key_capture_widget() -> ~gi.repository.Gtk.Widget | None

      Gets the widget that ``entry`` is capturing key events from.










   .. method:: get_placeholder_text() -> str | None

      Gets the placeholder text associated with ``entry``.



      .. versionadded:: 4.10








   .. method:: get_search_delay() -> int

      Get the delay to be used between the last keypress and the
      :obj:`~gi.repository.Gtk.SearchEntry.signals.search_changed` signal being emitted.



      .. versionadded:: 4.8








   .. method:: set_input_hints(hints: ~gi.repository.Gtk.InputHints) -> None

      Sets the input hints for ``entry``.



      .. versionadded:: 4.14





      :param hints: the new input hints





   .. method:: set_input_purpose(purpose: ~gi.repository.Gtk.InputPurpose) -> None

      Sets the input purpose of ``entry``.



      .. versionadded:: 4.14





      :param purpose: the new input purpose





   .. method:: set_key_capture_widget(widget: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets ``widget`` as the widget that ``entry`` will capture key
      events from.

      Key events are consumed by the search entry to start or
      continue a search.

      If the entry is part of a ``GtkSearchBar``, it is preferable
      to call :obj:`~gi.repository.Gtk.SearchBar.set_key_capture_widget` instead,
      which will reveal the entry in addition to triggering the
      search entry.

      Note that despite the name of this function, the events
      are only 'captured' in the bubble phase, which means that
      editable child widgets of ``widget`` will receive text input
      before it gets captured. If that is not desired, you can
      capture and forward the events yourself with
      :obj:`~gi.repository.Gtk.EventControllerKey.forward`.







      :param widget: a ``GtkWidget``





   .. method:: set_placeholder_text(text: str | None = None) -> None

      Sets the placeholder text associated with ``entry``.



      .. versionadded:: 4.10





      :param text: the text to set as a placeholder





   .. method:: set_search_delay(delay: int) -> None

      Set the delay to be used between the last keypress and the
      :obj:`~gi.repository.Gtk.SearchEntry.signals.search_changed` signal being emitted.



      .. versionadded:: 4.8





      :param delay: a delay in milliseconds









Properties
----------

.. rst-class:: interim-class

.. class:: SearchEntry
   :no-index:
   

   .. attribute:: props.activates_default
      :type: bool

      Whether to activate the default widget when Enter is pressed.







   .. attribute:: props.input_hints
      :type: ~gi.repository.Gtk.InputHints

      The hints about input for the ``GtkSearchEntry`` used to alter the
      behaviour of input methods.



      .. versionadded:: 4.14





   .. attribute:: props.input_purpose
      :type: ~gi.repository.Gtk.InputPurpose

      The purpose for the ``GtkSearchEntry`` input used to alter the
      behaviour of input methods.



      .. versionadded:: 4.14





   .. attribute:: props.placeholder_text
      :type: str

      The text that will be displayed in the ``GtkSearchEntry``
      when it is empty and unfocused.







   .. attribute:: props.search_delay
      :type: int

      The delay in milliseconds from last keypress to the search
      changed signal.



      .. versionadded:: 4.8









Signals
-------

.. rst-class:: interim-class

.. class:: SearchEntry.signals
   :no-index:
   

   .. method:: activate() -> None

      Emitted when the entry is activated.

      The keybindings for this signal are all forms of the Enter key.










   .. method:: next_match() -> None

      Emitted when the user initiates a move to the next match
      for the current search string.

      This is a `keybinding signal <class.SignalAction.html>`_.

      Applications should connect to it, to implement moving
      between matches.

      The default bindings for this signal is Ctrl-g.










   .. method:: previous_match() -> None

      Emitted when the user initiates a move to the previous match
      for the current search string.

      This is a `keybinding signal <class.SignalAction.html>`_.

      Applications should connect to it, to implement moving
      between matches.

      The default bindings for this signal is Ctrl-Shift-g.










   .. method:: search_changed() -> None

      Emitted with a delay. The length of the delay can be
      changed with the :obj:`~gi.repository.Gtk.SearchEntry.props.search_delay`
      property.










   .. method:: search_started() -> None

      Emitted when the user initiated a search on the entry.










   .. method:: stop_search() -> None

      Emitted when the user stops a search via keyboard input.

      This is a `keybinding signal <class.SignalAction.html>`_.

      Applications should connect to it, to implement hiding
      the search entry in this case.

      The default bindings for this signal is Escape.