Class search-entry - cl-cffi-gtk4 API documentation

Package: gtk

Class gtk:search-entry

Superclasses

gtk:widget, gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gtk:editable, gobject:object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

activates-default

The activates-default property of type :boolean (Read / Write)
Whether to activate the default widget, such as the default button in a dialog, when the Enter key is pressed.
Default value: false

input-hints

The input-hints property of type gtk:input-hints (Read / Write)
The hints about input for the search entry used to alter the behaviour of input methods. Since 4.14
Default value: :none

input-purpose

The input-purpose property of type gtk:input-purpose (Read / Write)
The purpose for the search entry input used to alter the behaviour of input methods. Since 4.14
Default value: :free-form

placeholder-text

The placeholder-text property of type :string (Read / Write)
The text that will be displayed in the text entry when it is empty and unfocused.
Default value: nil

search-delay

The search-delay property of type :uint (Read / Write)
The delay in milliseconds from last keypress to the search changed signal.
Default value: 150

Details

The gtk:search-entry widget is a text entry that has been tailored for use as a search entry. The main API for interacting with a gtk:search-entry widget as entry is the gtk:editable interface.

Figure: GtkSearchEntry

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 search entry text immediately, but only after a short delay. To support this, the gtk:search-entry widget emits the "search-changed" signal which can be used instead of the "changed" signal.

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

Often, the gtk:search-entry widget will be fed events by means of being placed inside a gtk:search-bar widget. If that is not the case, you can use the gtk:search-entry-key-capture-widget function to let it capture key input from another widget.

CSS Nodes

entry.search
╰── text

The gtk:search-entry implementation has a single CSS node with name entry that carries a .search style class, and the text node is a child of that.

Accessibility

The gtk:search-entry implementation uses the :search-box role of the gtk:accessible-role enumeration.

Signal Details

The "activate" signal

lambda (entry)    :action

entry: The gtk:search-entry widget on which the signal is emitted.

The signal is forwarded from the "activated" signal, which is a keybinding signal for all forms of the Enter key.

The "next-match" signal

lambda (entry)    :action

entry: The gtk:search-entry widget on which the signal is emitted.

The 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 the Ctrl-g key.

The "previous-match" signal

lambda (entry)    :action

entry: The gtk:search-entry widget on which the signal is emitted.

The 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 the Ctrl-Shift-g key.

The "search-changed" signal

lambda (entry)    :run-last

entry: The gtk:search-entry widget on which the signal is emitted.

The signal is emitted with a short delay of 150 milliseconds after the last change to the text entry.

The "stop-search" signal

lambda (entry)    :action

entry: The gtk:search-entry widget on which the signal is emitted.

The 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 the Escape key.