Class Entry

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.Entry
All Implemented Interfaces:
Accessible, Buildable, CellEditable, ConstraintTarget, Editable, Proxy
@Generated("org.javagi.JavaGI") public class Entry extends Widget implements Accessible, Buildable, CellEditable, ConstraintTarget, Editable

A single-line text entry widget.

An example GtkEntry

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 setVisibility(boolean). 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 setInvisibleChar(int).

GtkEntry has the ability to display progress or activity information behind the text. To make an entry display such information, use setProgressFraction(double) or setProgressPulseStep(double).

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 setIconFromGicon(EntryIconPosition, Icon) 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 Gtk.Entry::icon-press signal. To allow DND operations from an icon, use setIconDragSource(EntryIconPosition, ContentProvider, Set). To set a tooltip on an icon, use setIconTooltipText(EntryIconPosition, String) 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 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:

<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.AccessibleRole.text_box role.

  • Constructor Details

    • Entry

      public Entry(MemorySegment address)
      Create a Entry instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Entry

      public Entry()
      Create a new Entry.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Entry class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Entry asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • withBuffer

      public static Entry withBuffer(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: Gtk.Editable:xalign

      Specified by:
      getAlignment in interface Editable
      Returns:
      the alignment

    • getAttributes

      public @Nullable AttrList getAttributes()

      Gets the attribute list of the GtkEntry.

      See setAttributes(AttrList).

      Returns:
      the attribute list

    • getBuffer

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

    • getCompletion

      @Deprecated public @Nullable EntryCompletion getCompletion()
      Deprecated.
      GtkEntryCompletion will be removed in GTK 5.
      Returns the auxiliary completion object currently in use by entry.
      Returns:
      The auxiliary completion object currently in use by this 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 @Nullable 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(EntryIconPosition iconPos)
      Returns whether the icon is activatable.
      Parameters:
      iconPos - Icon position
      Returns:
      true if the icon is activatable.

    • getIconArea

      public void getIconArea(EntryIconPosition iconPos, Rectangle iconArea)

      Gets the area where entry’s icon at iconPos 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, iconArea is filled with zeros. Otherwise, iconArea will be filled with the icon's allocation, relative to entry's allocation.

      Parameters:
      iconPos - Icon position
      iconArea - 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 Gtk.Widget::query-tooltip signal handler.

      Parameters:
      x - the x coordinate of the position to find, relative to this Entry
      y - the y coordinate of the position to find, relative to this Entry
      Returns:
      the index of the icon at the given position, or -1

    • getIconGicon

      public @Nullable Icon getIconGicon(EntryIconPosition iconPos)

      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:
      iconPos - Icon position
      Returns:
      A GIcon

    • getIconName

      public @Nullable String getIconName(EntryIconPosition iconPos)

      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:
      iconPos - Icon position
      Returns:
      An icon name

    • getIconPaintable

      public @Nullable Paintable getIconPaintable(EntryIconPosition iconPos)

      Retrieves the GdkPaintable used for the icon.

      If no GdkPaintable was used for the icon, null is returned.

      Parameters:
      iconPos - 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(EntryIconPosition iconPos)
      Returns whether the icon appears sensitive or insensitive.
      Parameters:
      iconPos - Icon position
      Returns:
      true if the icon is sensitive.

    • getIconStorageType

      public ImageType getIconStorageType(EntryIconPosition iconPos)

      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 ImageType.EMPTY.

      Parameters:
      iconPos - Icon position
      Returns:
      image representation being used

    • getIconTooltipMarkup

      public @Nullable String getIconTooltipMarkup(EntryIconPosition iconPos)
      Gets the contents of the tooltip on the icon at the specified position in entry.
      Parameters:
      iconPos - the icon position
      Returns:
      the tooltip text

    • getIconTooltipText

      public @Nullable String getIconTooltipText(EntryIconPosition iconPos)
      Gets the contents of the tooltip on the icon at the specified position in entry.
      Parameters:
      iconPos - the icon position
      Returns:
      the tooltip text

    • getInputHints

      public Set<InputHints> getInputHints()
      Gets the input hints of this GtkEntry.
      Returns:
      the input hints

    • getInputPurpose

      public InputPurpose getInputPurpose()
      Gets the input purpose of the GtkEntry.
      Returns:
      the input purpose

    • getInvisibleChar

      public int 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 setMaxLength(int).

      Returns:
      the maximum allowed number of characters in GtkEntry, or 0 if there is no maximum.

    • getMenuEntryIconText

      public @Nullable String getMenuEntryIconText(EntryIconPosition iconPos)
      Gets the text that will be used in the context menu of the GtkEntry when the specified icon is activatable. Selecting this item in the menu results, from all aspects, the same than clicking on the specified icon. This greatly simplifies making accessible applications, because the icons aren't focusable when using keyboard navigation. This is why Gtk recommends to add the same action to the context menu.
      Parameters:
      iconPos - either GTKENTRYICONPRIMARY or GTKENTRYICONSECONDARY
      Returns:
      the text that will be used in the menu item, or NULL if no menu item is desired.
      Since:
      4.20

    • getOverwriteMode

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

    • getPlaceholderText

      public @Nullable String getPlaceholderText()
      Retrieves the text that will be displayed when this 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 setProgressFraction(double).

      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 @Nullable TabArray getTabs()

      Gets the tabstops of the GtkEntry.

      See setTabs(TabArray).

      Returns:
      the tabstops

    • getTextLength

      public short getTextLength()

      Retrieves the current length of the text in entry.

      This is equivalent to getting entry's GtkEntryBuffer and calling EntryBuffer.getLength() 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 this Entry is visible.

      See setVisibility(boolean).

      Returns:
      true if the text is currently visible

    • grabFocusWithoutSelecting

      public boolean grabFocusWithoutSelecting()

      Causes this Entry to have keyboard focus.

      It behaves like Widget.grabFocus(), 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 setProgressPulseStep(double)).

    • 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 this 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: Gtk.Editable:xalign

      Specified by:
      setAlignment in interface Editable
      Parameters:
      xalign - The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts

    • setAttributes

      public void setAttributes(AttrList attrs)

      Sets a PangoAttrList.

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

      Since the attributes will be applied 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(EntryBuffer buffer)
      Set the GtkEntryBuffer object which holds the text for this widget.
      Parameters:
      buffer - a GtkEntryBuffer

    • setCompletion

      @Deprecated public void setCompletion(@Nullable EntryCompletion completion)
      Deprecated.
      GtkEntryCompletion will be removed in GTK 5.

      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(EntryIconPosition iconPos, boolean activatable)
      Sets whether the icon is activatable.
      Parameters:
      iconPos - Icon position
      activatable - true if the icon should be activatable

    • setIconDragSource

      public void setIconDragSource(EntryIconPosition iconPos, ContentProvider provider, Set<DragAction> 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:
      iconPos - icon position
      provider - a GdkContentProvider
      actions - a bitmask of the allowed drag actions

    • setIconDragSource

      public void setIconDragSource(EntryIconPosition iconPos, ContentProvider provider, DragAction... 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:
      iconPos - icon position
      provider - a GdkContentProvider
      actions - a bitmask of the allowed drag actions

    • setIconFromGicon

      public void setIconFromGicon(EntryIconPosition iconPos, @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:
      iconPos - The position at which to set the icon
      icon - The icon to set

    • setIconFromIconName

      public void setIconFromIconName(EntryIconPosition iconPos, @Nullable String iconName)

      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 iconName is null, no icon will be shown in the specified position.

      Parameters:
      iconPos - The position at which to set the icon
      iconName - An icon name

    • setIconFromPaintable

      public void setIconFromPaintable(EntryIconPosition iconPos, @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:
      iconPos - Icon position
      paintable - A GdkPaintable

    • setIconSensitive

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

    • setIconTooltipMarkup

      public void setIconTooltipMarkup(EntryIconPosition iconPos, @Nullable 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 Widget.setTooltipMarkup(String) and setIconTooltipText(EntryIconPosition, String).

      Parameters:
      iconPos - the icon position
      tooltip - the contents of the tooltip for the icon

    • setIconTooltipText

      public void setIconTooltipText(EntryIconPosition iconPos, @Nullable 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 Widget.setTooltipText(String) and setIconTooltipMarkup(EntryIconPosition, String).

      If you unset the widget tooltip via Widget.setTooltipText(String) or Widget.setTooltipMarkup(String), this sets Gtk.Widget:has-tooltip to false, which suppresses icon tooltips too. You can resolve this by then calling Widget.setHasTooltip(boolean) to set Gtk.Widget:has-tooltip back to true, or setting at least one non-empty tooltip on any icon achieves the same result.

      Parameters:
      iconPos - the icon position
      tooltip - the contents of the tooltip for the icon

    • setInputHints

      public void setInputHints(Set<InputHints> hints)
      Set additional hints which allow input methods to fine-tune their behavior.
      Parameters:
      hints - the hints

    • setInputHints

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

    • setInputPurpose

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

    • setInvisibleChar

      public void setInvisibleChar(int ch)

      Sets the character to use in place of the actual text in “password mode”.

      See setVisibility(boolean) 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 in characters.

      This is equivalent to getting entry's GtkEntryBuffer and calling EntryBuffer.setMaxLength(int) 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.

    • setMenuEntryIconText

      public void setMenuEntryIconText(EntryIconPosition iconPos, String text)
      Sets the text that will be used in the context menu of the GtkEntry when the specified icon is activatable. Selecting this item in the menu results, from all aspects, the same than clicking on the specified icon. This greatly simplifies making accessible applications, because the icons aren't focusable when using keyboard navigation. This is why Gtk recommends to add the same action to the context menu.
      Parameters:
      iconPos - either GTKENTRYICONPRIMARY or GTKENTRYICONSECONDARY
      text - the text used for the menu item in the context menu, or NULL to not add a menu item.
      Since:
      4.20

    • 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 String text)

      Sets text to be displayed in this 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 this 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 progressPulse() 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 setInvisibleChar(int).

      Note that you probably want to set Gtk.Entry:input-purpose to InputPurpose.PASSWORD or InputPurpose.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 setInvisibleChar(int).

    • activate

      protected void activate()
      Class handler for the GtkEntry::activate signal. The default implementation activates the gtk.activate-default action.

    • onActivate

      public SignalConnection<Entry.ActivateCallback> onActivate(Entry.ActivateCallback handler)

      Emitted when the entry is activated.

      The keybindings for this signal are all forms of the Enter key.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitActivate

      public void emitActivate()
      Emits the "activate" signal. See onActivate(Entry.ActivateCallback).

    • onIconPress

      public SignalConnection<Entry.IconPressCallback> onIconPress(Entry.IconPressCallback handler)
      Emitted when an activatable icon is clicked.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitIconPress

      public void emitIconPress(EntryIconPosition iconPos)
      Emits the "icon-press" signal. See onIconPress(Entry.IconPressCallback).

    • onIconRelease

      public SignalConnection<Entry.IconReleaseCallback> onIconRelease(Entry.IconReleaseCallback handler)
      Emitted on the button release from a mouse click over an activatable icon.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitIconRelease

      public void emitIconRelease(EntryIconPosition iconPos)
      Emits the "icon-release" signal. See onIconRelease(Entry.IconReleaseCallback).

    • builder

      public static Entry.Builder<? extends Entry.Builder> builder()
      A Entry.Builder object constructs a Entry with the specified properties. Use the various set...() methods to set properties, and finish construction with Entry.Builder.build().
      Returns:
      the builder object