
@c %start of fragment

@node GtkEntryCompletion
@chapter GtkEntryCompletion
Completion functionality for GtkEntry

@section Overview
@code{<gtk-entry-completion>} is an auxiliary object to be used in conjunction
with @code{<gtk-entry>} to provide the completion functionality. It implements
the @code{<gtk-cell-layout>} interface, to allow the user to add extra cells to
the @code{<gtk-tree-view>} with completion matches.

"Completion functionality" means that when the user modifies the text in the
entry, @code{<gtk-entry-completion>} checks which rows in the model match the
current content of the entry, and displays a list of matches. By default, the
matching is done by comparing the entry text case-insensitively against the text
column of the model (see @code{gtk-entry-completion-set-text-column}), but this
can be overridden with a custom match function (see
@code{gtk-entry-completion-set-match-func}).

When the user selects a completion, the content of the entry is updated. By
default, the content of the entry is replaced by the text column of the model,
but this can be overridden by connecting to the ::match-selected signal and
updating the entry in the signal handler. Note that you should return
@samp{@code{#t}} from the signal handler to suppress the default behaviour.

To add completion functionality to an entry, use
@code{gtk-entry-set-completion}.

In addition to regular completion matches, which will be inserted into the entry
when they are selected, @code{<gtk-entry-completion>} also allows to display
"actions" in the popup window. Their appearance is similar to menuitems, to
differentiate them clearly from completion strings. When an action is selected,
the ::action-activated signal is emitted.

@section Usage
@include defuns-gtkentrycompletion.xml.texi

@c %end of fragment
