Class: Gtk::Text
Overview
The GtkText widget is a single-line text entry widget.
GtkText is the common implementation of single-line text editing
that is shared between [classGtk.Entry], [classGtk.PasswordEntry],
[classGtk.SpinButton], and other widgets. In all of these, GtkText is
used as the delegate for the [ifaceGtk.Editable] implementation.
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 [methodGtk.Text.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 [methodGtk.Text.set_invisible_char].
If you are looking to add icons or progress display in an entry, look at [classGtk.Entry]. There other alternatives for more specialized use cases, such as [classGtk.SearchEntry].
If you need multi-line editable text, look at [classGtk.TextView].
CSS nodes
text[.read-only]
├── placeholder
├── undershoot.left
├── undershoot.right
├── [selection]
├── [block-cursor]
╰── [window.popup]
GtkText has a main node with the name text. Depending on the properties
of the widget, the .read-only style class may appear.
When the entry has a selection, it adds a subnode with the name selection.
When the entry is in overwrite mode, it adds a subnode with the name
block-cursor that determines how the block cursor is drawn.
The CSS node for a context menu is added as a subnode with the name popup.
The undershoot nodes are used to draw the underflow indication when content
is scrolled out of view. These nodes get the .left or .right style class
added depending on where the indication is drawn.
When touch is used and touch selection handles are shown, they are using
CSS nodes with name cursor-handle. They get the .top or .bottom style
class depending on where they are shown in relation to the selection. If
there is just a single handle for the text cursor, it gets the style class
.insertion-cursor.
Accessibility
GtkText uses the %GTK_ACCESSIBLE_ROLE_NONE role, which causes it to be
skipped for accessibility. This is because GtkText is expected to be used
as a delegate for a GtkEditable implementation that will be represented
to accessibility.
Instance Method Summary collapse
-
#activates_default ⇒ Boolean
Returns whether pressing Enter will activate the default widget for the window containing self.
-
#activates_default=(activates_default) ⇒ Boolean
Whether to activate the default widget when Enter is pressed.
-
#activates_default? ⇒ Boolean
Whether to activate the default widget when Enter is pressed.
-
#attributes ⇒ Pango::AttrList
A list of Pango attributes to apply to the text of the
GtkText. -
#attributes=(attributes) ⇒ Pango::AttrList
A list of Pango attributes to apply to the text of the
GtkText. -
#buffer ⇒ Gtk::EntryBuffer
The
GtkEntryBufferobject which stores the text. -
#buffer=(buffer) ⇒ Gtk::EntryBuffer
The
GtkEntryBufferobject which stores the text. -
#compute_cursor_extents(position, strong, weak) ⇒ nil
Determine the positions of the strong and weak cursors if the insertion point in the layout is at position.
-
#enable_emoji_completion ⇒ Boolean
Returns whether Emoji completion is enabled for this
GtkTextwidget. -
#enable_emoji_completion=(enable_emoji_completion) ⇒ Boolean
Whether to suggest Emoji replacements.
-
#enable_emoji_completion? ⇒ Boolean
Whether to suggest Emoji replacements.
-
#extra_menu ⇒ Gio::MenuModel
A menu model whose contents will be appended to the context menu.
-
#extra_menu=(extra_menu) ⇒ Gio::MenuModel
A menu model whose contents will be appended to the context menu.
-
#grab_focus_without_selecting ⇒ Boolean
Causes self to have keyboard focus.
-
#im_module ⇒ String
Which IM (input method) module should be used for this self.
-
#im_module=(im_module) ⇒ String
Which IM (input method) module should be used for this self.
-
#initialize(buffer) ⇒ Gtk::Widget
constructor
Creates a new
GtkTextwith the specified text buffer. -
#input_hints ⇒ Gtk::InputHints
Additional hints that allow input methods to fine-tune their behaviour.
-
#input_hints=(input_hints) ⇒ Gtk::InputHints
Additional hints that allow input methods to fine-tune their behaviour.
-
#input_purpose ⇒ Gtk::InputPurpose
The purpose of this text field.
-
#input_purpose=(input_purpose) ⇒ Gtk::InputPurpose
The purpose of this text field.
-
#invisible_char ⇒ Integer
The character to used when masking contents (in “password mode”).
-
#invisible_char=(invisible_char) ⇒ Integer
The character to used when masking contents (in “password mode”).
-
#invisible_char_set=(invisible_char_set) ⇒ Boolean
Whether the invisible char has been set for the
GtkText. -
#invisible_char_set? ⇒ Boolean
Whether the invisible char has been set for the
GtkText. -
#max_length ⇒ Integer
Maximum number of characters that are allowed.
-
#max_length=(max_length) ⇒ Integer
Maximum number of characters that are allowed.
-
#overwrite_mode ⇒ Boolean
Gets whether text is overwritten when typing in the
GtkText. -
#overwrite_mode=(overwrite_mode) ⇒ Boolean
If text is overwritten when typing in the
GtkText. -
#overwrite_mode? ⇒ Boolean
If text is overwritten when typing in the
GtkText. -
#placeholder_text ⇒ String
The text that will be displayed in the
GtkTextwhen it is empty and unfocused. -
#placeholder_text=(placeholder_text) ⇒ String
The text that will be displayed in the
GtkTextwhen it is empty and unfocused. -
#propagate_text_width ⇒ Boolean
Returns whether the
GtkTextwill grow and shrink with the content. -
#propagate_text_width=(propagate_text_width) ⇒ Boolean
Whether the widget should grow and shrink with the content.
-
#propagate_text_width? ⇒ Boolean
Whether the widget should grow and shrink with the content.
-
#scroll_offset ⇒ Integer
Number of pixels scrolled of the screen to the left.
-
#scroll_offset=(scroll_offset) ⇒ Integer
Number of pixels scrolled of the screen to the left.
-
#tabs ⇒ Pango::TabArray
A list of tabstops to apply to the text of the
GtkText. -
#tabs=(tabs) ⇒ Pango::TabArray
A list of tabstops to apply to the text of the
GtkText. -
#text_length ⇒ Integer
Retrieves the current length of the text in self.
-
#truncate_multiline ⇒ Boolean
Returns whether the
GtkTextwill truncate multi-line text that is pasted into the widget. -
#truncate_multiline=(truncate_multiline) ⇒ Boolean
When true, pasted multi-line text is truncated to the first line.
-
#truncate_multiline? ⇒ Boolean
When true, pasted multi-line text is truncated to the first line.
-
#unset_invisible_char ⇒ nil
Unsets the invisible char.
-
#visibility ⇒ Boolean
Retrieves whether the text in self is visible.
-
#visibility=(visibility) ⇒ Boolean
If false, the text is masked with the “invisible char”.
-
#visibility? ⇒ Boolean
If false, the text is masked with the “invisible char”.
Methods inherited from Widget
#accessible_role, #accessible_role=, #action_set_enabled, #activate, #activate_action, #activate_action_variant, #activate_default, #activate_signal, #activate_signal=, #activate_signal_from_name=, #add_binding, #add_binding_action, #add_binding_signal, #add_controller, #add_css_class, #add_mnemonic_label, #add_shortcut, #add_tick_callback, #allocate, #allocated_baseline, #allocated_height, #allocated_width, #baseline, #bind_template_callback_full, #bind_template_child, #bind_template_child_full, #can_focus, #can_focus=, #can_focus?, #can_target, #can_target=, #can_target?, #child_focus, #child_visible, #child_visible=, #children, #clipboard, #compute_bounds, #compute_expand, #compute_point, #compute_transform, #contains, #create_pango_context, #create_pango_layout, #css_classes, #css_classes=, #css_name, #css_name=, #cursor, #cursor=, #cursor_from_name=, default_direction, default_direction=, #direction, #direction=, #display, #dispose_template, #drag_check_threshold, #error_bell, #first_child, #focus_child, #focus_child=, #focus_on_click, #focus_on_click=, #focus_on_click?, #focusable, #focusable=, #focusable?, #font_map, #font_map=, #font_options, #font_options=, #frame_clock, #get_allocation, #get_ancestor, #get_color, #get_preferred_size, #get_size, #get_size_request, #get_template_child, #grab_focus, #halign, #halign=, #has_css_class, #has_default, #has_default=, #has_default?, #has_focus, #has_focus=, #has_focus?, #has_tooltip, #has_tooltip=, #has_tooltip?, #has_visible_focus, have_template?, #height, #height_request, #height_request=, #hexpand, #hexpand=, #hexpand?, #hexpand_set, #hexpand_set=, #hexpand_set?, #hide, #in_destruction, #init_template, #insert_action_group, #insert_action_group_raw, #insert_after, #insert_before, #install_action, #install_property_action, #is_ancestor, #is_drawable, #is_focus, #is_sensitive, #is_visible, #keynav_failed, #last_child, #layout_manager, #layout_manager=, #layout_manager_type, #layout_manager_type=, #list_mnemonic_labels, #map, #mapped, #margin_bottom, #margin_bottom=, #margin_end, #margin_end=, #margin_start, #margin_start=, #margin_top, #margin_top=, #measure, #mnemonic_activate, #name, #name=, #native, #next_sibling, #observe_children, #observe_controllers, #opacity, #opacity=, #overflow, #overflow=, #pango_context, #parent, #parent=, #pick, #prev_sibling, #primary_clipboard, #query_action, #queue_allocate, #queue_draw, #queue_resize, #realize, #realized, #receives_default, #receives_default=, #receives_default?, #remove_controller, #remove_css_class, #remove_mnemonic_label, #remove_tick_callback, #request_mode, #root, #root=, #scale_factor, #scale_factor=, #sensitive, #sensitive=, #sensitive?, #set_size_request, #set_size_request_raw, #set_state_flags, #set_template, #set_template_raw, #settings, #should_layout, #show, #size_allocate, #snapshot_child, #state_flags, #style_context, #style_context_raw, #template=, template_children, #template_from_resource=, #template_scope=, #tooltip_markup, #tooltip_markup=, #tooltip_text, #tooltip_text=, #translate_coordinates, #translate_coordinates_raw, #trigger_tooltip_query, #unmap, #unparent, #unrealize, #unset_state_flags, #valign, #valign=, #vexpand, #vexpand=, #vexpand?, #vexpand_set, #vexpand_set=, #vexpand_set?, #visible, #visible=, #visible?, #width, #width_request, #width_request=
Constructor Details
#initialize(buffer) ⇒ Gtk::Widget
Creates a new GtkText with the specified text buffer.
Instance Method Details
#activates_default ⇒ Boolean
Returns whether pressing Enter will activate the default widget for the window containing self.
See [methodGtk.Text.set_activates_default].
#activates_default=(activates_default) ⇒ Boolean
Whether to activate the default widget when Enter is pressed.
#activates_default? ⇒ Boolean
Whether to activate the default widget when Enter is pressed.
#attributes ⇒ Pango::AttrList
A list of Pango attributes to apply to the text of the GtkText.
This is mainly useful to change the size or weight of the text.
The PangoAttribute's start_index and end_index must refer to the
GtkEntryBuffer text, i.e. without the preedit string.
#attributes=(attributes) ⇒ Pango::AttrList
A list of Pango attributes to apply to the text of the GtkText.
This is mainly useful to change the size or weight of the text.
The PangoAttribute's start_index and end_index must refer to the
GtkEntryBuffer text, i.e. without the preedit string.
#buffer ⇒ Gtk::EntryBuffer
The GtkEntryBuffer object which stores the text.
#buffer=(buffer) ⇒ Gtk::EntryBuffer
The GtkEntryBuffer object which stores the text.
#compute_cursor_extents(position, strong, weak) ⇒ nil
Determine the positions of the strong and weak cursors if the insertion point in the layout is at position.
The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction are inserted.
The rectangle positions are in widget coordinates.
#enable_emoji_completion ⇒ Boolean
Returns whether Emoji completion is enabled for this
GtkText widget.
#enable_emoji_completion=(enable_emoji_completion) ⇒ Boolean
Whether to suggest Emoji replacements.
#enable_emoji_completion? ⇒ Boolean
Whether to suggest Emoji replacements.
#extra_menu ⇒ Gio::MenuModel
A menu model whose contents will be appended to the context menu.
#extra_menu=(extra_menu) ⇒ Gio::MenuModel
A menu model whose contents will be appended to the context menu.
#grab_focus_without_selecting ⇒ Boolean
Causes self to have keyboard focus.
It behaves like [methodGtk.Widget.grab_focus], except that it doesn't select the contents of self. 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.
#im_module ⇒ String
Which IM (input method) module should be used for this self.
See [classGtk.IMMulticontext].
Setting this to a non-nil value overrides the system-wide IM module setting. See the [propertyGtk.Settings:gtk-im-module] property.
#im_module=(im_module) ⇒ String
Which IM (input method) module should be used for this self.
See [classGtk.IMMulticontext].
Setting this to a non-nil value overrides the system-wide IM module setting. See the [propertyGtk.Settings:gtk-im-module] property.
#input_hints ⇒ Gtk::InputHints
Additional hints that allow input methods to fine-tune their behaviour.
#input_hints=(input_hints) ⇒ Gtk::InputHints
Additional hints that allow input methods to fine-tune their behaviour.
#input_purpose ⇒ Gtk::InputPurpose
The purpose of this text field.
This property can be used by on-screen keyboards and other input methods to adjust their behaviour.
Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN is independent from setting [propertyGtk.Text:visibility].
#input_purpose=(input_purpose) ⇒ Gtk::InputPurpose
The purpose of this text field.
This property can be used by on-screen keyboards and other input methods to adjust their behaviour.
Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN is independent from setting [propertyGtk.Text:visibility].
#invisible_char ⇒ Integer
The character to used when masking contents (in “password mode”).
#invisible_char=(invisible_char) ⇒ Integer
The character to used when masking contents (in “password mode”).
#invisible_char_set=(invisible_char_set) ⇒ Boolean
Whether the invisible char has been set for the GtkText.
#invisible_char_set? ⇒ Boolean
Whether the invisible char has been set for the GtkText.
#max_length ⇒ Integer
Maximum number of characters that are allowed.
Zero indicates no limit.
#max_length=(max_length) ⇒ Integer
Maximum number of characters that are allowed.
Zero indicates no limit.
#overwrite_mode ⇒ Boolean
Gets whether text is overwritten when typing in the GtkText.
See [methodGtk.Text.set_overwrite_mode].
#overwrite_mode=(overwrite_mode) ⇒ Boolean
If text is overwritten when typing in the GtkText.
#overwrite_mode? ⇒ Boolean
If text is overwritten when typing in the GtkText.
#placeholder_text ⇒ String
The text that will be displayed in the GtkText when it is empty
and unfocused.
#placeholder_text=(placeholder_text) ⇒ String
The text that will be displayed in the GtkText when it is empty
and unfocused.
#propagate_text_width ⇒ Boolean
Returns whether the GtkText will grow and shrink
with the content.
#propagate_text_width=(propagate_text_width) ⇒ Boolean
Whether the widget should grow and shrink with the content.
#propagate_text_width? ⇒ Boolean
Whether the widget should grow and shrink with the content.
#scroll_offset ⇒ Integer
Number of pixels scrolled of the screen to the left.
#scroll_offset=(scroll_offset) ⇒ Integer
Number of pixels scrolled of the screen to the left.
#tabs ⇒ Pango::TabArray
A list of tabstops to apply to the text of the GtkText.
#tabs=(tabs) ⇒ Pango::TabArray
A list of tabstops to apply to the text of the GtkText.
#text_length ⇒ Integer
Retrieves the current length of the text in self.
This is equivalent to getting self's GtkEntryBuffer
and calling [methodGtk.EntryBuffer.get_length] on it.
#truncate_multiline ⇒ Boolean
Returns whether the GtkText will truncate multi-line text
that is pasted into the widget
#truncate_multiline=(truncate_multiline) ⇒ Boolean
When true, pasted multi-line text is truncated to the first line.
#truncate_multiline? ⇒ Boolean
When true, pasted multi-line text is truncated to the first line.
#unset_invisible_char ⇒ nil
Unsets the invisible char.
After calling this, the default invisible char is used again.
#visibility ⇒ Boolean
Retrieves whether the text in self is visible.
#visibility=(visibility) ⇒ Boolean
If false, the text is masked with the “invisible char”.
#visibility? ⇒ Boolean
If false, the text is masked with the “invisible char”.