GtkSearchEntry
GtkSearchEntry — An entry which shows a search icon
Functions
Properties
| gboolean | activates-default | Read / Write |
| char * | placeholder-text | Read / Write |
Signals
| void | activate | Action |
| void | next-match | Action |
| void | previous-match | Action |
| void | search-changed | Run Last |
| void | search-started | Run Last |
| void | stop-search | Action |
Types and Values
Object Hierarchy
GObject
╰── GInitiallyUnowned
╰── GtkWidget
╰── GtkSearchEntry
Implemented Interfaces
GtkSearchEntry implements GtkAccessible, GtkBuildable, GtkConstraintTarget and GtkEditable.
Includes
#include <gtk/gtk.h>
Description
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.
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 “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, GtkSearchEntry will be fed events by means of being placed inside a GtkSearchBar. If that is not the case, you can use gtk_search_entry_set_key_capture_widget() to let it capture key input from another widget.
CSS Nodes
entry.search ╰── text
GtkSearchEntry has a single CSS node with name entry that carries a .sarch style class, and the text node is a child of that.
Accessibility
GtkSearchEntry uses the GTK_ACCESSIBLE_ROLE_SEARCH_BOX role.
Functions
gtk_search_entry_new ()
GtkWidget *
gtk_search_entry_new (void); Creates a GtkSearchEntry, with a find icon when the search field is empty, and a clear icon when it isn't.
Returns
a new GtkSearchEntry
gtk_search_entry_set_key_capture_widget ()
void gtk_search_entry_set_key_capture_widget (GtkSearchEntry *entry,GtkWidget *widget);
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 gtk_search_bar_set_key_capture_widget() instead, which will reveal the entry in addition to triggering the search entry.
Parameters
entry | ||
widget | a GtkWidget. | [nullable][transfer none] |
gtk_search_entry_get_key_capture_widget ()
GtkWidget *
gtk_search_entry_get_key_capture_widget
(GtkSearchEntry *entry); Gets the widget that entry is capturing key events from.
Parameters
entry |
Returns
The key capture widget.
[transfer none]
Types and Values
GtkSearchEntry
typedef struct _GtkSearchEntry GtkSearchEntry;
Property Details
The “activates-default” property
“activates-default” gboolean
Whether to activate the default widget (such as the default button in a dialog) when Enter is pressed.
Owner: GtkSearchEntry
Flags: Read / Write
Default value: FALSE
The “placeholder-text” property
“placeholder-text” char *
Show text in the entry when it’s empty and unfocused.
Owner: GtkSearchEntry
Flags: Read / Write
Default value: NULL
Signal Details
The “activate” signal
void user_function (GtkSearchEntry *self, gpointer user_data)
The ::activate signal is forwarded from the “activated” signal, which is a keybinding signal for all forms of the Enter key.
Parameters
self | The widget on which the signal is emitted | |
user_data | user data set when the signal handler was connected. |
Flags: Action
The “next-match” signal
void user_function (GtkSearchEntry *entry, gpointer user_data)
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.
Parameters
entry | the entry on which the signal was emitted | |
user_data | user data set when the signal handler was connected. |
Flags: Action
The “previous-match” signal
void user_function (GtkSearchEntry *entry, gpointer user_data)
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.
Parameters
entry | the entry on which the signal was emitted | |
user_data | user data set when the signal handler was connected. |
Flags: Action
The “search-changed” signal
void user_function (GtkSearchEntry *entry, gpointer user_data)
The “search-changed” signal is emitted with a short delay of 150 milliseconds after the last change to the entry text.
Parameters
entry | the entry on which the signal was emitted | |
user_data | user data set when the signal handler was connected. |
Flags: Run Last
The “search-started” signal
void user_function (GtkSearchEntry *entry, gpointer user_data)
The ::search-started signal gets emitted when the user initiated a search on the entry.
Parameters
entry | the entry on which the signal was emitted | |
user_data | user data set when the signal handler was connected. |
Flags: Run Last
The “stop-search” signal
void user_function (GtkSearchEntry *entry, gpointer user_data)
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.
Parameters
entry | the entry on which the signal was emitted | |
user_data | user data set when the signal handler was connected. |
Flags: Action
© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk4/4.0/GtkSearchEntry.html