class Gtk::Entry

• Gtk::Entry
• Gtk::Widget
• GObject::InitiallyUnowned
• GObject::Object
• Reference
• Object

Overview

Gtk::Entry 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 Gtk::Entry#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#invisible_char=.

Gtk::Entry has the ability to display progress or activity information behind the text. To make an entry display such information, use Gtk::Entry#progress_fraction= or Gtk::Entry#progress_pulse_step=.

Additionally, Gtk::Entry 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#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 Gtk::Entry#icon_drag_source=. To set a tooltip on an icon, use Gtk::Entry#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]]

Gtk::Entry 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 Gtk::Text.

Gtk::Entry as Gtk::Buildable

The Gtk::Entry implementation of the Gtk::Buildable interface supports a custom element, which supports any number of elements. The element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify Pango::Attribute values for this label.

An example of a UI definition fragment specifying Pango attributes:

WARNING ⚠️ The following code is in xml ⚠️

<object class="Gtk::Entry">
  <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

Gtk::Entry uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role.

Included Modules

• Gtk::Accessible
• Gtk::Buildable
• Gtk::CellEditable
• Gtk::ConstraintTarget
• Gtk::Editable

Defined in:

Constructors

• .new : self

  Creates a new entry.

• .new(*, accessible_role : Gtk::AccessibleRole | Nil = nil, activates_default : Bool | Nil = nil, attributes : Pango::AttrList | Nil = nil, buffer : Gtk::EntryBuffer | Nil = nil, can_focus : Bool | Nil = nil, can_target : Bool | Nil = nil, completion : Gtk::EntryCompletion | Nil = nil, css_classes : Enumerable(String) | Nil = nil, css_name : String | Nil = nil, cursor : Gdk::Cursor | Nil = nil, cursor_position : Int32 | Nil = nil, editable : Bool | Nil = nil, editing_canceled : Bool | Nil = nil, enable_emoji_completion : Bool | Nil = nil, enable_undo : Bool | Nil = nil, extra_menu : Gio::MenuModel | Nil = nil, focus_on_click : Bool | Nil = nil, focusable : Bool | Nil = nil, halign : Gtk::Align | Nil = nil, has_default : Bool | Nil = nil, has_focus : Bool | Nil = nil, has_frame : Bool | Nil = nil, has_tooltip : Bool | Nil = nil, height_request : Int32 | Nil = nil, hexpand : Bool | Nil = nil, hexpand_set : Bool | Nil = nil, im_module : String | Nil = nil, input_hints : Gtk::InputHints | Nil = nil, input_purpose : Gtk::InputPurpose | Nil = nil, invisible_char : UInt32 | Nil = nil, invisible_char_set : Bool | Nil = nil, layout_manager : Gtk::LayoutManager | Nil = nil, margin_bottom : Int32 | Nil = nil, margin_end : Int32 | Nil = nil, margin_start : Int32 | Nil = nil, margin_top : Int32 | Nil = nil, max_length : Int32 | Nil = nil, max_width_chars : Int32 | Nil = nil, name : String | Nil = nil, opacity : Float64 | Nil = nil, overflow : Gtk::Overflow | Nil = nil, overwrite_mode : Bool | Nil = nil, parent : Gtk::Widget | Nil = nil, placeholder_text : String | Nil = nil, primary_icon_activatable : Bool | Nil = nil, primary_icon_gicon : Gio::Icon | Nil = nil, primary_icon_name : String | Nil = nil, primary_icon_paintable : Gdk::Paintable | Nil = nil, primary_icon_sensitive : Bool | Nil = nil, primary_icon_storage_type : Gtk::ImageType | Nil = nil, primary_icon_tooltip_markup : String | Nil = nil, primary_icon_tooltip_text : String | Nil = nil, progress_fraction : Float64 | Nil = nil, progress_pulse_step : Float64 | Nil = nil, receives_default : Bool | Nil = nil, root : Gtk::Root | Nil = nil, scale_factor : Int32 | Nil = nil, scroll_offset : Int32 | Nil = nil, secondary_icon_activatable : Bool | Nil = nil, secondary_icon_gicon : Gio::Icon | Nil = nil, secondary_icon_name : String | Nil = nil, secondary_icon_paintable : Gdk::Paintable | Nil = nil, secondary_icon_sensitive : Bool | Nil = nil, secondary_icon_storage_type : Gtk::ImageType | Nil = nil, secondary_icon_tooltip_markup : String | Nil = nil, secondary_icon_tooltip_text : String | Nil = nil, selection_bound : Int32 | Nil = nil, sensitive : Bool | Nil = nil, show_emoji_icon : Bool | Nil = nil, tabs : Pango::TabArray | Nil = nil, text : String | Nil = nil, text_length : UInt32 | Nil = nil, tooltip_markup : String | Nil = nil, tooltip_text : String | Nil = nil, truncate_multiline : Bool | Nil = nil, valign : Gtk::Align | Nil = nil, vexpand : Bool | Nil = nil, vexpand_set : Bool | Nil = nil, visibility : Bool | Nil = nil, visible : Bool | Nil = nil, width_chars : Int32 | Nil = nil, width_request : Int32 | Nil = nil, xalign : Float32 | Nil = nil)
• .new_with_buffer(buffer : Gtk::EntryBuffer) : self

  Creates a new entry with the specified text buffer.

Class Method Summary

• .g_type : UInt64

  Returns the type id (GType) registered in GLib type system.

Instance Method Summary

• #==(other : self)

  Returns true if this reference is the same as other.

• #activate_signal
• #activates_default : Bool

  Retrieves the value set by gtk_entry_set_activates_default().

• #activates_default=(setting : Bool) : Nil

  Sets whether pressing Enter in the entry will activate the default widget for the window containing the entry.

• #activates_default? : Bool
• #alignment : Float32

  Gets the value set by gtk_entry_set_alignment().

• #alignment=(xalign : Float32) : Nil

  Sets the alignment for the contents of the entry.

• #attributes : Pango::AttrList | Nil

  Gets the attribute list of the Gtk::Entry.

• #attributes=(attrs : Pango::AttrList) : Nil

  Sets a Pango::AttrList.

• #attributes=(value : Pango::AttrList | Nil) : Pango::AttrList | Nil
• #buffer : Gtk::EntryBuffer

  Get the Gtk::EntryBuffer object which holds the text for this widget.

• #buffer=(buffer : Gtk::EntryBuffer) : Nil

  Set the Gtk::EntryBuffer object which holds the text for this widget.

• #completion : Gtk::EntryCompletion | Nil

  Returns the auxiliary completion object currently in use by entry.

• #completion=(completion : Gtk::EntryCompletion | Nil) : Nil

  Sets completion to be the auxiliary completion object to use with entry.

• #current_icon_drag_source : Int32

  Returns the index of the icon which is the source of the current DND operation, or -1.

• #enable_emoji_completion=(value : Bool) : Bool
• #enable_emoji_completion? : Bool
• #extra_menu : Gio::MenuModel | Nil

  Gets the menu model set with gtk_entry_set_extra_menu().

• #extra_menu=(model : Gio::MenuModel | Nil) : Nil

  Sets a menu model to add when constructing the context menu for entry.

• #grab_focus_without_selecting : Bool

  Causes entry to have keyboard focus.

• #has_frame : Bool

  Gets the value set by gtk_entry_set_has_frame().

• #has_frame=(setting : Bool) : Nil

  Sets whether the entry has a beveled frame around it.

• #has_frame? : Bool
• #hash(hasher)

  See Object#hash(hasher)

• #icon_activatable(icon_pos : Gtk::EntryIconPosition) : Bool

  Returns whether the icon is activatable.

• #icon_area(icon_pos : Gtk::EntryIconPosition) : Gdk::Rectangle

  Gets the area where entry’s icon at icon_pos is drawn.

• #icon_at_pos(x : Int32, y : Int32) : Int32

  Finds the icon at the given position and return its index.

• #icon_gicon(icon_pos : Gtk::EntryIconPosition) : Gio::Icon | Nil

  Retrieves the GIcon used for the icon.

• #icon_name(icon_pos : Gtk::EntryIconPosition) : String | Nil

  Retrieves the icon name used for the icon.

• #icon_paintable(icon_pos : Gtk::EntryIconPosition) : Gdk::Paintable | Nil

  Retrieves the Gdk::Paintable used for the icon.

• #icon_press_signal
• #icon_release_signal
• #icon_sensitive(icon_pos : Gtk::EntryIconPosition) : Bool

  Returns whether the icon appears sensitive or insensitive.

• #icon_storage_type(icon_pos : Gtk::EntryIconPosition) : Gtk::ImageType

  Gets the type of representation being used by the icon to store image data.

• #icon_tooltip_markup(icon_pos : Gtk::EntryIconPosition) : String | Nil

  Gets the contents of the tooltip on the icon at the specified position in entry.

• #icon_tooltip_text(icon_pos : Gtk::EntryIconPosition) : String | Nil

  Gets the contents of the tooltip on the icon at the specified position in entry.

• #im_module : String
• #im_module=(value : String) : String
• #input_hints : Gtk::InputHints

  Gets the input hints of this Gtk::Entry.

• #input_hints=(hints : Gtk::InputHints) : Nil

  Set additional hints which allow input methods to fine-tune their behavior.

• #input_purpose : Gtk::InputPurpose

  Gets the input purpose of the Gtk::Entry.

• #input_purpose=(purpose : Gtk::InputPurpose) : Nil

  Sets the input purpose which can be used by input methods to adjust their behavior.

• #invisible_char : Char

  Retrieves the character displayed in place of the actual text in “password mode”.

• #invisible_char=(value : UInt32) : UInt32
• #invisible_char=(ch : Char) : Nil

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

• #invisible_char_set=(value : Bool) : Bool
• #invisible_char_set? : Bool
• #max_length : Int32

  Retrieves the maximum allowed length of the text in entry.

• #max_length=(max : Int32) : Nil

  Sets the maximum allowed length of the contents of the widget.

• #overwrite_mode : Bool

  Gets whether the Gtk::Entry is in overwrite mode.

• #overwrite_mode=(overwrite : Bool) : Nil

  Sets whether the text is overwritten when typing in the Gtk::Entry.

• #overwrite_mode? : Bool
• #placeholder_text : String | Nil

  Retrieves the text that will be displayed when entry is empty and unfocused

• #placeholder_text=(value : String) : String
• #placeholder_text=(text : String | Nil) : Nil

  Sets text to be displayed in entry when it is empty.

• #primary_icon_activatable=(value : Bool) : Bool
• #primary_icon_activatable? : Bool
• #primary_icon_gicon : Gio::Icon | Nil
• #primary_icon_gicon=(value : Gio::Icon | Nil) : Gio::Icon | Nil
• #primary_icon_name : String
• #primary_icon_name=(value : String) : String
• #primary_icon_paintable : Gdk::Paintable | Nil
• #primary_icon_paintable=(value : Gdk::Paintable | Nil) : Gdk::Paintable | Nil
• #primary_icon_sensitive=(value : Bool) : Bool
• #primary_icon_sensitive? : Bool
• #primary_icon_storage_type : Gtk::ImageType
• #primary_icon_tooltip_markup : String
• #primary_icon_tooltip_markup=(value : String) : String
• #primary_icon_tooltip_text : String
• #primary_icon_tooltip_text=(value : String) : String
• #progress_fraction : Float64

  Returns the current fraction of the task that’s been completed.

• #progress_fraction=(fraction : Float64) : Nil

  Causes the entry’s progress indicator to “fill in” the given fraction of the bar.

• #progress_pulse : Nil

  Indicates that some progress is made, but you don’t know how much.

• #progress_pulse_step : Float64

  Retrieves the pulse step set with gtk_entry_set_progress_pulse_step().

• #progress_pulse_step=(fraction : Float64) : Nil

  Sets the fraction of total entry width to move the progress bouncing block for each pulse.

• #reset_im_context : Nil

  Reset the input method context of the entry if needed.

• #scroll_offset : Int32
• #secondary_icon_activatable=(value : Bool) : Bool
• #secondary_icon_activatable? : Bool
• #secondary_icon_gicon : Gio::Icon | Nil
• #secondary_icon_gicon=(value : Gio::Icon | Nil) : Gio::Icon | Nil
• #secondary_icon_name : String
• #secondary_icon_name=(value : String) : String
• #secondary_icon_paintable : Gdk::Paintable | Nil
• #secondary_icon_paintable=(value : Gdk::Paintable | Nil) : Gdk::Paintable | Nil
• #secondary_icon_sensitive=(value : Bool) : Bool
• #secondary_icon_sensitive? : Bool
• #secondary_icon_storage_type : Gtk::ImageType
• #secondary_icon_tooltip_markup : String
• #secondary_icon_tooltip_markup=(value : String) : String
• #secondary_icon_tooltip_text : String
• #secondary_icon_tooltip_text=(value : String) : String
• #set_icon_activatable(icon_pos : Gtk::EntryIconPosition, activatable : Bool) : Nil

  Sets whether the icon is activatable.

• #set_icon_drag_source(icon_pos : Gtk::EntryIconPosition, provider : Gdk::ContentProvider, actions : Gdk::DragAction) : Nil

  Sets up the icon at the given position as drag source.

• #set_icon_from_gicon(icon_pos : Gtk::EntryIconPosition, icon : Gio::Icon | Nil) : Nil

  Sets the icon shown in the entry at the specified position from the current icon theme.

• #set_icon_from_icon_name(icon_pos : Gtk::EntryIconPosition, icon_name : String | Nil) : Nil

  Sets the icon shown in the entry at the specified position from the current icon theme.

• #set_icon_from_paintable(icon_pos : Gtk::EntryIconPosition, paintable : Gdk::Paintable | Nil) : Nil

  Sets the icon shown in the specified position using a Gdk::Paintable.

• #set_icon_sensitive(icon_pos : Gtk::EntryIconPosition, sensitive : Bool) : Nil

  Sets the sensitivity for the specified icon.

• #set_icon_tooltip_markup(icon_pos : Gtk::EntryIconPosition, tooltip : String | Nil) : Nil

  Sets tooltip as the contents of the tooltip for the icon at the specified position.

• #set_icon_tooltip_text(icon_pos : Gtk::EntryIconPosition, tooltip : String | Nil) : Nil

  Sets tooltip as the contents of the tooltip for the icon at the specified position.

• #show_emoji_icon=(value : Bool) : Bool
• #show_emoji_icon? : Bool
• #tabs : Pango::TabArray | Nil

  Gets the tabstops of the `Gtk::Entry.

• #tabs=(tabs : Pango::TabArray | Nil) : Nil

  Sets a Pango::TabArray.

• #text_length : UInt16

  Retrieves the current length of the text in entry.

• #truncate_multiline=(value : Bool) : Bool
• #truncate_multiline? : Bool
• #unset_invisible_char : Nil

  Unsets the invisible char, so that the default invisible char is used again.

• #visibility : Bool

  Retrieves whether the text in entry is visible.

• #visibility=(visible : Bool) : Nil

  Sets whether the contents of the entry are visible or not.

• #visibility? : Bool

Constructor Detail

Class Method Detail

Instance Method Detail