Gtk.SearchEntry

g Atk.ImplementorIface Atk.ImplementorIface Gtk.Widget Gtk.Widget Atk.ImplementorIface->Gtk.Widget GObject.GInterface GObject.GInterface GObject.GInterface->Atk.ImplementorIface Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable Gtk.CellEditable Gtk.CellEditable GObject.GInterface->Gtk.CellEditable Gtk.Editable Gtk.Editable GObject.GInterface->Gtk.Editable GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Gtk.Widget GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gtk.Buildable->Gtk.Widget Gtk.Entry Gtk.Entry Gtk.CellEditable->Gtk.Entry Gtk.Editable->Gtk.Entry Gtk.SearchEntry Gtk.SearchEntry Gtk.Entry->Gtk.SearchEntry Gtk.Widget->Gtk.Entry

Example

../_images/SearchEntry.png
Subclasses:None

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.

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

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.

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.