GtkSearchEntry

GtkSearchEntry — An entry which shows a search icon

Functions

GtkWidget * gtk_search_entry_new ()
gboolean gtk_search_entry_handle_event ()

Signals

void next-match Action
void previous-match Action
void search-changed Run Last
void stop-search Action

Types and Values

struct GtkSearchEntry

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkEntry
                ╰── GtkSearchEntry

Implemented Interfaces

GtkSearchEntry implements AtkImplementorIface, GtkBuildable, GtkEditable and GtkCellEditable.

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_handle_event() to pass events.

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

Since: 3.6

gtk_search_entry_handle_event ()

gboolean
gtk_search_entry_handle_event (GtkSearchEntry *entry,
                               GdkEvent *event);

This function should be called when the top-level window which contains the search entry received a key event. If the entry is part of a GtkSearchBar, it is preferable to call gtk_search_bar_handle_event() instead, which will reveal the entry in addition to passing the event to this function.

If the key event is handled by the search entry and starts or continues a search, GDK_EVENT_STOP will be returned. The caller should ensure that the entry is shown in this case, and not propagate the event further.

Parameters

entry

a GtkSearchEntry

event

a key event

Returns

GDK_EVENT_STOP if the key press event resulted in a search beginning or continuing, GDK_EVENT_PROPAGATE otherwise.

Since: 3.16

Types and Values

struct GtkSearchEntry

struct GtkSearchEntry;

Signal Details

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

Since: 3.16

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

Since: 3.16

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

Since: 3.10

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

Since: 3.16

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk3/3.24/GtkSearchEntry.html