Terminal
Superclasses: Widget
, InitiallyUnowned
, Object
Implemented Interfaces: Accessible
, AccessibleText
, Buildable
, ConstraintTarget
, Scrollable
- Constructors:
Terminal(**properties)
new() -> Vte.Terminal
Constructors
Methods
- class Terminal
- check_hyperlink_at(x: float, y: float) str | None
Returns a nonempty string: the target of the explicit hyperlink (printed using the OSC 8 escape sequence) at the position (x, y), or
None
.Proper use of the escape sequence should result in URI-encoded URIs with a proper scheme like “http://”, “https://”, “file://”, “mailto:” etc. This is, however, not enforced by VTE. The caller must tolerate the returned string potentially not being a valid URI.
Added in version 0.70.
- Parameters:
x
y
- check_match_at(x: float, y: float) tuple[str | None, int]
Checks if the text in and around the position (x, y) matches any of the regular expressions previously set using vte_terminal_match_add(). If a match exists, the text string is returned and if
tag
is notNone
, the number associated with the matched regular expression will be stored intag
.If more than one regular expression has been set with vte_terminal_match_add(), then expressions are checked in the order in which they were added.
Added in version 0.70.
- Parameters:
x
y
- check_regex_simple_at(x: float, y: float, regexes: Sequence[Regex], match_flags: int) list[str] | None
Checks each regex in
regexes
if the text in and around the position (x, y) matches the regular expressions. If a match exists, the matched text is stored inmatches
at the position of the regex inregexes
; otherwiseNone
is stored there. Each non-None
element ofmatches
should be freed withfree()
.Note that the regexes in
regexes
should have been created using the%PCRE2_MULTILINE
flag.Added in version 0.70.
- Parameters:
x
y
regexes – an array of
Regex
match_flags – PCRE2 match flags, or 0
- feed(data: Sequence[int] | None = None) None
Interprets
data
as if it were data received from a child process.- Parameters:
data – a string in the terminal’s current encoding
- feed_child(text: Sequence[int] | None = None) None
Sends a block of UTF-8 text to the child as if it were entered by the user at the keyboard.
- Parameters:
text – data to send to the child
- feed_child_binary(data: Sequence[int] | None = None) None
Sends a block of binary data to the child.
Deprecated since version 0.60: Don’t send binary data. Use
feed_child()
instead to send UTF-8 text- Parameters:
data – data to send to the child
- get_allow_bold() bool
Checks whether or not the terminal will attempt to draw bold text, by using a bold font variant.
Deprecated since version 0.60: There’s probably no reason for this feature to exist.
- get_allow_hyperlink() bool
Checks whether or not hyperlinks (OSC 8 escape sequence) are allowed.
Added in version 0.50.
- get_audible_bell() bool
Checks whether or not the terminal will beep when the child outputs the “bl” sequence.
- get_bold_is_bright() bool
Checks whether the SGR 1 attribute also switches to the bright counterpart of the first 8 palette colors, in addition to making them bold (legacy behavior) or if SGR 1 only enables bold and leaves the color intact.
Added in version 0.52.
- get_cjk_ambiguous_width() int
Returns whether ambiguous-width characters are narrow or wide. (Note that when using a non-UTF-8 encoding set via
set_encoding()
, the width of ambiguous-width characters is fixed and determined by the encoding itself.)
- get_color_background_for_draw() RGBA
Returns the background colour, as used by
terminal
when drawing the background, which may be different from the color set byset_color_background()
.Note: you must only call this function while handling the GtkWidget::draw signal.
This function is rarely useful. One use for it is if you disable drawing the background (see
set_clear_background()
) and then need to draw the background yourself.Added in version 0.54.
Added in version 0.76.
Added in version 0.76.
- get_cursor_blink_mode() CursorBlinkMode
Returns the currently set cursor blink mode.
- get_cursor_position() tuple[int, int]
Reads the location of the insertion cursor and returns it. The row coordinate is absolute.
This method is unaware of BiDi. The returned column is logical column.
- get_cursor_shape() CursorShape
Returns the currently set cursor shape.
- get_enable_a11y() bool
Checks whether the terminal communicates with a11y backends
Added in version 0.78.
- get_enable_bidi() bool
Checks whether the terminal performs bidirectional text rendering.
Added in version 0.58.
- get_encoding() str | None
Determines the name of the encoding in which the terminal expects data to be encoded, or
None
if UTF-8 is in use.Deprecated since version 0.54: Support for non-UTF-8 is deprecated.
- get_font() FontDescription
Queries the terminal for information about the fonts which will be used to draw text in the terminal. The actual font takes the font scale into account, this is not reflected in the return value, the unscaled font is returned.
- get_has_selection() bool
Checks if the terminal currently contains selected text. Note that this is different from determining if the terminal is the owner of any
GtkClipboard
items.
- get_icon_title() str | None
Deprecated since version 0.54: Please do not use it in newly written code
- get_mouse_autohide() bool
Determines the value of the terminal’s mouse autohide setting. When autohiding is enabled, the mouse cursor will be hidden when the user presses a key and shown when the user moves the mouse. This setting can be changed using
set_mouse_autohide()
.
- get_rewrap_on_resize() bool
Checks whether or not the terminal will rewrap its contents upon resize.
Deprecated since version 0.58: Please do not use it in newly written code
- get_text(is_selected: Callable[[...], bool] | None = None, *user_data: Any) tuple[str | None, list[CharAttributes]]
Extracts a view of the visible part of the terminal.
This method is unaware of BiDi. The columns returned in
attributes
are logical columns.Note: since 0.68, passing a non-
None
attributes
parameter is deprecated. Starting with 0.72, passing a non-None
attributes
parameter will make this function itself returnNone
. Since 0.72, passing a non-None
is_selected
parameter will make this function itself returnNone
.Deprecated since version 0.76: Use
get_text_format()
instead- Parameters:
is_selected – a
SelectionFunc
callback. Deprecated: 0.44: Always passNone
here.user_data – user data to be passed to the callback
- get_text_blink_mode() TextBlinkMode
Checks whether or not the terminal will allow blinking text.
Added in version 0.52.
- get_text_format(format: Format) str | None
Returns text from the visible part of the terminal in the specified format.
This method is unaware of BiDi. The columns returned in
attributes
are logical columns.Added in version 0.76.
- Parameters:
format – the
Format
to use
- get_text_include_trailing_spaces(is_selected: Callable[[...], bool] | None = None, *user_data: Any) tuple[str, list[CharAttributes]]
Extracts a view of the visible part of the terminal.
This method is unaware of BiDi. The columns returned in
attributes
are logical columns.Note: since 0.68, passing a non-
None
array
parameter is deprecated. Starting with 0.72, passing a non-None
array
parameter will make this function itself returnNone
. Since 0.72, passing a non-None
is_selected
parameter will make this function itself returnNone
.Deprecated since version 0.56: Use
get_text_format()
instead.- Parameters:
is_selected – a
SelectionFunc
callback. Deprecated: 0.44: Always passNone
here.user_data – user data to be passed to the callback
- get_text_range(start_row: int, start_col: int, end_row: int, end_col: int, is_selected: Callable[[...], bool] | None = None, *user_data: Any) tuple[str | None, list[CharAttributes]]
Extracts a view of the visible part of the terminal. The entire scrollback buffer is scanned, so it is possible to read the entire contents of the buffer using this function.
This method is unaware of BiDi. The columns passed in
start_col
andend_row
, and returned inattributes
are logical columns.Since 0.68, passing a non-
None
array
parameter is deprecated. Since 0.72, passing a non-None
array
parameter will make this functionitself return
None
.- Since 0.72, passing a non-
None
is_selected
function will make this function itself return
None
.
Deprecated since version 0.76: Use
get_text_range_format()
instead- Parameters:
start_row – first row to search for data
start_col – first column to search for data
end_row – last row to search for data
end_col – last column to search for data
is_selected – a
SelectionFunc
callback. Deprecated: 0.44: Always passNone
hereuser_data – user data to be passed to the callback
- Since 0.72, passing a non-
- get_text_range_format(format: Format, start_row: int, start_col: int, end_row: int, end_col: int) tuple[str | None, int]
Returns the specified range of text in the specified format.
Added in version 0.72.
- Parameters:
format – the
Format
to usestart_row – the first row of the range
start_col – the first column of the range
end_row – the last row of the range
end_col – the last column of the range
- get_text_selected(format: Format) str | None
Gets the currently selected text in the format specified by
format
. Since 0.72, this function also supportsHTML
format.Added in version 0.70.
- Parameters:
format – the
Format
to use
- get_text_selected_full(format: Format) tuple[str | None, int]
Gets the currently selected text in the format specified by
format
.Added in version 0.72.
- Parameters:
format – the
Format
to use
- get_word_char_exceptions() str | None
Returns the set of characters which will be considered parts of a word when doing word-wise selection, in addition to the default which only considers alphanumeric characters part of a word.
If
None
, a built-in set is used.Added in version 0.40.
- match_add_regex(regex: Regex, flags: int) int
Adds the regular expression
regex
to the list of matching expressions. When the user moves the mouse cursor over a section of displayed text which matches this expression, the text will be highlighted.Note that
regex
should have been created using the <literal>PCRE2_MULTILINE</literal> flag.Added in version 0.46.
- Parameters:
regex – a
Regex
flags – PCRE2 match flags, or 0
- match_check(column: int, row: int) tuple[str | None, int]
Checks if the text in and around the specified position matches any of the regular expressions previously set using vte_terminal_match_add(). If a match exists, the text string is returned and if
tag
is notNone
, the number associated with the matched regular expression will be stored intag
.If more than one regular expression has been set with vte_terminal_match_add(), then expressions are checked in the order in which they were added.
Deprecated since version 0.46: Use vte_terminal_match_check_event() instead.
- Parameters:
column – the text column
row – the text row
- match_remove(tag: int) None
Removes the regular expression which is associated with the given
tag
from the list of expressions which the terminal will highlight when the user moves the mouse cursor over matching text.- Parameters:
tag – the tag of the regex to remove
- match_remove_all() None
Clears the list of regular expressions the terminal uses to highlight text when the user moves the mouse cursor.
- match_set_cursor(tag: int, cursor: Cursor | None = None) None
Sets which cursor the terminal will use if the pointer is over the pattern specified by
tag
. The terminal keeps a reference tocursor
.Deprecated since version 0.40: Use
match_set_cursor_name()
instead.- Parameters:
tag – the tag of the regex which should use the specified cursor
cursor – the
Cursor
which the terminal should use when the pattern is highlighted, orNone
to use the standard cursor
- match_set_cursor_name(tag: int, cursor_name: str) None
Sets which cursor the terminal will use if the pointer is over the pattern specified by
tag
.- Parameters:
tag – the tag of the regex which should use the specified cursor
cursor_name – the name of the cursor
- paste_clipboard() None
Sends the contents of the
GDK_SELECTION_CLIPBOARD
selection to the terminal’s child. It’s called on paste menu item, or when user presses Shift+Insert.
- paste_primary() None
Sends the contents of the
GDK_SELECTION_PRIMARY
selection to the terminal’s child. The terminal will call also paste theGDK_SELECTION_PRIMARY
selection when the user clicks with the the second mouse button.
- paste_text(text: str) None
Sends
text
to the terminal’s child as if retrived from the clipboard, this differs fromfeed_child()
in that it may processtext
before passing it to the child (e.g. apply bracketed mode)Added in version 0.68.
- Parameters:
text – a string to paste
- pty_new_sync(flags: PtyFlags, cancellable: Cancellable | None = None) Pty
Creates a new
Pty
, sets the emulation property fromTerminal
:emulation, and sets the size usingterminal
’s size.See vte_pty_new() for more information.
- Parameters:
flags – flags from
PtyFlags
cancellable – a
Cancellable
, orNone
- reset(clear_tabstops: bool, clear_history: bool) None
Resets as much of the terminal’s internal state as possible, discarding any unprocessed input data, resetting character attributes, cursor state, national character set state, status line, terminal modes (insert/delete), selection state, and encoding.
- Parameters:
clear_tabstops – whether to reset tabstops
clear_history – whether to empty the terminal’s scrollback buffer
- search_find_next() bool
Searches the next string matching the search regex set with
search_set_regex()
.
- search_find_previous() bool
Searches the previous string matching the search regex set with
search_set_regex()
.
- search_set_regex(regex: Regex | None, flags: int) None
Sets the regex to search for. Unsets the search regex when passed
None
.Note that
regex
should have been created using the <literal>PCRE2_MULTILINE</literal> flag.Added in version 0.46.
- Parameters:
regex – a
Regex
, orNone
flags – PCRE2 match flags, or 0
- search_set_wrap_around(wrap_around: bool) None
Sets whether search should wrap around to the beginning of the terminal content when reaching its end.
- Parameters:
wrap_around – whether search should wrap
- set_allow_bold(allow_bold: bool) None
Controls whether or not the terminal will attempt to draw bold text, by using a bold font variant.
Deprecated since version 0.60: There’s probably no reason for this feature to exist.
- Parameters:
allow_bold –
True
if the terminal should attempt to draw bold text
- set_allow_hyperlink(allow_hyperlink: bool) None
Controls whether or not hyperlinks (OSC 8 escape sequence) are allowed.
Added in version 0.50.
- Parameters:
allow_hyperlink –
True
if the terminal should allow hyperlinks
- set_audible_bell(is_audible: bool) None
Controls whether or not the terminal will beep when the child outputs the “bl” sequence.
- Parameters:
is_audible –
True
if the terminal should beep
- set_backspace_binding(binding: EraseBinding) None
Modifies the terminal’s backspace key binding, which controls what string or control sequence the terminal sends to its child when the user presses the backspace key.
- Parameters:
binding – a
EraseBinding
for the backspace key
- set_bold_is_bright(bold_is_bright: bool) None
Sets whether the SGR 1 attribute also switches to the bright counterpart of the first 8 palette colors, in addition to making them bold (legacy behavior) or if SGR 1 only enables bold and leaves the color intact.
Added in version 0.52.
- Parameters:
bold_is_bright –
True
if bold should also enable bright
- set_cell_height_scale(scale: float) None
Sets the terminal’s cell height scale to
scale
.This can be used to increase the line spacing. (The font’s height is not affected.) Valid values go from 1.0 (default) to 2.0 (“double spacing”).
Added in version 0.52.
- Parameters:
scale – the cell height scale
- set_cell_width_scale(scale: float) None
Sets the terminal’s cell width scale to
scale
.This can be used to increase the letter spacing. (The font’s width is not affected.) Valid values go from 1.0 (default) to 2.0.
Added in version 0.52.
- Parameters:
scale – the cell width scale
- set_cjk_ambiguous_width(width: int) None
This setting controls whether ambiguous-width characters are narrow or wide. (Note that when using a non-UTF-8 encoding set via
set_encoding()
, the width of ambiguous-width characters is fixed and determined by the encoding itself.)- Parameters:
width – either 1 (narrow) or 2 (wide)
- set_clear_background(setting: bool) None
Sets whether to paint the background with the background colour. The default is
True
.This function is rarely useful. One use for it is to add a background image to the terminal.
Added in version 0.52.
- Parameters:
setting – whether to clear the background
- set_color_background(background: RGBA) None
Sets the background color for text which does not have a specific background color assigned. Only has effect when no background image is set and when the terminal is not transparent.
- Parameters:
background – the new background color
- set_color_bold(bold: RGBA | None = None) None
Sets the color used to draw bold text in the default foreground color. If
bold
isNone
then the default color is used.- Parameters:
bold – the new bold color or
None
- set_color_cursor(cursor_background: RGBA | None = None) None
Sets the background color for text which is under the cursor. If
None
, text under the cursor will be drawn with foreground and background colors reversed.- Parameters:
cursor_background – the new color to use for the text cursor, or
None
- set_color_cursor_foreground(cursor_foreground: RGBA | None = None) None
Sets the foreground color for text which is under the cursor. If
None
, text under the cursor will be drawn with foreground and background colors reversed.Added in version 0.44.
- Parameters:
cursor_foreground – the new color to use for the text cursor, or
None
- set_color_foreground(foreground: RGBA) None
Sets the foreground color used to draw normal text.
- Parameters:
foreground – the new foreground color
- set_color_highlight(highlight_background: RGBA | None = None) None
Sets the background color for text which is highlighted. If
None
, it is unset. If neither highlight background nor highlight foreground are set, highlighted text (which is usually highlighted because it is selected) will be drawn with foreground and background colors reversed.- Parameters:
highlight_background – the new color to use for highlighted text, or
None
- set_color_highlight_foreground(highlight_foreground: RGBA | None = None) None
Sets the foreground color for text which is highlighted. If
None
, it is unset. If neither highlight background nor highlight foreground are set, highlighted text (which is usually highlighted because it is selected) will be drawn with foreground and background colors reversed.- Parameters:
highlight_foreground – the new color to use for highlighted text, or
None
- set_colors(foreground: RGBA | None = None, background: RGBA | None = None, palette: Sequence[RGBA] | None = None) None
palette
specifies the new values for the 256 palette colors: 8 standard colors, their 8 bright counterparts, 6x6x6 color cube, and 24 grayscale colors. Omitted entries will default to a hardcoded value.palette_size
must be 0, 8, 16, 232 or 256.If
foreground
isNone
andpalette_size
is greater than 0, the new foreground color is taken frompalette``[7]. If ``background
isNone
andpalette_size
is greater than 0, the new background color is taken from ``palette``[0].- Parameters:
foreground – the new foreground color, or
None
background – the new background color, or
None
palette – the color palette
Sets
menu
as the context menu interminal
. UseNone
to unset the current menu.Note that a menu model set with
set_context_menu_model()
takes precedence over a menu set using this function.Added in version 0.76.
- Parameters:
menu – a menu
Sets
model
as the context menu model interminal
. UseNone
to unset the current menu model.Added in version 0.76.
- Parameters:
model – a
MenuModel
- set_cursor_blink_mode(mode: CursorBlinkMode) None
Sets whether or not the cursor will blink. Using
SYSTEM
will use theSettings
::gtk-cursor-blink setting.- Parameters:
mode – the
CursorBlinkMode
to use
- set_cursor_shape(shape: CursorShape) None
Sets the shape of the cursor drawn.
- Parameters:
shape – the
CursorShape
to use
- set_delete_binding(binding: EraseBinding) None
Modifies the terminal’s delete key binding, which controls what string or control sequence the terminal sends to its child when the user presses the delete key.
- Parameters:
binding – a
EraseBinding
for the delete key
- set_enable_a11y(enable_a11y: bool) None
Controls whether or not the terminal will communicate with a11y backends.
Added in version 0.78.
- Parameters:
enable_a11y –
True
to enable a11y support
- set_enable_bidi(enable_bidi: bool) None
Controls whether or not the terminal will perform bidirectional text rendering.
Added in version 0.58.
- Parameters:
enable_bidi –
True
to enable BiDi support
- set_enable_fallback_scrolling(enable: bool) None
Controls whether the terminal uses scroll events to scroll the history if the event was not otherwise consumed by it.
This function is rarely useful, except when the terminal is added to a
ScrolledWindow
, to perform kinetic scrolling (while vte itself does not, yet, implement kinetic scrolling by itself).Added in version 0.64.
- Parameters:
enable – whether to enable fallback scrolling
- set_enable_shaping(enable_shaping: bool) None
Controls whether or not the terminal will shape Arabic text.
Added in version 0.58.
- Parameters:
enable_shaping –
True
to enable Arabic shaping
- set_enable_sixel(enabled: bool) None
Set whether to enable SIXEL images.
Added in version 0.62.
- Parameters:
enabled – whether to enable SIXEL images
- set_encoding(codeset: str | None = None) bool
Changes the encoding the terminal will expect data from the child to be encoded with. For certain terminal types, applications executing in the terminal can change the encoding. If
codeset
isNone
, it uses “UTF-8”.Note: Support for non-UTF-8 is deprecated and may get removed altogether. Instead of this function, you should use a wrapper like luit(1) when spawning the child process.
Deprecated since version 0.54: Support for non-UTF-8 is deprecated.
- Parameters:
codeset – target charset, or
None
to use UTF-8
- set_font(font_desc: FontDescription | None = None) None
Sets the font used for rendering all text displayed by the terminal, overriding any fonts set using gtk_widget_modify_font(). The terminal will immediately attempt to load the desired font, retrieve its metrics, and attempt to resize itself to keep the same number of rows and columns. The font scale is applied to the specified font.
- Parameters:
font_desc – a
FontDescription
for the desired font, orNone
- set_font_options(font_options: FontOptions | None = None) None
Sets the terminal’s font options to
options
.Note that on GTK4, the terminal by default uses font options with
%CAIRO_HINT_METRICS_ON
set; to override that, use this function to set aFontOptions
that has%CAIRO_HINT_METRICS_OFF
set.Added in version 0.74.
- Parameters:
font_options – the font options, or
None
- set_font_scale(scale: float) None
Sets the terminal’s font scale to
scale
.- Parameters:
scale – the font scale
- set_input_enabled(enabled: bool) None
Enables or disables user input. When user input is disabled, the terminal’s child will not receive any key press, or mouse button press or motion events sent to it.
- Parameters:
enabled – whether to enable user input
- set_mouse_autohide(setting: bool) None
Changes the value of the terminal’s mouse autohide setting. When autohiding is enabled, the mouse cursor will be hidden when the user presses a key and shown when the user moves the mouse. This setting can be read using
get_mouse_autohide()
.- Parameters:
setting – whether the mouse pointer should autohide
- set_pty(pty: Pty | None = None) None
Sets
pty
as the PTY to use interminal
. UseNone
to unset the PTY.- Parameters:
pty – a
Pty
, orNone
- set_rewrap_on_resize(rewrap: bool) None
Controls whether or not the terminal will rewrap its contents, including the scrollback history, whenever the terminal’s width changes.
Deprecated since version 0.58: Please do not use it in newly written code
- Parameters:
rewrap –
True
if the terminal should rewrap on resize
- set_scroll_on_insert(scroll: bool) None
Controls whether or not the terminal will forcibly scroll to the bottom of the viewable history when text is inserted, e.g. by a paste.
Added in version 0.76.
- Parameters:
scroll – whether the terminal should scroll on insert
- set_scroll_on_keystroke(scroll: bool) None
Controls whether or not the terminal will forcibly scroll to the bottom of the viewable history when the user presses a key. Modifier keys do not trigger this behavior.
Added in version 0.52.
- Parameters:
scroll – whether the terminal should scroll on keystrokes
- set_scroll_on_output(scroll: bool) None
Controls whether or not the terminal will forcibly scroll to the bottom of the viewable history when the new data is received from the child.
Added in version 0.52.
- Parameters:
scroll – whether the terminal should scroll on output
- set_scroll_unit_is_pixels(enable: bool) None
Controls whether the terminal’s scroll unit is lines or pixels.
This function is rarely useful, except when the terminal is added to a
ScrolledWindow
.Added in version 0.66.
- Parameters:
enable – whether to use pixels as scroll unit
- set_scrollback_lines(lines: int) None
Sets the length of the scrollback buffer used by the terminal. The size of the scrollback buffer will be set to the larger of this value and the number of visible rows the widget can display, so 0 can safely be used to disable scrollback.
A negative value means “infinite scrollback”.
Using a large scrollback buffer (roughly 1M+ lines) may lead to performance degradation or exhaustion of system resources, and is therefore not recommended.
Note that this setting only affects the normal screen buffer. No scrollback is allowed on the alternate screen buffer.
- Parameters:
lines – the length of the history buffer
- set_size(columns: int, rows: int) None
Attempts to change the terminal’s size in terms of rows and columns. If the attempt succeeds, the widget will resize itself to the proper size.
- Parameters:
columns – the desired number of columns
rows – the desired number of rows
- set_text_blink_mode(text_blink_mode: TextBlinkMode) None
Controls whether or not the terminal will allow blinking text.
Added in version 0.52.
- Parameters:
text_blink_mode – the
TextBlinkMode
to use
- set_word_char_exceptions(exceptions: str) None
With this function you can provide a set of characters which will be considered parts of a word when doing word-wise selection, in addition to the default which only considers alphanumeric characters part of a word.
The characters in
exceptions
must be non-alphanumeric, each character must occur only once, and ifexceptions
contains the character U+002D HYPHEN-MINUS, it must be at the start of the string.Use
None
to reset the set of exception characters to the default.Added in version 0.40.
- Parameters:
exceptions – a string of ASCII punctuation characters, or
None
- set_xalign(align: Align) None
Sets the horizontal alignment of
terminal
within its allocation.- Note:
%VTE_ALIGN_START_FILL
is not supported, and will be treated like
START
.
Added in version 0.76.
- Parameters:
align – alignment value from
Align
- Note:
- set_xfill(fill: bool) None
Sets the horizontal fillment of
terminal
within its allocation.- Note:
%VTE_FILL_START_FILL
is not supported, and will be treated like
%VTE_FILL_START
.
Added in version 0.76.
- Parameters:
fill – fillment value from
VteFill
- Note:
- set_yalign(align: Align) None
Sets the vertical alignment of
terminal
within its allocation.Added in version 0.76.
- Parameters:
align – alignment value from
Align
- set_yfill(fill: bool) None
Sets the vertical fillment of
terminal
within its allocation. Note that yfill is only supported with yalign set toSTART
, and is ignored for all other yalign values.Added in version 0.76.
- Parameters:
fill – fillment value from
VteFill
- spawn_async(pty_flags: PtyFlags, working_directory: str | None, argv: Sequence[str], envv: Sequence[str] | None, spawn_flags: SpawnFlags, child_setup: Callable[[...], None] | None, timeout: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
A convenience function that wraps creating the
Pty
and spawning the child process on it. Likespawn_with_fds_async()
, except that this function does not allow passing file descriptors to the child process. Seespawn_with_fds_async()
for more information.Added in version 0.48.
- Parameters:
pty_flags – flags from
PtyFlags
working_directory – the name of a directory the command should start in, or
None
to use the current working directoryargv – child’s argument vector
envv – a list of environment variables to be added to the environment before starting the process, or
None
spawn_flags – flags from
SpawnFlags
child_setup – an extra child setup function to run in the child just before exec(), or
None
timeout – a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely
cancellable – a
Cancellable
, orNone
callback – a
TerminalSpawnAsyncCallback
, orNone
user_data – user data for
callback
, orNone
- spawn_sync(pty_flags: PtyFlags, working_directory: str | None, argv: Sequence[str], envv: Sequence[str] | None, spawn_flags: SpawnFlags, child_setup: Callable[[...], None] | None = None, cancellable: Cancellable | None = None, *child_setup_data: Any) tuple[bool, int]
Starts the specified command under a newly-allocated controlling pseudo-terminal. The
argv
andenvv
lists should beNone
-terminated. The “TERM” environment variable is automatically set to a default value, but can be overridden fromenvv
.pty_flags
controls logging the session to the specified system log files.Note that
%G_SPAWN_DO_NOT_REAP_CHILD
will always be added tospawn_flags
.Note also that
%G_SPAWN_STDOUT_TO_DEV_NULL
,%G_SPAWN_STDERR_TO_DEV_NULL
, and%G_SPAWN_CHILD_INHERITS_STDIN
are not supported inspawn_flags
, since stdin, stdout and stderr of the child process will always be connected to the PTY.Note that all open file descriptors will be closed in the child. If you want to keep some file descriptor open for use in the child process, you need to use a child setup function that unsets the FD_CLOEXEC flag on that file descriptor.
See vte_pty_new(),
spawn_async()
andwatch_child()
for more information.Beginning with 0.52, sets PWD to
working_directory
in order to preserve symlink components. The caller should also make sure that symlinks were preserved while constructing the value ofworking_directory
, e.g. by usingget_current_directory_uri()
,get_current_dir()
or get_current_dir_name().Deprecated since version 0.48: Use
spawn_async()
instead.- Parameters:
pty_flags – flags from
PtyFlags
working_directory – the name of a directory the command should start in, or
None
to use the current working directoryargv – child’s argument vector
envv – a list of environment variables to be added to the environment before starting the process, or
None
spawn_flags – flags from
SpawnFlags
child_setup – an extra child setup function to run in the child just before exec(), or
None
cancellable – a
Cancellable
, orNone
child_setup_data – user data for
child_setup
- spawn_with_fds_async(pty_flags: PtyFlags, working_directory: str | None, argv: Sequence[str], envv: Sequence[str] | None, fds: Sequence[int] | None, map_fds: Sequence[int] | None, spawn_flags: SpawnFlags, child_setup: Callable[[...], None] | None, timeout: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
A convenience function that wraps creating the
Pty
and spawning the child process on it. Seenew_sync()
,spawn_with_fds_async()
, andspawn_finish()
for more information.When the operation is finished successfully,
callback
will be called with the childPid
, and aNone
Error
. The child PID will already be watched viawatch_child()
.When the operation fails,
callback
will be called with a -1Pid
, and a non-None
Error
containing the error information.Note that
%G_SPAWN_STDOUT_TO_DEV_NULL
,%G_SPAWN_STDERR_TO_DEV_NULL
, and%G_SPAWN_CHILD_INHERITS_STDIN
are not supported inspawn_flags
, since stdin, stdout and stderr of the child process will always be connected to the PTY.If
fds
is notNone
, the child process will map the file descriptors fromfds
according tomap_fds
;n_map_fds
must be less or equal ton_fds
. This function will take ownership of the file descriptors infds
; you must not use or close them after this call.Note that all open file descriptors apart from those mapped as above will be closed in the child. (If you want to keep some other file descriptor open for use in the child process, you need to use a child setup function that unsets the FD_CLOEXEC flag on that file descriptor manually.)
Beginning with 0.60, and on linux only, and unless
SPAWN_NO_SYSTEMD_SCOPE
is passed inspawn_flags
, the newly created child process will be moved to its own systemd user scope; and ifSPAWN_REQUIRE_SYSTEMD_SCOPE
is passed, and creation of the systemd user scope fails, the whole spawn will fail. You can override the options used for the systemd user scope by providing a systemd override file for ‘vte-spawn-.scope’ unit. See man:systemd.unit(5) for further information.Note that if
terminal
has been destroyed before the operation is called,callback
will be called with aNone
terminal
; you must not do anything in the callback besides freeing any resources associated withuser_data
, but taking care not to access the now-destroyedTerminal
. Note that in this case, if spawning was successful, the child process will be aborted automatically.Beginning with 0.52, sets PWD to
working_directory
in order to preserve symlink components. The caller should also make sure that symlinks were preserved while constructing the value ofworking_directory
, e.g. by usingget_current_directory_uri()
,get_current_dir()
or get_current_dir_name().Added in version 0.62.
- Parameters:
pty_flags – flags from
PtyFlags
working_directory – the name of a directory the command should start in, or
None
to use the current working directoryargv – child’s argument vector
envv – a list of environment variables to be added to the environment before starting the process, or
None
fds – an array of file descriptors, or
None
map_fds – an array of integers, or
None
spawn_flags – flags from
SpawnFlags
child_setup – an extra child setup function to run in the child just before exec(), or
None
timeout – a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely
cancellable – a
Cancellable
, orNone
callback – a
TerminalSpawnAsyncCallback
, orNone
user_data – user data for
callback
, orNone
- watch_child(child_pid: int) None
Watches
child_pid
. When the process exists, theTerminal
::child-exited signal will be called with the child’s exit status.Prior to calling this function, a
Pty
must have been set interminal
usingset_pty()
. When the child exits, the terminal’sPty
will be set toNone
.Note:
child_watch_add()
orchild_watch_add_full()
must not have been called forchild_pid
, nor aSource
for it been created withchild_watch_source_new()
.Note: when using the
spawn_async()
family of functions, the%G_SPAWN_DO_NOT_REAP_CHILD
flag MUST have been passed.- Parameters:
child_pid – a
Pid
- write_contents_sync(stream: OutputStream, flags: WriteFlags, cancellable: Cancellable | None = None) bool
Write contents of the current contents of
terminal
(including any scrollback history) tostream
according toflags
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error%G_IO_ERROR_CANCELLED
will be returned inerror
.This is a synchronous operation and will make the widget (and input processing) during the write operation, which may take a long time depending on scrollback history and
stream
availability for writing.- Parameters:
stream – a
OutputStream
to write toflags – a set of
WriteFlags
cancellable – a
Cancellable
object, orNone
Properties
- class Terminal
- props.allow_bold: bool
Controls whether or not the terminal will attempt to draw bold text, by using a bold font variant.
Deprecated since version 0.60: There’s probably no reason for this feature to exist.
- props.allow_hyperlink: bool
Controls whether or not hyperlinks (OSC 8 escape sequence) are recognized and displayed.
Added in version 0.50.
- props.audible_bell: bool
Controls whether or not the terminal will beep when the child outputs the “bl” sequence.
- props.backspace_binding: EraseBinding
Controls what string or control sequence the terminal sends to its child when the user presses the backspace key.
- props.bold_is_bright: bool
Whether the SGR 1 attribute also switches to the bright counterpart of the first 8 palette colors, in addition to making them bold (legacy behavior) or if SGR 1 only enables bold and leaves the color intact.
Added in version 0.52.
- props.cell_height_scale: float
Scale factor for the cell height, to increase line spacing. (The font’s height is not affected.)
Added in version 0.52.
- props.cell_width_scale: float
Scale factor for the cell width, to increase letter spacing. (The font’s width is not affected.)
Added in version 0.52.
- props.cjk_ambiguous_width: int
This setting controls whether ambiguous-width characters are narrow or wide. (Note that when using a non-UTF-8 encoding set via
set_encoding()
, the width of ambiguous-width characters is fixed and determined by the encoding itself.)This setting only takes effect the next time the terminal is reset, either via escape sequence or with
reset()
.
The menu used for context menus. Note that context menu model set with the
Terminal
::context-menu-model property orset_context_menu_model()
takes precedence over this.Added in version 0.76.
The menu model used for context menus. If non-
None
, the context menu is generated from this model, and overrides a context menu set with theTerminal
::context-menu property orset_context_menu()
.Added in version 0.76.
- props.cursor_blink_mode: CursorBlinkMode
Sets whether or not the cursor will blink. Using
SYSTEM
will use theSettings
:gtk-cursor-blink setting.
- props.cursor_shape: CursorShape
Controls the shape of the cursor.
- props.delete_binding: EraseBinding
Controls what string or control sequence the terminal sends to its child when the user presses the delete key.
- props.enable_a11y: bool
Controls whether or not a11y is enabled for the widget.
Added in version 0.78.
- props.enable_bidi: bool
Controls whether or not the terminal will perform bidirectional text rendering.
Added in version 0.58.
- props.enable_shaping: bool
Controls whether or not the terminal will shape Arabic text.
Added in version 0.58.
- props.encoding: str
Controls the encoding the terminal will expect data from the child to be encoded with. For certain terminal types, applications executing in the terminal can change the encoding. The default is defined by the application’s locale settings.
Deprecated since version 0.54: Instead of using this, you should use a tool like luit(1) when support for non-UTF-8 is required
- props.font_desc: FontDescription
Specifies the font used for rendering all text displayed by the terminal, overriding any fonts set using gtk_widget_modify_font(). The terminal will immediately attempt to load the desired font, retrieve its metrics, and attempt to resize itself to keep the same number of rows and columns.
- props.font_options: FontOptions
The terminal’s font options, or
None
to use the default font options.Note that on GTK4, the terminal by default uses font options with
%CAIRO_HINT_METRICS_ON
set; to override that, use this function to set aFontOptions
that has%CAIRO_HINT_METRICS_OFF
set.Added in version 0.74.
- props.hyperlink_hover_uri: str
The currently hovered hyperlink URI, or
None
if unset.Added in version 0.50.
- props.input_enabled: bool
Controls whether the terminal allows user input. When user input is disabled, key press and mouse button press and motion events are not sent to the terminal’s child.
- props.pointer_autohide: bool
Controls the value of the terminal’s mouse autohide setting. When autohiding is enabled, the mouse cursor will be hidden when the user presses a key and shown when the user moves the mouse.
- props.rewrap_on_resize: bool
Controls whether or not the terminal will rewrap its contents, including the scrollback buffer, whenever the terminal’s width changes.
Deprecated since version 0.58: Please do not use it in newly written code
- props.scroll_on_insert: bool
Controls whether or not the terminal will forcibly scroll to the bottom of the viewable history when the text is inserted (e.g. by a paste).
Added in version 0.76.
- props.scroll_on_keystroke: bool
Controls whether or not the terminal will forcibly scroll to the bottom of the viewable history when the user presses a key. Modifier keys do not trigger this behavior.
- props.scroll_on_output: bool
Controls whether or not the terminal will forcibly scroll to the bottom of the viewable history when the new data is received from the child.
- props.scroll_unit_is_pixels: bool
Controls whether the terminal’s GtkAdjustment values unit is lines or pixels. This can be enabled when the terminal is the child of a GtkScrolledWindow to fix some bugs with its kinetic scrolling.
Added in version 0.66.
- props.scrollback_lines: int
The length of the scrollback buffer used by the terminal. The size of the scrollback buffer will be set to the larger of this value and the number of visible rows the widget can display, so 0 can safely be used to disable scrollback. Note that this setting only affects the normal screen buffer. For terminal types which have an alternate screen buffer, no scrollback is allowed on the alternate screen buffer.
- props.text_blink_mode: TextBlinkMode
Controls whether or not the terminal will allow blinking text.
Added in version 0.52.
- props.word_char_exceptions: str
The set of characters which will be considered parts of a word when doing word-wise selection, in addition to the default which only considers alphanumeric characters part of a word.
If
None
, a built-in set is used.Added in version 0.40.
- props.xalign: Align
The horizontal alignment of
terminal
within its allocation.Added in version 0.76.
- props.xfill: bool
The horizontal fillment of
terminal
within its allocation.Added in version 0.76.
Signals
- class Terminal.signals
-
- char_size_changed(width: int, height: int) None
Emitted whenever the cell size changes, e.g. due to a change in font, font-scale or cell-width/height-scale.
Note that this signal should rather be called “cell-size-changed”.
- Parameters:
width – the new character cell width
height – the new character cell height
- child_exited(status: int) None
This signal is emitted when the terminal detects that a child watched using
watch_child()
has exited.- Parameters:
status – the child’s exit status
- commit(text: str, size: int) None
Emitted whenever the terminal receives input from the user and prepares to send it to the child process.
- Parameters:
text – a string of text
size – the length of that string of text
- contents_changed() None
Emitted whenever the visible appearance of the terminal has changed. Used primarily by
VteTerminalAccessible
.
- cursor_moved() None
Emitted whenever the cursor moves to a new character cell. Used primarily by
VteTerminalAccessible
.
- deiconify_window() None
Never emitted.
Deprecated since version 0.60: Please do not use it in newly written code
- encoding_changed() None
Emitted whenever the terminal’s current encoding has changed.
Note: support for non-UTF-8 is deprecated.
- eof() None
Emitted when the terminal receives an end-of-file from a child which is running in the terminal. This signal is frequently (but not always) emitted with a
Terminal
::child-exited signal.
- hyperlink_hover_uri_changed(uri: str, bbox: Rectangle) None
Emitted when the hovered hyperlink changes.
uri
andbbox
are owned by VTE, must not be modified, and might change after the signal handlers returns.The signal is not re-emitted when the bounding box changes for the same hyperlink. This might change in a future VTE version without notice.
Added in version 0.50.
- Parameters:
uri – the nonempty target URI under the mouse, or NULL
bbox – the bounding box of the hyperlink anchor text, or NULL
- iconify_window() None
Never emitted.
Deprecated since version 0.60: Please do not use it in newly written code
- lower_window() None
Never emitted.
Deprecated since version 0.60: Please do not use it in newly written code
- maximize_window() None
Never emitted.
Deprecated since version 0.60: Please do not use it in newly written code
- move_window(x: int, y: int) None
Never emitted.
Deprecated since version 0.60: Please do not use it in newly written code
- Parameters:
x – the terminal’s desired location, X coordinate
y – the terminal’s desired location, Y coordinate
- paste_clipboard() None
Emitted whenever
paste_clipboard()
is called.
- raise_window() None
Never emitted.
Deprecated since version 0.60: Please do not use it in newly written code
- refresh_window() None
Never emitted.
Deprecated since version 0.60: Please do not use it in newly written code
- resize_window(width: int, height: int) None
Emitted at the child application’s request.
- Parameters:
width – the desired number of columns
height – the desired number of rows
- restore_window() None
Never emitted.
Deprecated since version 0.60: Please do not use it in newly written code
Emitted with non-
None
context beforeterminal
shows a context menu. The handler may set either a menu model usingset_context_menu_model()
, or a menu usingset_context_menu()
, which will then be used as context menu. If neither a menu model nor a menu are set, a context menu will not be shown.Note that
context
is only valid during the signal emission; you may not retain it to call methods on it afterwards.Also emitted with
None
context after the context menu has been dismissed.- Parameters:
context – the context
Virtual Methods
- class Terminal
-
- do_copy_clipboard() None
Places the selected text in the terminal in the
GDK_SELECTION_CLIPBOARD
selection.Deprecated since version 0.50: Use
copy_clipboard_format()
withTEXT
instead.
- do_paste_clipboard() None
Sends the contents of the
GDK_SELECTION_CLIPBOARD
selection to the terminal’s child. It’s called on paste menu item, or when user presses Shift+Insert.
- Parameters:
context
Fields
- class Terminal
- widget