forked from AuroraMiddleware/gtk
927 lines
13 KiB
Plaintext
927 lines
13 KiB
Plaintext
<!-- ##### 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::toggle-overwrite ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry: the object which received the signal.
|
|
|
|
<!-- ##### ARG GtkEntry:activatable-primary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:activatable-secondary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:activates-default ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:caps-lock-warning ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:cursor-position ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:editable ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:gicon-primary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:gicon-secondary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:has-frame ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:icon-name-primary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:icon-name-secondary ##### -->
|
|
<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:pixbuf-primary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:pixbuf-secondary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:progress-fraction ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:progress-pulse-step ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:scroll-offset ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:selection-bound ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:sensitive-primary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:sensitive-secondary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:shadow-type ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:stock-primary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:stock-secondary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:storage-type-primary ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:storage-type-secondary ##### -->
|
|
<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:inner-border ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:prelight ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkEntry:state-hint ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### FUNCTION gtk_entry_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_new_with_max_length ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@max:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_set_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@text:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_append_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@text:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_prepend_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@text:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_set_position ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@position:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_get_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_get_text_length ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_select_region ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@start:
|
|
@end:
|
|
|
|
|
|
<!-- ##### 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_editable ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@editable:
|
|
|
|
|
|
<!-- ##### 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_storage_type ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@icon_pos:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_get_pixbuf ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@icon_pos:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_get_stock ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@icon_pos:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_get_icon_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@icon_pos:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_entry_get_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_set_icon_tooltip_markup ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@entry:
|
|
@icon_pos:
|
|
@tooltip:
|
|
|
|
|
|
<!-- ##### 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:
|
|
|
|
|