Gtk.SearchEntry¶

class — extends Widget, Accessible, Buildable, ConstraintTarget, Editable

A single-line text entry widget for use as a search entry.

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

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

The SearchEntry.previous-match, SearchEntry.next-match and 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 SearchBar. If that is not the case, you can use 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 Editable API.

Shortcuts and Gestures¶

The following signals have default keybindings:

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 AccessibleRole.search_box role.

Constructors¶

new¶

@classmethod
def new(cls) -> Widget

Creates a GtkSearchEntry.

Methods¶

get_input_hints¶

def get_input_hints(self) -> InputHints

Gets the input purpose for entry.

get_input_purpose¶

def get_input_purpose(self) -> InputPurpose

Gets the input purpose of entry.

get_key_capture_widget¶

def get_key_capture_widget(self) -> Widget | None

Gets the widget that entry is capturing key events from.

get_placeholder_text¶

def get_placeholder_text(self) -> str | None

Gets the placeholder text associated with entry.

get_search_delay¶

def get_search_delay(self) -> int

Get the delay to be used between the last keypress and the SearchEntry.search-changed signal being emitted.

set_input_hints¶

def set_input_hints(self, hints: InputHints | int) -> None

Sets the input hints for entry.

Parameters:

hints — the new input hints

set_input_purpose¶

def set_input_purpose(self, purpose: InputPurpose | int) -> None

Sets the input purpose of entry.

Parameters:

purpose — the new input purpose

set_key_capture_widget¶

def set_key_capture_widget(self, widget: Widget | None = ...) -> None

Sets widget as the widget that entry 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 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 EventControllerKey.forward.

Parameters:

widget — a GtkWidget

set_placeholder_text¶

def set_placeholder_text(self, text: str | None = ...) -> None

Sets the placeholder text associated with entry.

Parameters:

text — the text to set as a placeholder

set_search_delay¶

def set_search_delay(self, delay: int) -> None

Set the delay to be used between the last keypress and the SearchEntry.search-changed signal being emitted.

Parameters:

delay — a delay in milliseconds

Properties¶

activates_default¶

activates_default: bool  # read/write

Whether to activate the default widget when Enter is pressed.

input_hints¶

input_hints: InputHints | int  # read/write

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

input_purpose¶

input_purpose: InputPurpose | int  # read/write

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

key_capture_widget¶

key_capture_widget: Widget  # read/write

The widget that the entry will use to capture key events.

Key events are consumed by the search entry to start or continue a search.

placeholder_text¶

placeholder_text: str  # read/write

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

search_delay¶

search_delay: int  # read/write

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

Signals¶

activate¶

def on_activate(self) -> None: ...

Emitted when the entry is activated.

The keybindings for this signal are all forms of the <kbd>Enter</kbd> key.

next-match¶

def on_next_match(self) -> None: ...

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

previous-match¶

def on_previous_match(self) -> None: ...

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

search-changed¶

def on_search_changed(self) -> None: ...

Emitted with a delay. The length of the delay can be changed with the SearchEntry.search-delay property.

search-started¶

def on_search_started(self) -> None: ...

Emitted when the user initiated a search on the entry.

stop-search¶

def on_stop_search(self) -> None: ...

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