The
gtk:text widget is a single line text entry.
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 a text entry for passwords and other sensitive information, it can be put into "password mode" using the
gtk:text-visibility function.
In this mode, entered text is displayed using an "invisible" character. By
default, GTK picks the best invisible character that is available in the current font, but it can be changed with the
gtk:text-invisible-char
function.
If you are looking to add icons or progress display in a text entry, look at the
gtk:entry widget. There other alternatives for more specialized use cases, such as the
gtk:search-entry widget.
If you need multi-line editable text, look at the
gtk:text-view
widget.
CSS nodes
text[.read-only]
├── placeholder
├── undershoot.left
├── undershoot.right
├── [selection]
├── [block-cursor]
╰── [window.popup]
The
gtk:text implementation has a main node with the name
text. Depending on the properties of the widget, the
.read-only style class may appear. When the text entry has a selection, it adds a subnode with the name
selection. When the text
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 below
text as well.
The undershoot nodes are used to draw the underflow indication when content is scrolled out of view. These nodes get the
.left and
.right
style classes 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
.insertion-cursor style class.
Accessibility
The
gtk:text implementation uses the
:none role of the
gtk:accessible-role
enumeration, which causes it to be skipped for accessibility. This is because the
gtk:text implementation is expected to be used as a delegate for a
gtk:editable implementation that will be represented
to accessibility.
Signal Details
The "activate" signal
lambda (entry) :action
- entry
- The gtk:text widget on which the signal is emitted.
The signal is emitted when the user hits the
Enter key. The default bindings for this signal are all forms of the
Enter key.
The "backspace" signal
lambda (entry) :action
- entry
- The gtk:text widget that received the signal.
The signal is a keybinding signal which gets emitted when the user asks for it. The default bindings for this signal are the
Backspace and
Shift-Backspace keys.
The "copy-clipboard" signal
lambda (entry) :action
- entry
- The gtk:text widget that received the signal.
The signal is a keybinding signal which gets emitted to copy the selection
to the clipboard. The default bindings for this signal are the
Ctrl-c and
Ctrl-Insert keys.
The "cut-clipboard" signal
lambda (entry) :action
- entry
- The gtk:text widget that received the signal.
The signal is a keybinding signal which gets emitted to cut the selection
to the clipboard. The default bindings for this signal are the
Ctrl-x and
Shift-Delete keys.
The "delete-from-cursor" signal
lambda (entry type count) :action
- entry
- The gtk:text widget that received the signal.
- type
- The granularity of the deletion as a value of the gtk:delete-type enumeration.
- count
- The integer for the number of type units to delete.
The signal is a keybinding signal which gets emitted when the user initiates a text deletion. If the type is
:chars, GTK deletes the
selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are the
Delete key for deleting a character and the
Ctrl-Delete key for deleting a
word.
The "insert-at-cursor" signal
lambda (entry string) :action
- entry
- The gtk:text widget that received the signal.
- string
- The string to insert.
The signal is a keybinding signal which gets emitted when the user
initiates the insertion of a fixed string at the cursor. This signal has
no default bindings.
The "insert-emoji" signal
lambda (entry) :action
- entry
- The gtk:text widget that received the signal.
The signal is a keybinding signal which gets emitted to present the Emoji
chooser for the text entry. The default bindings for this signal are the
Ctrl-. and
Ctrl-; keys.
The "move-cursor" signal
lambda (entry step count extend) :action
- entry
- The gtk:text widget that received the signal.
- step
- The granularity of the move as a value of the gtk:movement-step enumeration.
- count
- The integer for the number of step units to move.
- extend
- True if the move should extend the selection.
The signal is a keybinding signal which gets emitted when the user
initiates a cursor movement. If the cursor is not visible in the text
entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with the
g:signal-emit
function if they need to control the cursor programmatically. The default
bindings for this signal come in two variants, the variant with the
Shift modifier extends the selection, the variant without the
Shift modifier does not. There are too many key combinations to
list them all here. Arrow keys move by individual characters/lines.
Ctrl-arrow key combinations move by words/paragraphs.
Home/
End keys move to the ends of the text entry.
The "paste-clipboard" signal
lambda (entry) :action
- entry
- The gtk:text widget that received the signal.
The signal is a keybinding signal which gets emitted to paste the contents
of the clipboard into the text entry. The default bindings for this signal are the
Ctrl-v and
Shift-Insert keys.
The "preedit-changed" signal
lambda (entry preedit) :action
- entry
- The gtk:text widget that received the signal.
- preedit
- The current preedit string.
If an input method is used, the typed text will not immediately be
committed to the entry buffer. So if you are interested in the text,
connect to this signal.
The "toggle-overwrite" signal
lambda (entry) :action
- entry
- The gtk:text widget that received the signal.
The signal is a keybinding signal which gets emitted to toggle the
overwrite mode of the text entry. The default bindings for this signal is the
Insert key.
Action Details
- menu.popup}{Opens the context menu.}
@entry[text.redo
- Redoes the last change to the contents.
- text.undo
- Undoes the last change to the contents.
- misc.toggle-visibility
- Toggles the “visibility” property.
- misc.insert-emoji
- Opens the Emoji chooser.
- selection.select-all
- Selects all of the widgets content.
- selection.delete
- Deletes the current selection.
- clipboard.paste
- Inserts the contents of the clipboard into the widget.
- clipboard.copy
- Copies the contents to the clipboard.
- clipboard.cut
- Copies the contents to the clipboard and deletes it from the widget.