[~andy/gtk] / docs / reference / gtk / tmpl / gtkentry.sgml

<!-- ##### SECTION Title ##### -->
GtkEntry

<!-- ##### SECTION Short_Description ##### -->
A single line text entry field

<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkEntry widget is a single line text entry
widget. A fairly large set of key bindings are supported
by default. If the entered text is longer than the allocation
of the widget, the widget will scroll so that the cursor
position is visible. 
</para>
<para>
When using an entry for passwords and other sensitive information,
it can be put into "password mode" using gtk_entry_set_visibility(). 
In this mode, entered text is displayed using a 'invisible' character.
By default, GTK+ picks the best invisible character that is available
in the current font, but it can be changed with 
gtk_entry_set_invisible_char(). Since 2.16, GTK+ displays a warning
when Caps Lock or input methods might interfere with entering text in
a password entry. The warning can be turned off with the 
#GtkEntry::caps-lock-warning property.
</para>
<para>
Since 2.16, GtkEntry has the ability to display progress or activity 
information behind the text. To make an entry display such information, 
use gtk_entry_set_progress_fraction() or gtk_entry_set_progress_pulse_step().
</para>
<para>
Additionally, GtkEntry can show icons at either side of the entry. These
icons can be activatable by clicking, can be set up as drag source and
can have tooltips. To add an icon, use gtk_entry_set_icon_from_gicon() or
one of the various other functions that set an icon from a stock id, an
icon name or a pixbuf. To trigger an action when the user clicks an icon,
connect to the #GtkEntry::icon-press signal. To allow DND operations
from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on 
an icon, use gtk_entry_set_icon_tooltip_text() or the corresponding function
for markup.
</para>
<para>
Note that functionality or information that is only available by clicking 
on an icon in an entry may not be accessible at all to users which are not 
able to use a mouse or other pointing device. It is therefore recommended 
that any such functionality should also be available by other means, e.g. 
via the context menu of the entry.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>

<varlistentry>
<term>#GtkTextView</term>
<listitem><para>a widget for handling multi-line text entry.</para></listitem>
</varlistentry>

<varlistentry>
<term>#GtkEntryCompletion</term>
<listitem><para>adds completion functionality to GtkEntry.</para></listitem>
</varlistentry>

</variablelist>
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GtkEntry ##### -->
<para>
The #GtkEntry-struct struct contains only private data.
</para>


<!-- ##### SIGNAL GtkEntry::activate ##### -->
<para>

</para>

@entry: the object which received the signal.

<!-- ##### SIGNAL GtkEntry::backspace ##### -->
<para>

</para>

@entry: the object which received the signal.

<!-- ##### SIGNAL GtkEntry::copy-clipboard ##### -->
<para>

</para>

@entry: the object which received the signal.

<!-- ##### SIGNAL GtkEntry::cut-clipboard ##### -->
<para>

</para>

@entry: the object which received the signal.

<!-- ##### SIGNAL GtkEntry::delete-from-cursor ##### -->
<para>

</para>

@entry: the object which received the signal.
@arg1: 
@arg2: 

<!-- ##### SIGNAL GtkEntry::icon-press ##### -->
<para>

</para>

@entry: the object which received the signal.
@arg1: 
@event: 

<!-- ##### SIGNAL GtkEntry::icon-release ##### -->
<para>

</para>

@entry: the object which received the signal.
@arg1: 
@event: 

<!-- ##### SIGNAL GtkEntry::insert-at-cursor ##### -->
<para>

</para>

@entry: the object which received the signal.
@arg1: 

<!-- ##### SIGNAL GtkEntry::move-cursor ##### -->
<para>

</para>

@entry: the object which received the signal.
@arg1: 
@arg2: 
@arg3: 

<!-- ##### SIGNAL GtkEntry::paste-clipboard ##### -->
<para>

</para>

@entry: the object which received the signal.

<!-- ##### SIGNAL GtkEntry::populate-popup ##### -->
<para>

</para>

@entry: the object which received the signal.
@arg1: 

<!-- ##### SIGNAL GtkEntry::preedit-changed ##### -->
<para>

</para>

@entry: the object which received the signal.
@arg1: 

<!-- ##### SIGNAL GtkEntry::toggle-overwrite ##### -->
<para>

</para>

@entry: the object which received the signal.

<!-- ##### ARG GtkEntry:activates-default ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:buffer ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:caps-lock-warning ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:cursor-position ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:editable ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:has-frame ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:im-module ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:inner-border ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:invisible-char ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:invisible-char-set ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:max-length ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:overwrite-mode ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-activatable ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-gicon ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-name ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-pixbuf ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-sensitive ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-stock ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-storage-type ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-tooltip-markup ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:primary-icon-tooltip-text ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:progress-fraction ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:progress-pulse-step ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:scroll-offset ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-activatable ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-gicon ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-name ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-pixbuf ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-sensitive ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-stock ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-storage-type ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-tooltip-markup ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:secondary-icon-tooltip-text ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:selection-bound ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:shadow-type ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:text ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:text-length ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:truncate-multiline ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:visibility ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:width-chars ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:xalign ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:icon-prelight ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:inner-border ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:invisible-char ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:progress-border ##### -->
<para>

</para>

<!-- ##### ARG GtkEntry:state-hint ##### -->
<para>

</para>

<!-- ##### FUNCTION gtk_entry_new ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_entry_new_with_buffer ##### -->
<para>

</para>

@buffer: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_buffer ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_buffer ##### -->
<para>

</para>

@entry: 
@buffer: 


<!-- ##### FUNCTION gtk_entry_set_text ##### -->
<para>

</para>

@entry: 
@text: 


<!-- ##### FUNCTION gtk_entry_get_text ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_text_length ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_visibility ##### -->
<para>

</para>

@entry: 
@visible: 


<!-- ##### FUNCTION gtk_entry_set_invisible_char ##### -->
<para>

</para>

@entry: 
@ch: 


<!-- ##### FUNCTION gtk_entry_unset_invisible_char ##### -->
<para>

</para>

@entry: 


<!-- ##### FUNCTION gtk_entry_set_max_length ##### -->
<para>
</para>

@entry: 
@max: 


<!-- ##### FUNCTION gtk_entry_get_activates_default ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_has_frame ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_inner_border ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_width_chars ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_activates_default ##### -->
<para>

</para>

@entry: 
@setting: 


<!-- ##### FUNCTION gtk_entry_set_has_frame ##### -->
<para>

</para>

@entry: 
@setting: 


<!-- ##### FUNCTION gtk_entry_set_inner_border ##### -->
<para>

</para>

@entry: 
@border: 


<!-- ##### FUNCTION gtk_entry_set_width_chars ##### -->
<para>

</para>

@entry: 
@n_chars: 


<!-- ##### FUNCTION gtk_entry_get_invisible_char ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_alignment ##### -->
<para>

</para>

@entry: 
@xalign: 


<!-- ##### FUNCTION gtk_entry_get_alignment ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_overwrite_mode ##### -->
<para>

</para>

@entry: 
@overwrite: 


<!-- ##### FUNCTION gtk_entry_get_overwrite_mode ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_layout ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_layout_offsets ##### -->
<para>

</para>

@entry: 
@x: 
@y: 


<!-- ##### FUNCTION gtk_entry_layout_index_to_text_index ##### -->
<para>

</para>

@entry: 
@layout_index: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_text_index_to_layout_index ##### -->
<para>

</para>

@entry: 
@text_index: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_max_length ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_visibility ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_completion ##### -->
<para>

</para>

@entry: 
@completion: 


<!-- ##### FUNCTION gtk_entry_get_completion ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_cursor_hadjustment ##### -->
<para>

</para>

@entry: 
@adjustment: 


<!-- ##### FUNCTION gtk_entry_get_cursor_hadjustment ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_progress_fraction ##### -->
<para>

</para>

@entry: 
@fraction: 


<!-- ##### FUNCTION gtk_entry_get_progress_fraction ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_progress_pulse_step ##### -->
<para>

</para>

@entry: 
@fraction: 


<!-- ##### FUNCTION gtk_entry_get_progress_pulse_step ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_progress_pulse ##### -->
<para>

</para>

@entry: 


<!-- ##### ENUM GtkEntryIconPosition ##### -->
<para>
Specifies the side of the entry at which an icon is placed.
</para>

@GTK_ENTRY_ICON_PRIMARY: At the beginning of the entry (depending on the text direction).
@GTK_ENTRY_ICON_SECONDARY: At the end of the entry (depending on the text direction).

<!-- ##### FUNCTION gtk_entry_set_icon_from_pixbuf ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@pixbuf: 


<!-- ##### FUNCTION gtk_entry_set_icon_from_stock ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@stock_id: 


<!-- ##### FUNCTION gtk_entry_set_icon_from_icon_name ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@icon_name: 


<!-- ##### FUNCTION gtk_entry_set_icon_from_gicon ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@icon: 


<!-- ##### FUNCTION gtk_entry_get_icon_storage_type ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_icon_pixbuf ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_icon_stock ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_icon_name ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_icon_gicon ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_icon_activatable ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@activatable: 


<!-- ##### FUNCTION gtk_entry_get_icon_activatable ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_icon_sensitive ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@sensitive: 


<!-- ##### FUNCTION gtk_entry_get_icon_sensitive ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_icon_at_pos ##### -->
<para>

</para>

@entry: 
@x: 
@y: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_icon_tooltip_text ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@tooltip: 


<!-- ##### FUNCTION gtk_entry_get_icon_tooltip_text ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_icon_tooltip_markup ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@tooltip: 


<!-- ##### FUNCTION gtk_entry_get_icon_tooltip_markup ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_set_icon_drag_source ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@target_list: 
@actions: 


<!-- ##### FUNCTION gtk_entry_get_current_icon_drag_source ##### -->
<para>

</para>

@entry: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_icon_window ##### -->
<para>

</para>

@entry: 
@icon_pos: 
@Returns: 


<!-- ##### FUNCTION gtk_entry_get_text_window ##### -->
<para>

</para>

@entry: 
@Returns: