:right-sidebar: True

Text
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: Text(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.AccessibleText`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Editable`



The ``GtkText`` widget is a single-line text entry widget.

``GtkText`` is the common implementation of single-line text editing
that is shared between :obj:`~gi.repository.Gtk.Entry`, :obj:`~gi.repository.Gtk.PasswordEntry`,
:obj:`~gi.repository.Gtk.SpinButton`, and other widgets. In all of these, ``GtkText`` is
used as the delegate for the :obj:`~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.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
:obj:`~gi.repository.Gtk.Text.set_invisible_char`.

If you are looking to add icons or progress display in an entry, look
at :obj:`~gi.repository.Gtk.Entry`. There other alternatives for more specialized use
cases, such as :obj:`~gi.repository.Gtk.SearchEntry`.

If you need multi-line editable text, look at :obj:`~gi.repository.Gtk.TextView`.

Shortcuts and Gestures
----------------------

``GtkText`` supports the following keyboard shortcuts:


- :kbd:`Shift`+:kbd:`F10` or :kbd:`Menu` opens the context menu.
- :kbd:`Ctrl`+:kbd:`A` or :kbd:`Ctrl`+<kbd>&sol;</kbd>
  selects all the text.
- :kbd:`Ctrl`+:kbd:`Shift`+:kbd:`A` or
  :kbd:`Ctrl`+<kbd>&bsol;</kbd> unselects all.
- :kbd:`Ctrl`+:kbd:`Z` undoes the last modification.
- :kbd:`Ctrl`+:kbd:`Y` or :kbd:`Ctrl`+:kbd:`Shift`+:kbd:`Z`
  redoes the last undone modification.

Additionally, the following signals have default keybindings:


- :obj:`~gi.repository.Gtk.Text.signals.activate`
- :obj:`~gi.repository.Gtk.Text.signals.backspace`
- :obj:`~gi.repository.Gtk.Text.signals.copy_clipboard`
- :obj:`~gi.repository.Gtk.Text.signals.cut_clipboard`
- :obj:`~gi.repository.Gtk.Text.signals.delete_from_cursor`
- :obj:`~gi.repository.Gtk.Text.signals.insert_emoji`
- :obj:`~gi.repository.Gtk.Text.signals.move_cursor`
- :obj:`~gi.repository.Gtk.Text.signals.paste_clipboard`
- :obj:`~gi.repository.Gtk.Text.signals.toggle_overwrite`

Actions
-------

``GtkText`` defines a set of built-in actions:


- ``clipboard.copy`` copies the contents to the clipboard.
- ``clipboard.cut`` copies the contents to the clipboard and deletes it from
  the widget.
- ``clipboard.paste`` inserts the contents of the clipboard into the widget.
- ``menu.popup`` opens the context menu.
- ``misc.insert-emoji`` opens the Emoji chooser.
- ``misc.toggle-visibility`` toggles the ``GtkText``:visibility property.
- ``selection.delete`` deletes the current selection.
- ``selection.select-all`` selects all of the widgets content.
- ``text.redo`` redoes the last change to the contents.
- ``text.undo`` undoes the last change to the contents.

CSS nodes
---------


.. code-block:: 
   :dedent:

   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 :const:`~gi.repository.Gtk.AccessibleRole.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.



Constructors
------------

.. rst-class:: interim-class

.. class:: Text
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkText``.










   .. classmethod:: new_with_buffer(buffer: ~gi.repository.Gtk.EntryBuffer) -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkText`` with the specified text buffer.







      :param buffer: The buffer to use for the new ``GtkText``.









Methods
-------

.. rst-class:: interim-class

.. class:: Text
   :no-index:


   .. method:: compute_cursor_extents(position: int) -> tuple[~gi.repository.Graphene.Rect, ~gi.repository.Graphene.Rect]

      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.



      .. versionadded:: 4.4





      :param position: the character position





   .. method:: get_activates_default() -> bool

      Returns whether pressing Enter will activate
      the default widget for the window containing ``self``.

      See :obj:`~gi.repository.Gtk.Text.set_activates_default`.










   .. method:: get_attributes() -> ~gi.repository.Pango.AttrList | None

      Gets the attribute list that was set on the ``GtkText``.

      See :obj:`~gi.repository.Gtk.Text.set_attributes`.










   .. method:: get_buffer() -> ~gi.repository.Gtk.EntryBuffer

      Get the ``GtkEntryBuffer`` object which holds the text for
      this widget.










   .. method:: get_enable_emoji_completion() -> bool

      Returns whether Emoji completion is enabled for this
      ``GtkText`` widget.










   .. method:: get_extra_menu() -> ~gi.repository.Gio.MenuModel | None

      Gets the menu model for extra items in the context menu.

      See :obj:`~gi.repository.Gtk.Text.set_extra_menu`.










   .. method:: get_input_hints() -> ~gi.repository.Gtk.InputHints

      Gets the input hints of the ``GtkText``.










   .. method:: get_input_purpose() -> ~gi.repository.Gtk.InputPurpose

      Gets the input purpose of the ``GtkText``.










   .. method:: get_invisible_char() -> str

      Retrieves the character displayed when visibility is set to false.

      Note that GTK does not compute this value unless it needs it,
      so the value returned by this function is not very useful unless
      it has been explicitly set with :obj:`~gi.repository.Gtk.Text.set_invisible_char`.










   .. method:: get_max_length() -> int

      Retrieves the maximum allowed length of the text in ``self``.

      See :obj:`~gi.repository.Gtk.Text.set_max_length`.

      This is equivalent to getting ``self``'s ``GtkEntryBuffer`` and
      calling :obj:`~gi.repository.Gtk.EntryBuffer.get_max_length` on it.










   .. method:: get_overwrite_mode() -> bool

      Gets whether text is overwritten when typing in the ``GtkText``.

      See :obj:`~gi.repository.Gtk.Text.set_overwrite_mode`.










   .. method:: get_placeholder_text() -> str | None

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

      If no placeholder text has been set, :const:`None` will be returned.










   .. method:: get_propagate_text_width() -> bool

      Returns whether the ``GtkText`` will grow and shrink
      with the content.










   .. method:: get_tabs() -> ~gi.repository.Pango.TabArray | None

      Gets the tabstops that were set on the ``GtkText``.

      See :obj:`~gi.repository.Gtk.Text.set_tabs`.










   .. method:: get_text_length() -> int

      Retrieves the current length of the text in ``self``.

      This is equivalent to getting ``self``'s ``GtkEntryBuffer``
      and calling :obj:`~gi.repository.Gtk.EntryBuffer.get_length` on it.










   .. method:: get_truncate_multiline() -> bool

      Returns whether the ``GtkText`` will truncate multi-line text
      that is pasted into the widget










   .. method:: get_visibility() -> bool

      Retrieves whether the text in ``self`` is visible.










   .. method:: grab_focus_without_selecting() -> bool

      Causes ``self`` to have keyboard focus.

      It behaves like :obj:`~gi.repository.Gtk.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.










   .. method:: set_activates_default(activates: bool) -> None

      If ``activates`` is :const:`True`, pressing Enter will activate
      the default widget for the window containing ``self``.

      This usually means that the dialog containing the ``GtkText``
      will be closed, since the default widget is usually one of
      the dialog buttons.







      :param activates: :const:`True` to activate window’s default widget on Enter keypress





   .. method:: set_attributes(attrs: ~gi.repository.Pango.AttrList | None = None) -> None

      Sets attributes that are applied to the text.







      :param attrs: a ``PangoAttrList``





   .. method:: set_buffer(buffer: ~gi.repository.Gtk.EntryBuffer) -> None

      Set the ``GtkEntryBuffer`` object which holds the text for
      this widget.







      :param buffer: a ``GtkEntryBuffer``





   .. method:: set_enable_emoji_completion(enable_emoji_completion: bool) -> None

      Sets whether Emoji completion is enabled.

      If it is, typing ':', followed by a recognized keyword,
      will pop up a window with suggested Emojis matching the
      keyword.







      :param enable_emoji_completion: :const:`True` to enable Emoji completion





   .. method:: set_extra_menu(model: ~gi.repository.Gio.MenuModel | None = None) -> None

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







      :param model: a ``GMenuModel``





   .. method:: set_input_hints(hints: ~gi.repository.Gtk.InputHints) -> None

      Sets input hints that allow input methods
      to fine-tune their behaviour.







      :param hints: the hints





   .. method:: set_input_purpose(purpose: ~gi.repository.Gtk.InputPurpose) -> None

      Sets the input purpose of the ``GtkText``.

      This can be used by on-screen keyboards and other
      input methods to adjust their behaviour.







      :param purpose: the purpose





   .. method:: set_invisible_char(ch: str) -> None

      Sets the character to use when in “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.







      :param ch: a Unicode character





   .. method:: set_max_length(length: int) -> None

      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.

      This is equivalent to getting ``self``'s ``GtkEntryBuffer`` and
      calling :obj:`~gi.repository.Gtk.EntryBuffer.set_max_length` on it.







      :param length: the maximum length of the ``GtkText``, or 0 for no maximum.
         (other than the maximum length of entries.) The value passed
         in will be clamped to the range 0-65536.





   .. method:: set_overwrite_mode(overwrite: bool) -> None

      Sets whether the text is overwritten when typing
      in the ``GtkText``.







      :param overwrite: new value





   .. method:: set_placeholder_text(text: str | None = None) -> None

      Sets text to be displayed in ``self`` when it is empty.

      This can be used to give a visual hint of the expected
      contents of the ``GtkText``.







      :param text: a string to be displayed when ``self``
         is empty and unfocused





   .. method:: set_propagate_text_width(propagate_text_width: bool) -> None

      Sets whether the ``GtkText`` should grow and shrink with the content.







      :param propagate_text_width: :const:`True` to propagate the text width





   .. method:: set_tabs(tabs: ~gi.repository.Pango.TabArray | None = None) -> None

      Sets tabstops that are applied to the text.







      :param tabs: a ``PangoTabArray``





   .. method:: set_truncate_multiline(truncate_multiline: bool) -> None

      Sets whether the ``GtkText`` should truncate multi-line text
      that is pasted into the widget.







      :param truncate_multiline: :const:`True` to truncate multi-line text





   .. method:: set_visibility(visible: bool) -> None

      Sets whether the contents of the ``GtkText`` are visible or not.

      When visibility is set to :const:`False`, characters are displayed
      as the invisible char, and will also appear that way when
      the text in the widget is copied to the clipboard.

      By default, GTK picks the best invisible character available
      in the current font, but it can be changed with
      :obj:`~gi.repository.Gtk.Text.set_invisible_char`.

      Note that you probably want to set :obj:`~gi.repository.Gtk.Text.props.input_purpose`
      to :const:`~gi.repository.Gtk.InputPurpose.PASSWORD` or :const:`~gi.repository.Gtk.InputPurpose.PIN` to
      inform input methods about the purpose of this self,
      in addition to setting visibility to :const:`False`.







      :param visible: :const:`True` if the contents of the ``GtkText`` are displayed
         as plaintext





   .. method:: unset_invisible_char() -> None

      Unsets the invisible char.

      After calling this, the default invisible
      char is used again.














Properties
----------

.. rst-class:: interim-class

.. class:: Text
   :no-index:
   

   .. attribute:: props.activates_default
      :type: bool

      The type of the None singleton.







   .. attribute:: props.attributes
      :type: ~gi.repository.Pango.AttrList

      The type of the None singleton.







   .. attribute:: props.buffer
      :type: ~gi.repository.Gtk.EntryBuffer

      The type of the None singleton.







   .. attribute:: props.enable_emoji_completion
      :type: bool

      The type of the None singleton.







   .. attribute:: props.extra_menu
      :type: ~gi.repository.Gio.MenuModel

      The type of the None singleton.







   .. attribute:: props.im_module
      :type: str

      The type of the None singleton.







   .. attribute:: props.input_hints
      :type: ~gi.repository.Gtk.InputHints

      The type of the None singleton.







   .. attribute:: props.input_purpose
      :type: ~gi.repository.Gtk.InputPurpose

      The type of the None singleton.







   .. attribute:: props.invisible_char
      :type: int

      The type of the None singleton.







   .. attribute:: props.invisible_char_set
      :type: bool

      The type of the None singleton.







   .. attribute:: props.max_length
      :type: int

      The type of the None singleton.







   .. attribute:: props.overwrite_mode
      :type: bool

      The type of the None singleton.







   .. attribute:: props.placeholder_text
      :type: str

      The type of the None singleton.







   .. attribute:: props.propagate_text_width
      :type: bool

      The type of the None singleton.







   .. attribute:: props.scroll_offset
      :type: int

      The type of the None singleton.







   .. attribute:: props.tabs
      :type: ~gi.repository.Pango.TabArray

      The type of the None singleton.







   .. attribute:: props.truncate_multiline
      :type: bool

      The type of the None singleton.







   .. attribute:: props.visibility
      :type: bool

      The type of the None singleton.











Signals
-------

.. rst-class:: interim-class

.. class:: Text.signals
   :no-index:
   

   .. method:: activate() -> None

      Emitted when the user hits the :kbd:`Enter` key.

      The default bindings for this signal are all forms
      of the :kbd:`Enter` key.










   .. method:: backspace() -> None

      The type of the None singleton.










   .. method:: copy_clipboard() -> None

      The type of the None singleton.










   .. method:: cut_clipboard() -> None

      The type of the None singleton.










   .. method:: delete_from_cursor(type: ~gi.repository.Gtk.DeleteType, count: int) -> None

      The type of the None singleton.







      :param type: the granularity of the deletion, as a ``GtkDeleteType``


      :param count: the number of ``type`` units to delete





   .. method:: insert_at_cursor(string: str) -> None

      The type of the None singleton.







      :param string: the string to insert





   .. method:: insert_emoji() -> None

      The type of the None singleton.










   .. method:: move_cursor(step: ~gi.repository.Gtk.MovementStep, count: int, extend: bool) -> None

      The type of the None singleton.







      :param step: the granularity of the move, as a ``GtkMovementStep``


      :param count: the number of ``step`` units to move


      :param extend: :const:`True` if the move should extend the selection





   .. method:: paste_clipboard() -> None

      The type of the None singleton.










   .. method:: preedit_changed(preedit: str) -> None

      The type of the None singleton.







      :param preedit: the current preedit string





   .. method:: toggle_overwrite() -> None

      The type of the None singleton.
















Fields
------

.. rst-class:: interim-class

.. class:: Text
   :no-index:
   

   .. attribute:: parent_instance