: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` A single-line text entry widget for use as a search entry. The main API for interacting with a ``GtkSearchEntry`` as entry is the ``GtkEditable`` interface. .. image:: https://docs.gtk.org/gtk4/search-entry.png It will show an inactive symbolic “find” icon when the search entry is empty, and a symbolic “clear” icon when there is text. Clicking on the “clear” icon will empty the search entry. To make filtering appear more reactive, it is a good idea to not react to every change in the entry text immediately, but only after a short delay. To support this, ``GtkSearchEntry`` emits the :obj:`~gi.repository.Gtk.SearchEntry.signals.search_changed` signal which can be used instead of the :obj:`~gi.repository.Gtk.Editable.signals.changed` signal. The :obj:`~gi.repository.Gtk.SearchEntry.signals.previous_match`\, :obj:`~gi.repository.Gtk.SearchEntry.signals.next_match` and :obj:`~gi.repository.Gtk.SearchEntry.signals.stop_search` signals can be used to implement moving between search results and ending the search. Often, ``GtkSearchEntry`` will be fed events by means of being placed inside a :obj:`~gi.repository.Gtk.SearchBar`\. If that is not the case, you can use :obj:`~gi.repository.Gtk.SearchEntry.set_key_capture_widget` to let it capture key input from another widget. ``GtkSearchEntry`` provides only minimal API and should be used with the :obj:`~gi.repository.Gtk.Editable` API. Shortcuts and Gestures -------------------------------------------------------------------------------- The following signals have default keybindings: - :obj:`~gi.repository.Gtk.SearchEntry.signals.activate` - :obj:`~gi.repository.Gtk.SearchEntry.signals.next_match` - :obj:`~gi.repository.Gtk.SearchEntry.signals.previous_match` - :obj:`~gi.repository.Gtk.SearchEntry.signals.stop_search` CSS Nodes -------------------------------------------------------------------------------- .. code-block:: :dedent: entry.search ╰── text ``GtkSearchEntry`` has a single CSS node with name entry that carries a ``.search`` style class, and the text node is a child of that. Accessibility -------------------------------------------------------------------------------- ``GtkSearchEntry`` uses the :obj:`~gi.repository.Gtk.AccessibleRole.search_box` role. 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.key_capture_widget :type: ~gi.repository.Gtk.Widget The widget that the entry will use to capture key events. Key events are consumed by the search entry to start or continue a search. .. versionadded:: 4.22 .. 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 :kbd:`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 `__\. Applications should connect to it, to implement moving between matches. The default bindings for this signal is :kbd:`Ctrl`\+:kbd:`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 `__\. Applications should connect to it, to implement moving between matches. The default bindings for this signal is :kbd:`Ctrl`\+:kbd:`Shift`\+:kbd:`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 `__\. Applications should connect to it, to implement hiding the search entry in this case. The default bindings for this signal is :kbd:`Escape`\.