Gtk.SearchEntry¶

Example¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1), Gtk.Editable (27)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
	`get_key_capture_widget` ()
	`get_placeholder_text` ()
	`get_search_delay` ()
	`set_key_capture_widget` (widget)
	`set_placeholder_text` (text)
	`set_search_delay` (delay)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9), Gtk.Editable (9)

Properties¶

Inherited:: Gtk.Widget (34), Gtk.Accessible (1), Gtk.Editable (8)

Name	Type	Flags
`activates-default`	`bool`	r/w/en
`placeholder-text`	`str`	r/w
`search-delay`	`int`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1), Gtk.Editable (3)

Name	Short Description
`activate`	Emitted when the entry is activated.
`next-match`	Emitted when the user initiates a move to the next match for the current search string.
`previous-match`	Emitted when the user initiates a move to the previous match for the current search string.
`search-changed`	Emitted with a delay.
`search-started`	Emitted when the user initiated a search on the entry.
`stop-search`	Emitted when the user stops a search via keyboard input.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1), Gtk.Editable (3)

Class Details¶

class Gtk.SearchEntry(**kwargs)¶

Bases:: Gtk.Widget, Gtk.Editable
Abstract:: No

GtkSearchEntry is an entry widget that has been tailored for use as a search entry.

The main API for interacting with a GtkSearchEntry as entry is the GtkEditable interface.

An example Gtk.SearchEntry

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 [signal`Gtk`.SearchEntry::search-changed] signal which can be used instead of the [signal`Gtk`.Editable::changed] signal.

The [signal`Gtk`.SearchEntry::previous-match], [signal`Gtk`.SearchEntry::next-match] and [signal`Gtk`.SearchEntry::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 [class`Gtk`.SearchBar]. If that is not the case, you can use [method`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 [iface`Gtk`.Editable] API.

CSS Nodes

`` 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 Gtk.AccessibleRole.SEARCH_BOX role.

classmethod new()[source]¶

Returns:: a new GtkSearchEntry
Return type:: Gtk.Widget

Creates a GtkSearchEntry.

get_key_capture_widget()[source]¶

Returns:: The key capture widget.
Return type:: Gtk.Widget or None

Gets the widget that self is capturing key events from.

get_placeholder_text()[source]¶

Returns:: The placeholder text.
Return type:: str or None

Gets the placeholder text associated with self.

New in version 4.10.

get_search_delay()[source]¶

Returns:: a delay in milliseconds.
Return type:: int

Get the delay to be used between the last keypress and the [signal`Gtk`.SearchEntry::search-changed] signal being emitted.

New in version 4.8.

set_key_capture_widget(widget)[source]¶

Parameters:: widget (Gtk.Widget or None) – a GtkWidget

Sets widget as the widget that self 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 [method`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 [method`Gtk`.EventControllerKey.forward].

set_placeholder_text(text)[source]¶

Parameters:: text (str or None) – the text to set as a placeholder

Sets the placeholder text associated with self.

New in version 4.10.

set_search_delay(delay)[source]¶

Parameters:: delay (int) – a delay in milliseconds

Set the delay to be used between the last keypress and the [signal`Gtk`.SearchEntry::search-changed] signal being emitted.

New in version 4.8.

Signal Details¶

Gtk.SearchEntry.signals.activate(search_entry)¶

Signal Name:: activate
Flags:: RUN_LAST, ACTION
Parameters:: search_entry (Gtk.SearchEntry) – The object which received the signal

Emitted when the entry is activated.

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

Gtk.SearchEntry.signals.next_match(search_entry)¶

Signal Name:: next-match
Flags:: RUN_LAST, ACTION
Parameters:: search_entry (Gtk.SearchEntry) – The object which received the signal

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

Gtk.SearchEntry.signals.previous_match(search_entry)¶

Signal Name:: previous-match
Flags:: RUN_LAST, ACTION
Parameters:: search_entry (Gtk.SearchEntry) – The object which received the signal

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 Ctrl-Shift-g.

Gtk.SearchEntry.signals.search_changed(search_entry)¶

Signal Name:: search-changed
Flags:: RUN_LAST
Parameters:: search_entry (Gtk.SearchEntry) – The object which received the signal

Emitted with a delay. The length of the delay can be changed with the [property`Gtk`.SearchEntry:search-delay] property.

Gtk.SearchEntry.signals.search_started(search_entry)¶

Signal Name:: search-started
Flags:: RUN_LAST
Parameters:: search_entry (Gtk.SearchEntry) – The object which received the signal

Emitted when the user initiated a search on the entry.

Gtk.SearchEntry.signals.stop_search(search_entry)¶

Signal Name:: stop-search
Flags:: RUN_LAST, ACTION
Parameters:: search_entry (Gtk.SearchEntry) – The object which received the signal

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

Property Details¶

Gtk.SearchEntry.props.activates_default¶

Name:: activates-default
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to activate the default widget when Enter is pressed.

Gtk.SearchEntry.props.placeholder_text¶

Name:: placeholder-text
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

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

Gtk.SearchEntry.props.search_delay¶

Name:: search-delay
Type:: int
Default Value:: 150
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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

New in version 4.8.