Class Entry

All Implemented Interfaces:
PointerInterface

public class Entry extends Widget
`GtkEntry` is a single line text entry widget.

![An example GtkEntry](entry.png)

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 [method@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
[method@Gtk.Entry.set_invisible_char].

`GtkEntry` has the ability to display progress or activity
information behind the text. To make an entry display such information,
use [method@Gtk.Entry.set_progress_fraction] or
[method@Gtk.Entry.set_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
[method@Gtk.Entry.set_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 [signal@Gtk.Entry::icon-press] signal.
To allow DND operations from an icon, use
[method@Gtk.Entry.set_icon_drag_source]. To set a tooltip on an icon, use
[method@Gtk.Entry.set_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][.warning][.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 [class@Gtk.Text].

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

https://docs.gtk.org/gtk4/class.Entry.html

  • Field Details

  • Constructor Details

    • Entry

      public Entry(PointerContainer pointer)
    • Entry

      public Entry()
      Creates a new entry.
  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()
    • newWithBufferEntry

      public static Entry newWithBufferEntry(@Nonnull EntryBuffer buffer)
      Creates a new entry with the specified text buffer.
      Parameters:
      buffer - The buffer to use for the new `GtkEntry`.
      Returns:
      a new `GtkEntry`
    • getActivatesDefault

      public boolean getActivatesDefault()
      Retrieves the value set by gtk_entry_set_activates_default().
      Returns:
      %TRUE if the entry will activate the default widget
    • getAlignment

      public float getAlignment()
      Gets the value set by gtk_entry_set_alignment().

      See also: [property@Gtk.Editable:xalign]
      Returns:
      the alignment
    • getAttributes

      public AttrList getAttributes()
      Gets the attribute list of the `GtkEntry`.

      See [method@Gtk.Entry.set_attributes].
      Returns:
      the attribute list
    • getBuffer

      public EntryBuffer getBuffer()
      Get the `GtkEntryBuffer` object which holds the text for
      this widget.
      Returns:
      A `GtkEntryBuffer` object.
    • getCompletion

      public EntryCompletion getCompletion()
      Returns the auxiliary completion object currently
      in use by @entry.
      Returns:
      The auxiliary completion object currently in use by @entry
    • getCurrentIconDragSource

      public int getCurrentIconDragSource()
      Returns the index of the icon which is the source of the
      current DND operation, or -1.
      Returns:
      index of the icon which is the source of the current DND operation, or -1.
    • getExtraMenu

      public MenuModel getExtraMenu()
      Gets the menu model set with gtk_entry_set_extra_menu().
      Returns:
      the menu model
    • getHasFrame

      public boolean getHasFrame()
      Gets the value set by gtk_entry_set_has_frame().
      Returns:
      whether the entry has a beveled frame
    • getIconActivatable

      public boolean getIconActivatable(int icon_pos)
      Returns whether the icon is activatable.
      Parameters:
      icon_pos - Icon position
      Returns:
      %TRUE if the icon is activatable.
    • getIconArea

      public void getIconArea(int icon_pos, @Nonnull Rectangle icon_area)
      Gets the area where entry’s icon at @icon_pos is drawn.

      This function is useful when drawing something to the
      entry in a draw callback.

      If the entry is not realized or has no icon at the given
      position, @icon_area is filled with zeros. Otherwise,
      @icon_area will be filled with the icon's allocation,
      relative to @entry's allocation.
      Parameters:
      icon_pos - Icon position
      icon_area - Return location for the icon’s area
    • getIconAtPos

      public int getIconAtPos(int x, int y)
      Finds the icon at the given position and return its index.

      The position’s coordinates are relative to the @entry’s
      top left corner. If @x, @y doesn’t lie inside an icon,
      -1 is returned. This function is intended for use in a
      [signal@Gtk.Widget::query-tooltip] signal handler.
      Parameters:
      x - the x coordinate of the position to find, relative to @entry
      y - the y coordinate of the position to find, relative to @entry
      Returns:
      the index of the icon at the given position, or -1
    • getIconGicon

      public Icon getIconGicon(int icon_pos)
      Retrieves the `GIcon` used for the icon.

      %NULL will be returned if there is no icon or if the icon was
      set by some other method (e.g., by `GdkPaintable` or icon name).
      Parameters:
      icon_pos - Icon position
      Returns:
      A `GIcon`
    • getIconName

      public Str getIconName(int icon_pos)
      Retrieves the icon name used for the icon.

      %NULL is returned if there is no icon or if the icon was set
      by some other method (e.g., by `GdkPaintable` or gicon).
      Parameters:
      icon_pos - Icon position
      Returns:
      An icon name
    • getIconPaintable

      public Paintable getIconPaintable(int icon_pos)
      Retrieves the `GdkPaintable` used for the icon.

      If no `GdkPaintable` was used for the icon, %NULL is returned.
      Parameters:
      icon_pos - Icon position
      Returns:
      A `GdkPaintable` if no icon is set for this position or the icon set is not a `GdkPaintable`.
    • getIconSensitive

      public boolean getIconSensitive(int icon_pos)
      Returns whether the icon appears sensitive or insensitive.
      Parameters:
      icon_pos - Icon position
      Returns:
      %TRUE if the icon is sensitive.
    • getIconStorageType

      public int getIconStorageType(int icon_pos)
      Gets the type of representation being used by the icon
      to store image data.

      If the icon has no image data, the return value will
      be %GTK_IMAGE_EMPTY.
      Parameters:
      icon_pos - Icon position
      Returns:
      image representation being used
    • getIconTooltipMarkup

      public Str getIconTooltipMarkup(int icon_pos)
      Gets the contents of the tooltip on the icon at the specified
      position in @entry.
      Parameters:
      icon_pos - the icon position
      Returns:
      the tooltip text
    • getIconTooltipText

      public Str getIconTooltipText(int icon_pos)
      Gets the contents of the tooltip on the icon at the specified
      position in @entry.
      Parameters:
      icon_pos - the icon position
      Returns:
      the tooltip text
    • getInputHints

      public int getInputHints()
      Gets the input hints of this `GtkEntry`.
      Returns:
      the input hints
    • getInputPurpose

      public int getInputPurpose()
      Gets the input purpose of the `GtkEntry`.
      Returns:
      the input purpose
    • getInvisibleChar

      public byte getInvisibleChar()
      Retrieves the character displayed in place of the actual text
      in “password mode”.
      Returns:
      the current invisible char, or 0, if the entry does not show invisible text at all.
    • getMaxLength

      public int getMaxLength()
      Retrieves the maximum allowed length of the text in @entry.

      See [method@Gtk.Entry.set_max_length].
      Returns:
      the maximum allowed number of characters in `GtkEntry`, or 0 if there is no maximum.
    • getOverwriteMode

      public boolean getOverwriteMode()
      Gets whether the `GtkEntry` is in overwrite mode.
      Returns:
      whether the text is overwritten when typing.
    • getPlaceholderText

      public Str getPlaceholderText()
      Retrieves the text that will be displayed when @entry
      is empty and unfocused
      Returns:
      a pointer to the placeholder text as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored. If no placeholder text has been set, %NULL will be returned.
    • getProgressFraction

      public double getProgressFraction()
      Returns the current fraction of the task that’s been completed.

      See [method@Gtk.Entry.set_progress_fraction].
      Returns:
      a fraction from 0.0 to 1.0
    • getProgressPulseStep

      public double getProgressPulseStep()
      Retrieves the pulse step set with
      gtk_entry_set_progress_pulse_step().
      Returns:
      a fraction from 0.0 to 1.0
    • getTabs

      public TabArray getTabs()
      Gets the tabstops of the `GtkEntry.

      See [method@Gtk.Entry.set_tabs].
      Returns:
      the tabstops
    • getTextLength

      public int getTextLength()
      Retrieves the current length of the text in @entry.

      This is equivalent to getting @entry's `GtkEntryBuffer`
      and calling [method@Gtk.EntryBuffer.get_length] on it.
      Returns:
      the current number of characters in `GtkEntry`, or 0 if there are none.
    • getVisibility

      public boolean getVisibility()
      Retrieves whether the text in @entry is visible.

      See [method@Gtk.Entry.set_visibility].
      Returns:
      %TRUE if the text is currently visible
    • grabFocusWithoutSelecting

      public boolean grabFocusWithoutSelecting()
      Causes @entry to have keyboard focus.

      It behaves like [method@Gtk.Widget.grab_focus], except that it doesn't
      select the contents of the entry. You only want to call this on some
      special entries which the user usually doesn't want to replace all text
      in, such as search-as-you-type entries.
      Returns:
      %TRUE if focus is now inside @self
    • progressPulse

      public void progressPulse()
      Indicates that some progress is made, but you don’t
      know how much.

      Causes the entry’s progress indicator to enter “activity
      mode”, where a block bounces back and forth. Each call to
      gtk_entry_progress_pulse() causes the block to move by a
      little bit (the amount of movement per pulse is determined
      by [method@Gtk.Entry.set_progress_pulse_step]).
    • resetImContext

      public void resetImContext()
      Reset the input method context of the entry if needed.

      This can be necessary in the case where modifying the buffer
      would confuse on-going input method behavior.
    • setActivatesDefault

      public void setActivatesDefault(boolean setting)
      Sets whether pressing Enter in the @entry will activate the default
      widget for the window containing the entry.

      This usually means that the dialog containing the entry will be closed,
      since the default widget is usually one of the dialog buttons.
      Parameters:
      setting - %TRUE to activate window’s default widget on Enter keypress
    • setAlignment

      public void setAlignment(float xalign)
      Sets the alignment for the contents of the entry.

      This controls the horizontal positioning of the contents when
      the displayed text is shorter than the width of the entry.

      See also: [property@Gtk.Editable:xalign]
      Parameters:
      xalign - The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts
    • setAttributes

      public void setAttributes(@Nonnull AttrList attrs)
      Sets a `PangoAttrList`.

      The attributes in the list are applied to the entry text.

      Since the attributes will be applies to text that changes
      as the user types, it makes most sense to use attributes
      with unlimited extent.
      Parameters:
      attrs - a `PangoAttrList`
    • setBuffer

      public void setBuffer(@Nonnull EntryBuffer buffer)
      Set the `GtkEntryBuffer` object which holds the text for
      this widget.
      Parameters:
      buffer - a `GtkEntryBuffer`
    • setCompletion

      public void setCompletion(@Nullable EntryCompletion completion)
      Sets @completion to be the auxiliary completion object
      to use with @entry.

      All further configuration of the completion mechanism is
      done on @completion using the `GtkEntryCompletion` API.
      Completion is disabled if @completion is set to %NULL.
      Parameters:
      completion - The `GtkEntryCompletion`
    • setExtraMenu

      public void setExtraMenu(@Nullable MenuModel model)
      Sets a menu model to add when constructing
      the context menu for @entry.
      Parameters:
      model - a `GMenuModel`
    • setHasFrame

      public void setHasFrame(boolean setting)
      Sets whether the entry has a beveled frame around it.
      Parameters:
      setting - new value
    • setIconActivatable

      public void setIconActivatable(int icon_pos, boolean activatable)
      Sets whether the icon is activatable.
      Parameters:
      icon_pos - Icon position
      activatable - %TRUE if the icon should be activatable
    • setIconDragSource

      public void setIconDragSource(int icon_pos, @Nonnull ContentProvider provider, int actions)
      Sets up the icon at the given position as drag source.

      This makes it so that GTK will start a drag
      operation when the user clicks and drags the icon.
      Parameters:
      icon_pos - icon position
      provider - a `GdkContentProvider`
      actions - a bitmask of the allowed drag actions
    • setIconFromGicon

      public void setIconFromGicon(int icon_pos, @Nullable Icon icon)
      Sets the icon shown in the entry at the specified position
      from the current icon theme.

      If the icon isn’t known, a “broken image” icon will be
      displayed instead.

      If @icon is %NULL, no icon will be shown in the
      specified position.
      Parameters:
      icon_pos - The position at which to set the icon
      icon - The icon to set
    • setIconFromIconName

      public void setIconFromIconName(int icon_pos, @Nullable Str icon_name)
      Sets the icon shown in the entry at the specified position
      from the current icon theme.

      If the icon name isn’t known, a “broken image” icon will be
      displayed instead.

      If @icon_name is %NULL, no icon will be shown in the
      specified position.
      Parameters:
      icon_pos - The position at which to set the icon
      icon_name - An icon name
    • setIconFromIconName

      public void setIconFromIconName(int icon_pos, String icon_name)
      Sets the icon shown in the entry at the specified position
      from the current icon theme.

      If the icon name isn’t known, a “broken image” icon will be
      displayed instead.

      If @icon_name is %NULL, no icon will be shown in the
      specified position.
      Parameters:
      icon_pos - The position at which to set the icon
      icon_name - An icon name
    • setIconFromPaintable

      public void setIconFromPaintable(int icon_pos, @Nullable Paintable paintable)
      Sets the icon shown in the specified position using a `GdkPaintable`.

      If @paintable is %NULL, no icon will be shown in the specified position.
      Parameters:
      icon_pos - Icon position
      paintable - A `GdkPaintable`
    • setIconSensitive

      public void setIconSensitive(int icon_pos, boolean sensitive)
      Sets the sensitivity for the specified icon.
      Parameters:
      icon_pos - Icon position
      sensitive - Specifies whether the icon should appear sensitive or insensitive
    • setIconTooltipMarkup

      public void setIconTooltipMarkup(int icon_pos, @Nullable Str tooltip)
      Sets @tooltip as the contents of the tooltip for the icon at
      the specified position.

      @tooltip is assumed to be marked up with Pango Markup.

      Use %NULL for @tooltip to remove an existing tooltip.

      See also [method@Gtk.Widget.set_tooltip_markup] and
      [method@Gtk.Entry.set_icon_tooltip_text].
      Parameters:
      icon_pos - the icon position
      tooltip - the contents of the tooltip for the icon
    • setIconTooltipMarkup

      public void setIconTooltipMarkup(int icon_pos, String tooltip)
      Sets @tooltip as the contents of the tooltip for the icon at
      the specified position.

      @tooltip is assumed to be marked up with Pango Markup.

      Use %NULL for @tooltip to remove an existing tooltip.

      See also [method@Gtk.Widget.set_tooltip_markup] and
      [method@Gtk.Entry.set_icon_tooltip_text].
      Parameters:
      icon_pos - the icon position
      tooltip - the contents of the tooltip for the icon
    • setIconTooltipText

      public void setIconTooltipText(int icon_pos, @Nullable Str tooltip)
      Sets @tooltip as the contents of the tooltip for the icon
      at the specified position.

      Use %NULL for @tooltip to remove an existing tooltip.

      See also [method@Gtk.Widget.set_tooltip_text] and
      [method@Gtk.Entry.set_icon_tooltip_markup].

      If you unset the widget tooltip via
      [method@Gtk.Widget.set_tooltip_text] or
      [method@Gtk.Widget.set_tooltip_markup], this sets
      [property@Gtk.Widget:has-tooltip] to %FALSE, which suppresses
      icon tooltips too. You can resolve this by then calling
      [method@Gtk.Widget.set_has_tooltip] to set
      [property@Gtk.Widget:has-tooltip] back to %TRUE, or
      setting at least one non-empty tooltip on any icon
      achieves the same result.
      Parameters:
      icon_pos - the icon position
      tooltip - the contents of the tooltip for the icon
    • setIconTooltipText

      public void setIconTooltipText(int icon_pos, String tooltip)
      Sets @tooltip as the contents of the tooltip for the icon
      at the specified position.

      Use %NULL for @tooltip to remove an existing tooltip.

      See also [method@Gtk.Widget.set_tooltip_text] and
      [method@Gtk.Entry.set_icon_tooltip_markup].

      If you unset the widget tooltip via
      [method@Gtk.Widget.set_tooltip_text] or
      [method@Gtk.Widget.set_tooltip_markup], this sets
      [property@Gtk.Widget:has-tooltip] to %FALSE, which suppresses
      icon tooltips too. You can resolve this by then calling
      [method@Gtk.Widget.set_has_tooltip] to set
      [property@Gtk.Widget:has-tooltip] back to %TRUE, or
      setting at least one non-empty tooltip on any icon
      achieves the same result.
      Parameters:
      icon_pos - the icon position
      tooltip - the contents of the tooltip for the icon
    • setInputHints

      public void setInputHints(int hints)
      Set additional hints which allow input methods to
      fine-tune their behavior.
      Parameters:
      hints - the hints
    • setInputPurpose

      public void setInputPurpose(int purpose)
      Sets the input purpose which can be used by input methods
      to adjust their behavior.
      Parameters:
      purpose - the purpose
    • setInvisibleChar

      public void setInvisibleChar(byte ch)
      Sets the character to use in place of the actual text
      in “password mode”.

      See [method@Gtk.Entry.set_visibility] for how to enable
      “password mode”.

      By default, GTK picks the best invisible char available in
      the current font. If you set the invisible char to 0, then
      the user will get no feedback at all; there will be no text
      on the screen as they type.
      Parameters:
      ch - a Unicode character
    • setMaxLength

      public void setMaxLength(int max)
      Sets the maximum allowed length of the contents of the widget.

      If the current contents are longer than the given length, then
      they will be truncated to fit. The length is is in characters.

      This is equivalent to getting @entry's `GtkEntryBuffer` and
      calling [method@Gtk.EntryBuffer.set_max_length] on it.
      Parameters:
      max - the maximum length of the entry, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536.
    • setOverwriteMode

      public void setOverwriteMode(boolean overwrite)
      Sets whether the text is overwritten when typing in the `GtkEntry`.
      Parameters:
      overwrite - new value
    • setPlaceholderText

      public void setPlaceholderText(@Nullable Str text)
      Sets text to be displayed in @entry when it is empty.

      This can be used to give a visual hint of the expected
      contents of the `GtkEntry`.
      Parameters:
      text - a string to be displayed when @entry is empty and unfocused
    • setPlaceholderText

      public void setPlaceholderText(String text)
      Sets text to be displayed in @entry when it is empty.

      This can be used to give a visual hint of the expected
      contents of the `GtkEntry`.
      Parameters:
      text - a string to be displayed when @entry is empty and unfocused
    • setProgressFraction

      public void setProgressFraction(double fraction)
      Causes the entry’s progress indicator to “fill in” the given
      fraction of the bar.

      The fraction should be between 0.0 and 1.0, inclusive.
      Parameters:
      fraction - fraction of the task that’s been completed
    • setProgressPulseStep

      public void setProgressPulseStep(double fraction)
      Sets the fraction of total entry width to move the progress
      bouncing block for each pulse.

      Use [method@Gtk.Entry.progress_pulse] to pulse
      the progress.
      Parameters:
      fraction - fraction between 0.0 and 1.0
    • setTabs

      public void setTabs(@Nullable TabArray tabs)
      Sets a `PangoTabArray`.

      The tabstops in the array are applied to the entry text.
      Parameters:
      tabs - a `PangoTabArray`
    • setVisibility

      public void setVisibility(boolean visible)
      Sets whether the contents of the entry are visible or not.

      When visibility is set to %FALSE, characters are displayed
      as the invisible char, and will also appear that way when
      the text in the entry widget is copied elsewhere.

      By default, GTK picks the best invisible character available
      in the current font, but it can be changed with
      [method@Gtk.Entry.set_invisible_char].

      Note that you probably want to set [property@Gtk.Entry:input-purpose]
      to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to
      inform input methods about the purpose of this entry,
      in addition to setting visibility to %FALSE.
      Parameters:
      visible - %TRUE if the contents of the entry are displayed as plaintext
    • unsetInvisibleChar

      public void unsetInvisibleChar()
      Unsets the invisible char, so that the default invisible char
      is used again. See [method@Gtk.Entry.set_invisible_char].
    • onActivate

      public SignalHandler onActivate(Entry.OnActivate signal)
      Connect to signal "activate".
      See Entry.OnActivate.onActivate() for signal description.
      Field SIGNAL_ON_ACTIVATE contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.
    • onIconPress

      public SignalHandler onIconPress(Entry.OnIconPress signal)
      Connect to signal "icon-press".
      See Entry.OnIconPress.onIconPress(int) for signal description.
      Field SIGNAL_ON_ICON_PRESS contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.
    • onIconRelease

      public SignalHandler onIconRelease(Entry.OnIconRelease signal)
      Connect to signal "icon-release".
      See Entry.OnIconRelease.onIconRelease(int) for signal description.
      Field SIGNAL_ON_ICON_RELEASE contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.
    • asAccessible

      public Accessible asAccessible()
      Implements interface Accessible. Call this to get access to interface functions.
      Overrides:
      asAccessible in class Widget
      Returns:
      Accessible
    • asBuildable

      public Buildable asBuildable()
      Implements interface Buildable. Call this to get access to interface functions.
      Overrides:
      asBuildable in class Widget
      Returns:
      Buildable
    • asCellEditable

      public CellEditable asCellEditable()
      Implements interface CellEditable. Call this to get access to interface functions.
      Returns:
      CellEditable
    • asConstraintTarget

      public ConstraintTarget asConstraintTarget()
      Implements interface ConstraintTarget. Call this to get access to interface functions.
      Overrides:
      asConstraintTarget in class Widget
      Returns:
      ConstraintTarget
    • asEditable

      public Editable asEditable()
      Implements interface Editable. Call this to get access to interface functions.
      Returns:
      Editable
    • getTypeID

      public static long getTypeID()
    • getParentTypeID

      public static long getParentTypeID()
    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()
    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()
    • getInstanceSize

      public static int getInstanceSize()