Text
Superclasses: Widget
, InitiallyUnowned
, Object
Implemented Interfaces: Accessible
, AccessibleText
, Buildable
, ConstraintTarget
, 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 Entry
, PasswordEntry
,
SpinButton
, and other widgets. In all of these, GtkText
is
used as the delegate for the 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 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
set_invisible_char
.
If you are looking to add icons or progress display in an entry, look
at Entry
. There other alternatives for more specialized use
cases, such as SearchEntry
.
If you need multi-line editable text, look at 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 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
- class Text
-
- classmethod new_with_buffer(buffer: EntryBuffer) Widget
Creates a new
GtkText
with the specified text buffer.- Parameters:
buffer – The buffer to use for the new
GtkText
.
Methods
- class Text
- compute_cursor_extents(position: int) tuple[Rect, 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.
Added in version 4.4.
- Parameters:
position – the character position
- get_activates_default() bool
Returns whether pressing Enter will activate the default widget for the window containing
self
.
- get_attributes() AttrList | None
Gets the attribute list that was set on the
GtkText
.See
set_attributes
.
- get_buffer() EntryBuffer
Get the
GtkEntryBuffer
object which holds the text for this widget.
- get_enable_emoji_completion() bool
Returns whether Emoji completion is enabled for this
GtkText
widget.
Gets the menu model for extra items in the context menu.
See
set_extra_menu
.
- get_input_hints() InputHints
Gets the input hints of the
GtkText
.
- get_input_purpose() InputPurpose
Gets the input purpose of the
GtkText
.
- 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
set_invisible_char
.
- get_max_length() int
Retrieves the maximum allowed length of the text in
self
.See
set_max_length
.This is equivalent to getting
self
’sGtkEntryBuffer
and callingget_max_length
on it.
- get_overwrite_mode() bool
Gets whether text is overwritten when typing in the
GtkText
.See
set_overwrite_mode
.
- get_placeholder_text() str | None
Retrieves the text that will be displayed when
self
is empty and unfocusedIf no placeholder text has been set,
None
will be returned.
- get_propagate_text_width() bool
Returns whether the
GtkText
will grow and shrink with the content.
- get_text_length() int
Retrieves the current length of the text in
self
.This is equivalent to getting
self
’sGtkEntryBuffer
and callingget_length
on it.
- get_truncate_multiline() bool
Returns whether the
GtkText
will truncate multi-line text that is pasted into the widget
- grab_focus_without_selecting() bool
Causes
self
to have keyboard focus.It behaves like
grab_focus
, except that it doesn’t select the contents ofself
. 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.
- set_activates_default(activates: bool) None
If
activates
isTrue
, pressing Enter will activate the default widget for the window containingself
.This usually means that the dialog containing the
GtkText
will be closed, since the default widget is usually one of the dialog buttons.- Parameters:
activates –
True
to activate window’s default widget on Enter keypress
- set_attributes(attrs: AttrList | None = None) None
Sets attributes that are applied to the text.
- Parameters:
attrs – a
PangoAttrList
- set_buffer(buffer: EntryBuffer) None
Set the
GtkEntryBuffer
object which holds the text for this widget.- Parameters:
buffer – a
GtkEntryBuffer
- 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.
- Parameters:
enable_emoji_completion –
True
to enable Emoji completion
Sets a menu model to add when constructing the context menu for
self
.- Parameters:
model – a
GMenuModel
- set_input_hints(hints: InputHints) None
Sets input hints that allow input methods to fine-tune their behaviour.
- Parameters:
hints – the hints
- set_input_purpose(purpose: 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.
- Parameters:
purpose – the purpose
- 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.
- Parameters:
ch – a Unicode character
- 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
’sGtkEntryBuffer
and callingset_max_length
on it.- Parameters:
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.
- set_overwrite_mode(overwrite: bool) None
Sets whether the text is overwritten when typing in the
GtkText
.- Parameters:
overwrite – new value
- 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
.- Parameters:
text – a string to be displayed when
self
is empty and unfocused
- set_propagate_text_width(propagate_text_width: bool) None
Sets whether the
GtkText
should grow and shrink with the content.- Parameters:
propagate_text_width –
True
to propagate the text width
- set_tabs(tabs: TabArray | None = None) None
Sets tabstops that are applied to the text.
- Parameters:
tabs – a
PangoTabArray
- set_truncate_multiline(truncate_multiline: bool) None
Sets whether the
GtkText
should truncate multi-line text that is pasted into the widget.- Parameters:
truncate_multiline –
True
to truncate multi-line text
- set_visibility(visible: bool) None
Sets whether the contents of the
GtkText
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 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
set_invisible_char
.Note that you probably want to set
input_purpose
toPASSWORD
orPIN
to inform input methods about the purpose of this self, in addition to setting visibility toFalse
.- Parameters:
visible –
True
if the contents of theGtkText
are displayed as plaintext
Properties
- class Text
-
- props.attributes: 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
’sstart_index
andend_index
must refer to theGtkEntryBuffer
text, i.e. without the preedit string.
- props.buffer: EntryBuffer
The
GtkEntryBuffer
object which stores the text.
A menu model whose contents will be appended to the context menu.
- props.im_module: str
Which IM (input method) module should be used for this self.
See
IMMulticontext
.Setting this to a non-
None
value overrides the system-wide IM module setting. See thegtk_im_module
property.
- props.input_hints: InputHints
Additional hints that allow input methods to fine-tune their behaviour.
- props.input_purpose: 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
PASSWORD
orPIN
is independent from settingvisibility
.
Signals
- class Text.signals
- activate() None
Emitted when the user hits the Enter key.
The default bindings for this signal are all forms of the Enter key.
- backspace() None
Emitted when the user asks for it.
This is a keybinding signal.
The default bindings for this signal are Backspace and Shift`+:kbd:`Backspace.
- copy_clipboard() None
Emitted to copy the selection to the clipboard.
This is a keybinding signal.
The default bindings for this signal are Ctrl`+:kbd:`c and Ctrl`+:kbd:`Insert.
- cut_clipboard() None
Emitted to cut the selection to the clipboard.
This is a keybinding signal.
The default bindings for this signal are Ctrl`+:kbd:`x and Shift`+:kbd:`Delete.
- delete_from_cursor(type: DeleteType, count: int) None
Emitted when the user initiates a text deletion.
This is a keybinding signal.
If the
type
isCHARS
, GTK deletes the selection if there is one, otherwise it deletes the requested number of characters.The default bindings for this signal are Delete for deleting a character and Ctrl`+:kbd:`Delete for deleting a word.
- Parameters:
type – the granularity of the deletion, as a
GtkDeleteType
count – the number of
type
units to delete
- insert_at_cursor(string: str) None
Emitted when the user initiates the insertion of a fixed string at the cursor.
This is a keybinding signal.
This signal has no default bindings.
- Parameters:
string – the string to insert
- insert_emoji() None
Emitted to present the Emoji chooser for the widget.
This is a keybinding signal.
The default bindings for this signal are :kbd:`Ctrl`+<kbd>.</kbd> and :kbd:`Ctrl`+<kbd>;</kbd>
- move_cursor(step: MovementStep, count: int, extend: bool) None
Emitted when the user initiates a cursor movement.
If the cursor is not visible in
self
, this signal causes the viewport to be moved instead.This is a keybinding signal.
Applications should not connect to it, but may emit it with
signal_emit_by_name()
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 it does not. There are too many key combinations to list them all here.
←, →, ↑, ↓ move by individual characters/lines
Ctrl`+:kbd:`←, etc. move by words/paragraphs
Home and End move to the ends of the buffer
- Parameters:
step – the granularity of the move, as a
GtkMovementStep
count – the number of
step
units to moveextend –
True
if the move should extend the selection
- paste_clipboard() None
Emitted to paste the contents of the clipboard.
This is a keybinding signal.
The default bindings for this signal are Ctrl`+:kbd:`v and Shift`+:kbd:`Insert.
- preedit_changed(preedit: str) None
Emitted when the preedit text changes.
If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, connect to this signal.
- Parameters:
preedit – the current preedit string
- toggle_overwrite() None
Emitted to toggle the overwrite mode of the
GtkText
.This is a keybinding signal.
The default bindings for this signal is Insert.
Fields
- class Text
- parent_instance