GtkSearchEntry

GtkSearchEntry — An entry which shows a search icon

Properties

gboolean activates-default Read / Write
gchar * 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 AtkImplementorIface, GtkBuildable, GtkConstraintTarget and GtkEditable.

Includes

#include <gtk/gtk.h>

Description

GtkSearchEntry is a subclass of GtkEntry that has been tailored for use as a search entry.

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.

Note that the search/clear icon is shown using a secondary icon, and thus does not work if you are using the secondary icon position for some other purpose.

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.

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

a GtkSearchEntry

 

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

a GtkSearchEntry

 

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”         gchar *

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 *searchentry,
               gpointer        user_data)

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