Gtk.SearchEntry

Example

Subclasses:

None

Methods

Inherited:

Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (16), Gtk.Buildable (1), Gtk.Editable (27)

Structs:

Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	new ()
	get_input_hints ()
	get_input_purpose ()
	get_key_capture_widget ()
	get_placeholder_text ()
	get_search_delay ()
	set_input_hints (hints)
	set_input_purpose (purpose)
	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	Short Description
activates-default	bool	r/w/en
input-hints	Gtk.InputHints	r/w/en
input-purpose	Gtk.InputPurpose	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.

Shortcuts and Gestures

The following signals have default keybindings:

• [signal`Gtk`.SearchEntry::activate]

• [signal`Gtk`.SearchEntry::next-match]

• [signal`Gtk`.SearchEntry::previous-match]

• [signal`Gtk`.SearchEntry::stop-search]

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()

Returns:

a new GtkSearchEntry

Return type:

Gtk.Widget

Creates a GtkSearchEntry.

get_input_hints()

Returns:

The input hints

Return type:

Gtk.InputHints

Gets the input purpose for self.

New in version 4.14.

get_input_purpose()

Returns:

The input hints

Return type:

Gtk.InputPurpose

Gets the input purpose of self.

New in version 4.14.

get_key_capture_widget()

Returns:

The key capture widget.

Return type:

Gtk.Widget or None

Gets the widget that self is capturing key events from.

get_placeholder_text()

Returns:

The placeholder text.

Return type:

str or None

Gets the placeholder text associated with self.

New in version 4.10.

get_search_delay()

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_input_hints(hints)

Parameters:

hints (Gtk.InputHints) – the new input hints

Sets the input hints for self.

New in version 4.14.

set_input_purpose(purpose)

Parameters:

purpose (Gtk.InputPurpose) – the new input purpose

Sets the input purpose of self.

New in version 4.14.

set_key_capture_widget(widget)

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)

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)

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 <kbd>Enter</kbd> 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 <kbd>Ctrl</kbd>+<kbd>g</kbd>.

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

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

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

Name:

input-hints

Type:

Gtk.InputHints

Default Value:

Gtk.InputHints.NONE

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The hints about input for the GtkSearchEntry used to alter the behaviour of input methods.

New in version 4.14.

Gtk.SearchEntry.props.input_purpose

Name:

input-purpose

Type:

Gtk.InputPurpose

Default Value:

Gtk.InputPurpose.FREE_FORM

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The purpose for the GtkSearchEntry input used to alter the behaviour of input methods.

New in version 4.14.

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.