`GtkEntry` 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.
When using an entry for passwords and other sensitive information, it can be put into “password mode” using [
[email protected]_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 [[email protected]_invisible_char].
`GtkEntry` has the ability to display progress or activity information behind the text. To make an entry display such information, use [
[email protected]_progress_fraction] or [[email protected]_progress_pulse_step].
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 [[email protected]_icon_from_gicon] or one of the various other functions that set an
icon from an icon name or a paintable. To trigger an action when the user clicks an icon, connect to the [[email protected]:
GtkEntry:icon-presss] signal. To allow DND operations from an icon, use [[email protected]_icon_drag_source]. To set a tooltip
on an icon, use [[email protected]_icon_tooltip_text] or the corresponding function for markup.
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.
CSS nodes
``` entry.flat[.error] ├── text[.readonly] ├── image.left ├── image.right ╰── [progress[.pulse]] ```
`GtkEntry` has a main node with the name entry. Depending on the properties of the entry, the style classes .read-only and .flat may
appear. The style classes .warning and .error may also be used with entries.
When the entry shows icons, it adds subnodes with the name image and the style class .left or .right, depending on where the icon
appears.
When the entry shows progress, it adds a subnode with the name progress. The node has the style class .pulse when the shown progress is
pulsing.
For all the subnodes added to the text node in various situations, see [[email protected]].
GtkEntry as GtkBuildable
The `GtkEntry` implementation of the `GtkBuildable` interface supports a custom <attributes> element, which supports any number of
<attribute> elements. The <attribute> element has attributes named “name“, “value“, “start“ and “end“ and
allows you to specify `PangoAttribute` values for this label.
An example of a UI definition fragment specifying Pango attributes: ```xml <object class="GtkEntry"> <attributes> <
attribute name="weight" value="PANGO_WEIGHT_BOLD"/> <attribute name="background" value="red" start="5" end="10"/> <
/attributes> </object> ```
The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified,
the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup
embedded in the translatable content instead.
Accessibility
`GtkEntry` uses the gtk_accessible_role_text_box role.
- public bool activates_default { get; set; }
Whether to activate the default widget when Enter is pressed.
- public AttrList attributes { get; set; }
A list of Pango attributes to apply to the text of the entry.
- public EntryBuffer buffer { get; set construct; }
The buffer object which actually stores the text.
- public EntryCompletion completion { get; set; }
The auxiliary completion object to use with the entry.
- public bool enable_emoji_completion { get; set; }
Whether to suggest Emoji replacements for :-delimited names like `
GtkEntry:heart:`.
- public MenuModel extra_menu { get; set; }
A menu model whose contents will be appended to the context menu.
- public bool has_frame { get; set; }
Whehter the entry should draw a frame.
- public string im_module { owned get; set; }
Which IM (input method) module should be used for this entry.
- public InputHints input_hints { get; set; }
Additional hints that allow input methods to fine-tune their behavior.
- public InputPurpose input_purpose { get; set; }
The purpose of this text field.
- public uint invisible_char { get; set; }
The character to use when masking entry contents (“password mode”)
.
- public bool invisible_char_set { get; set; }
Whether the invisible char has been set for the `GtkEntry`.
- public int max_length { get; set; }
Maximum number of characters for this entry.
- public bool overwrite_mode { get; set; }
If text is overwritten when typing in the `GtkEntry`.
- public string placeholder_text { get; set; }
The text that will be displayed in the `GtkEntry` when it is empty and
unfocused.
- public bool primary_icon_activatable { get; set; }
Whether the primary icon is activatable.
- public Icon primary_icon_gicon { owned get; set; }
The `GIcon` to use for the primary icon for the entry.
- public string primary_icon_name { owned get; set; }
The icon name to use for the primary icon for the entry.
- public Paintable primary_icon_paintable { owned get; set; }
A `GdkPaintable` to use as the primary icon for the entry.
- public bool primary_icon_sensitive { get; set; }
Whether the primary icon is sensitive.
- public ImageType primary_icon_storage_type { get; }
The representation which is used for the primary icon of the entry.
- public string primary_icon_tooltip_markup { owned get; set; }
The contents of the tooltip on the primary icon, with markup.
- public string primary_icon_tooltip_text { owned get; set; }
The contents of the tooltip on the primary icon.
- public double progress_fraction { get; set; }
The current fraction of the task that's been completed.
- public double progress_pulse_step { get; set; }
The fraction of total entry width to move the progress bouncing block
for each pulse.
- public int scroll_offset { get; }
Number of pixels of the entry scrolled off the screen to the left.
- public bool secondary_icon_activatable { get; set; }
Whether the secondary icon is activatable.
- public Icon secondary_icon_gicon { owned get; set; }
The `GIcon` to use for the secondary icon for the entry.
- public string secondary_icon_name { owned get; set; }
The icon name to use for the secondary icon for the entry.
- public Paintable secondary_icon_paintable { owned get; set; }
A `GdkPaintable` to use as the secondary icon for the entry.
- public bool secondary_icon_sensitive { get; set; }
Whether the secondary icon is sensitive.
- public ImageType secondary_icon_storage_type { get; }
The representation which is used for the secondary icon of the entry.
- public string secondary_icon_tooltip_markup { owned get; set; }
The contents of the tooltip on the secondary icon, with markup.
- public string secondary_icon_tooltip_text { owned get; set; }
The contents of the tooltip on the secondary icon.
- public bool show_emoji_icon { get; set; }
- public TabArray tabs { get; set; }
- public uint text_length { get; }
The length of the text in the `GtkEntry`.
- public bool truncate_multiline { get; set; }
When true, pasted multi-line text is
truncated to the first line.
- public bool visibility { get; set; }
Whether the entry should show the “invisible char” instead of the
actual text (“password mode”).
- public bool get_activates_default ()
- public float get_alignment ()
- public unowned AttrList? get_attributes ()
Gets the attribute list of the `GtkEntry`.
- public unowned EntryBuffer get_buffer ()
Get the `GtkEntryBuffer` object which holds the text for this widget.
- public unowned EntryCompletion? get_completion ()
Returns the auxiliary completion object currently in use by
this.
- public int get_current_icon_drag_source ()
Returns the index of the icon which is the source of the current DND
operation, or -1.
- public unowned MenuModel? get_extra_menu ()
- public bool get_has_frame ()
- public bool get_icon_activatable (EntryIconPosition icon_pos)
Returns whether the icon is activatable.
- public Rectangle get_icon_area (EntryIconPosition icon_pos)
Gets the area where entry’s icon at icon_pos is drawn.
- public int get_icon_at_pos (int x, int y)
Finds the icon at the given position and return its index.
- public unowned Icon? get_icon_gicon (EntryIconPosition icon_pos)
Retrieves the `GIcon` used for the icon.
- public unowned string? get_icon_name (EntryIconPosition icon_pos)
Retrieves the icon name used for the icon.
- public unowned Paintable? get_icon_paintable (EntryIconPosition icon_pos)
Retrieves the `GdkPaintable` used for the icon.
- public bool get_icon_sensitive (EntryIconPosition icon_pos)
Returns whether the icon appears sensitive or insensitive.
- public ImageType get_icon_storage_type (EntryIconPosition icon_pos)
Gets the type of representation being used by the icon to store image
data.
- public string? get_icon_tooltip_markup (EntryIconPosition icon_pos)
Gets the contents of the tooltip on the icon at the specified position
in this.
- public string? get_icon_tooltip_text (EntryIconPosition icon_pos)
Gets the contents of the tooltip on the icon at the specified position
in this.
- public InputHints get_input_hints ()
Gets the input hints of this `GtkEntry`.
- public InputPurpose get_input_purpose ()
Gets the input purpose of the `GtkEntry`.
- public unichar get_invisible_char ()
Retrieves the character displayed in place of the actual text in
“password mode”.
- public int get_max_length ()
Retrieves the maximum allowed length of the text in
this.
- public bool get_overwrite_mode ()
Gets whether the `GtkEntry` is in overwrite mode.
- public unowned string? get_placeholder_text ()
Retrieves the text that will be displayed when
this is empty and unfocused
- public double get_progress_fraction ()
Returns the current fraction of the task that’s been completed.
- public double get_progress_pulse_step ()
- public unowned TabArray? get_tabs ()
Gets the tabstops of the `GtkEntry.
- public uint16 get_text_length ()
Retrieves the current length of the text in
this.
- public bool get_visibility ()
Retrieves whether the text in this
is visible.
- public bool grab_focus_without_selecting ()
Causes this to have keyboard focus.
- public void progress_pulse ()
Indicates that some progress is made, but you don’t know how much.
- public void reset_im_context ()
Reset the input method context of the entry if needed.
- public void set_activates_default (bool setting)
Sets whether pressing Enter in the this
will activate the default widget for the window containing the entry.
- public void set_alignment (float xalign)
Sets the alignment for the contents of the entry.
- public void set_attributes (AttrList attrs)
Sets a `PangoAttrList`.
- public void set_buffer (EntryBuffer buffer)
Set the `GtkEntryBuffer` object which holds the text for this widget.
- public void set_completion (EntryCompletion? completion)
Sets completion to be the auxiliary completion object to
use with this.
- public void set_extra_menu (MenuModel? model)
Sets a menu model to add when constructing the context menu for
this.
- public void set_has_frame (bool setting)
Sets whether the entry has a beveled frame around it.
- public void set_icon_activatable (EntryIconPosition icon_pos, bool activatable)
Sets whether the icon is activatable.
- public void set_icon_drag_source (EntryIconPosition icon_pos, ContentProvider provider, DragAction actions)
Sets up the icon at the given position as drag source.
- public void set_icon_from_gicon (EntryIconPosition icon_pos, Icon? icon)
Sets the icon shown in the entry at the specified position from the
current icon theme.
- public void set_icon_from_icon_name (EntryIconPosition icon_pos, string? icon_name)
Sets the icon shown in the entry at the specified position from the
current icon theme.
- public void set_icon_from_paintable (EntryIconPosition icon_pos, Paintable? paintable)
Sets the icon shown in the specified position using a `GdkPaintable`.
- public void set_icon_sensitive (EntryIconPosition icon_pos, bool sensitive)
Sets the sensitivity for the specified icon.
- public void set_icon_tooltip_markup (EntryIconPosition icon_pos, string? tooltip)
Sets tooltip as the contents of the tooltip for the icon
at the specified position.
- public void set_icon_tooltip_text (EntryIconPosition icon_pos, string? tooltip)
Sets tooltip as the contents of the tooltip for the icon
at the specified position.
- public void set_input_hints (InputHints hints)
Set additional hints which allow input methods to fine-tune their
behavior.
- public void set_input_purpose (InputPurpose purpose)
Sets the input purpose which can be used by input methods to adjust
their behavior.
- public void set_invisible_char (unichar ch)
Sets the character to use in place of the actual text in “password
mode”.
- public void set_max_length (int max)
Sets the maximum allowed length of the contents of the widget.
- public void set_overwrite_mode (bool overwrite)
Sets whether the text is overwritten when typing in the `GtkEntry`.
- public void set_placeholder_text (string? text)
Sets text to be displayed in this
when it is empty.
- public void set_progress_fraction (double fraction)
Causes the entry’s progress indicator to “fill in” the given
fraction of the bar.
- public void set_progress_pulse_step (double fraction)
Sets the fraction of total entry width to move the progress bouncing
block for each pulse.
- public void set_tabs (TabArray? tabs)
Sets a `PangoTabArray`.
- public void set_visibility (bool visible)
Sets whether the contents of the entry are visible or not.
- public void unset_invisible_char ()
Unsets the invisible char, so that the default invisible char is used
again.