Gnome::Gtk4::SearchEntry

Table of Contents
Description

CSS Nodes
Accessibility
Class initialization
new
:native-object
new-searchentry
Methods
get-input-hints
get-input-purpose
get-key-capture-widget
get-placeholder-text
get-search-delay
set-input-hints
set-input-purpose
set-key-capture-widget
set-placeholder-text
set-search-delay
Signals
activate
next-match
previous-match
search-changed
search-started
stop-search

Description

Gnome::Gtk4::SearchEntry is an entry widget that has been tailored for use as a search entry.

The main API for interacting with a Gnome::Gtk4::SearchEntry as entry is the Gnome::Gtk4::R-Editable 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, Gnome::Gtk4::SearchEntry emits the search-changed signal which can be used instead of the changed defined in Editable signal.

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

Often, Gnome::Gtk4::SearchEntry will be fed events by means of being placed inside a Gnome::Gtk4::SearchBar. If that is not the case, you can use .set-key-capture-widget() to let it capture key input from another widget.

Gnome::Gtk4::SearchEntry provides only minimal API and should be used with the Gnome::Gtk4::R-Editable API.

CSS Nodes

Gnome::Gtk4::SearchEntry has a single CSS node with name entry that carries a `.search` style class, and the text node is a child of that.

Accessibility

Gnome::Gtk4::SearchEntry uses the GTK_ACCESSIBLE_ROLE_SEARCH_BOX role.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-searchentry

Creates a Gnome::Gtk4::SearchEntry.

method new-searchentry ( --> Gnome::Gtk4::SearchEntry \)

Methods

get-input-hints

Gets the input purpose for $entry.

method get-input-hints (--> UInt )

Return value; The input hints.

get-input-purpose

Gets the input purpose of $entry.

method get-input-purpose (--> GtkInputPurpose )

Return value; The input hints.

Gets the widget that $entry is capturing key events from.

method get-key-capture-widget (--> N-Object )

Return value; The key capture widget..

get-placeholder-text

Gets the placeholder text associated with $entry.

method get-placeholder-text (--> Str )

Return value; The placeholder text..

get-search-delay

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

method get-search-delay (--> UInt )

Return value; a delay in milliseconds..

set-input-hints

Sets the input hints for $entry.

method set-input-hints ( UInt $hints )

$hints; the new input hints.

set-input-purpose

Sets the input purpose of $entry.

method set-input-purpose ( GtkInputPurpose $purpose )

$purpose; the new input purpose.

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 Gnome::Gtk4::SearchBar, it is preferable to call .set-key-capture-widget() in class Gnome::Gtk4::SearchBar 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 .forward() in class Gnome::Gtk4::EventControllerKey.

method set-key-capture-widget ( N-Object() $widget )

$widget; a Gnome::Gtk4::Widget.

set-placeholder-text

Sets the placeholder text associated with $entry.

method set-placeholder-text ( Str $text )

$text; the text to set as a placeholder.

set-search-delay

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

method set-search-delay ( UInt() $delay )

$delay; a delay in milliseconds.

Signals

activate

Emitted when the entry is activated.

The keybindings for this signal are all forms of the Enter key.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::SearchEntry :$_widget,
  *C<user>-options
)

$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::SearchEntry object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

next-match

Emitted when the user initiates a move to the next match for the current search string.

This is a [keybinding signal](class.SignalAction.html).

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

The default bindings for this signal is Ctrl-g.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::SearchEntry :$_widget,
  *C<user>-options
)

$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::SearchEntry object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

previous-match

Emitted when the user initiates a move to the previous match for the current search string.

This is a [keybinding signal](class.SignalAction.html).

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

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

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::SearchEntry :$_widget,
  *C<user>-options
)

$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::SearchEntry object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

search-changed

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

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::SearchEntry :$_widget,
  *C<user>-options
)

$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::SearchEntry object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

search-started

Emitted when the user initiated a search on the entry.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::SearchEntry :$_widget,
  *C<user>-options
)

$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::SearchEntry object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

stop-search

Emitted when the user stops a search via keyboard input.

This is a [keybinding signal](class.SignalAction.html).

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

The default bindings for this signal is Escape.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::SearchEntry :$_widget,
  *C<user>-options
)

$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::SearchEntry object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.