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

| GtkSearchEntry

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

    1
    2
    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.

Note that despite the name of this function, the events are only 'captured' in the bubble phase, which means that editable child widgets of `widget` will receive text input before it gets captured. If that is not desired, you can capture and forward the events yourself with `gtk_event_controller_key_forward()`.

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