## GtkSearchEntry GtkSearchEntry — An entry which shows a search icon |

## Functions

GtkWidget * | gtk_search_entry_new ()
void | gtk_search_entry_set_key_capture_widget ()
GtkWidget * | gtk_search_entry_get_key_capture_widget ()

## 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

| GtkSearchEntry

## 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