Gtk.SearchEntry¶

Example¶

Subclasses:	None

Methods¶

Inherited:	Gtk.Entry (76), Gtk.Widget (278), GObject.Object (37), Gtk.Buildable (10), Gtk.CellEditable (3), Gtk.Editable (13)
Structs:	Gtk.WidgetClass (12), GObject.ObjectClass (5)

class	`new` ()
	`handle_event` (event)

Virtual Methods¶

Inherited:	Gtk.Entry (13), Gtk.Widget (82), GObject.Object (7), Gtk.Buildable (10), Gtk.CellEditable (3), Gtk.Editable (10)

	`do_next_match` ()
	`do_previous_match` ()
	`do_search_changed` ()
	`do_stop_search` ()

Properties¶

Inherited:	Gtk.Entry (51), Gtk.Widget (39), Gtk.CellEditable (1)

Style Properties¶

Inherited:	Gtk.Entry (4), Gtk.Widget (17)

Signals¶

Inherited:	Gtk.Entry (14), Gtk.Widget (69), GObject.Object (1), Gtk.CellEditable (2), Gtk.Editable (3)

Name	Short Description
`next-match`	The `::next-match` signal is a `keybinding signal` which gets emitted when the user initiates a move to the next match for the current search string.
`previous-match`	The `::previous-match` signal is a `keybinding signal` which gets emitted when the user initiates a move to the previous match for the current search string.
`search-changed`	The `Gtk.SearchEntry` `::search-changed` signal is emitted with a short delay of 150 milliseconds after the last change to the entry text.
`stop-search`	The `::stop-search` signal is a `keybinding signal` which gets emitted when the user stops a search via keyboard input.

Fields¶

Inherited:	Gtk.Entry (14), Gtk.Widget (69), GObject.Object (1), Gtk.CellEditable (2), Gtk.Editable (3)

Name	Type	Access	Description
parent	`Gtk.Entry`	r

Class Details¶

class Gtk.SearchEntry(**kwargs)¶

Bases:	`Gtk.Entry`
Abstract:	No
Structure:	`Gtk.SearchEntryClass`

Gtk.SearchEntry is a subclass of Gtk.Entry that has been tailored for use as a search entry.

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.

Note that the search/clear icon is shown using a secondary icon, and thus does not work if you are using the secondary icon position for some other purpose.

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

The Gtk.SearchEntry ::previous-match, Gtk.SearchEntry ::next-match and Gtk.SearchEntry ::stop-search signals can be used to implement moving between search results and ending the search.

Often, Gtk.SearchEntry will be fed events by means of being placed inside a Gtk.SearchBar. If that is not the case, you can use Gtk.SearchEntry.handle_event() to pass events.

New in version 3.6.

classmethod new()[source]¶

Returns:	a new `Gtk.SearchEntry`
Return type:	`Gtk.Widget`

Creates a Gtk.SearchEntry, with a find icon when the search field is empty, and a clear icon when it isn’t.

New in version 3.6.

handle_event(event)[source]¶

Parameters:	event (`Gdk.Event`) – a key event
Returns:	`Gdk.EVENT_STOP` if the key press event resulted in a search beginning or continuing, `Gdk.EVENT_PROPAGATE` otherwise.
Return type:	`bool`

This function should be called when the top-level window which contains the search entry received a key event. If the entry is part of a Gtk.SearchBar, it is preferable to call Gtk.SearchBar.handle_event() instead, which will reveal the entry in addition to passing the event to this function.

If the key event is handled by the search entry and starts or continues a search, Gdk.EVENT_STOP will be returned. The caller should ensure that the entry is shown in this case, and not propagate the event further.

New in version 3.16.

do_next_match() virtual¶

do_previous_match() virtual¶

do_search_changed() virtual¶

do_stop_search() virtual¶

Signal Details¶

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

The ::next-match signal is a keybinding signal which gets emitted when the user initiates a move to the next match for the current search string.

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

The default bindings for this signal is Ctrl-g.

New in version 3.16.

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

The ::previous-match signal is a keybinding signal which gets emitted when the user initiates a move to the previous match for the current search string.

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

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

New in version 3.16.

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

The Gtk.SearchEntry ::search-changed signal is emitted with a short delay of 150 milliseconds after the last change to the entry text.

New in version 3.10.

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

The ::stop-search signal is a keybinding signal which gets emitted when the user stops a search via keyboard input.

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

The default bindings for this signal is Escape.

New in version 3.16.