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

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

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.