Terminal#

class Terminal(**properties: Any)#

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, AccessibleText, Buildable, ConstraintTarget, Scrollable

Constructors:

Terminal(**properties)
new() -> Vte.Terminal

Constructors#

class Terminal

classmethod new() → Terminal#: Creates a new terminal widget.

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:

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 not None, the number associated with the matched regular expression will be stored in tag.

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:

check_regex_simple_at(x: float, y: float, regexes: list[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 in matches at the position of the regex in regexes; otherwise None is stored there. Each non-None element of matches should be freed with free().

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

do_bell(self) → None#

do_char_size_changed(self, char_width: int, char_height: int) → None#

Parameters:

char_width
char_height

do_child_exited(self, status: int) → None#

Parameters:: status

do_commit(self, text: str, size: int) → None#

Parameters:

text
size

do_contents_changed(self) → None#

do_cursor_moved(self) → None#

do_decrease_font_size(self) → None#

do_deiconify_window(self) → None#

do_encoding_changed(self) → None#

do_eof(self) → None#

do_icon_title_changed(self) → None#

do_iconify_window(self) → None#

do_increase_font_size(self) → None#

do_lower_window(self) → None#

do_maximize_window(self) → None#

do_move_window(self, x: int, y: int) → None#

Parameters:

do_paste_clipboard(self) → None#

do_raise_window(self) → None#

do_refresh_window(self) → None#

do_resize_window(self, width: int, height: int) → None#

Parameters:

width
height

do_restore_window(self) → None#

do_selection_changed(self) → None#

do_setup_context_menu(self, context: EventContext) → None#

Parameters:: context

do_termprop_changed(self, prop: str) → None#

Parameters:: prop

do_termprops_changed(self, props: int, n_props: int) → bool#

Parameters:

props
n_props

do_window_title_changed(self) → None#

dup_termprop_string(prop: str) → tuple[str | None, int]#

Returns the value of a STRING termprop, or None if: prop is unset, or prop is not a registered property.

Added in version 0.78.

Parameters:: prop – a termprop name

dup_termprop_string_by_id(prop: int) → tuple[str | None, int]#

Like dup_termprop_string() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

dup_termprop_uuid(prop: str) → Uuid#

Returns the value of a UUID termprop as a Uuid, or None if: prop is unset, or prop is not a registered property.

Added in version 0.78.

Parameters:: prop – a termprop name

dup_termprop_uuid_by_id(prop: int) → Uuid#

Like dup_termprop_uuid() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

feed(data: list[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: list[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: list[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_cell_height_scale() → float#: Added in version 0.52.

get_cell_width_scale() → float#: Added in version 0.52.

get_char_height() → int#

get_char_width() → int#

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 by set_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.

get_column_count() → int#

get_context_menu() → Widget | None#: Added in version 0.76.

get_context_menu_model() → MenuModel | None#: Added in version 0.76.

get_current_directory_uri() → str | None#: Deprecated since version 0.78: Use the %VTE_TERMPROP_CURRENT_FILE_URI_STRING termprop.

get_current_file_uri() → str | None#: Deprecated since version 0.78: Use the %VTE_TERMPROP_CURRENT_FILE_URI_STRING termprop.

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_enable_fallback_scrolling() → bool#: Added in version 0.64.

get_enable_legacy_osc777() → bool#: Added in version 0.78.

get_enable_shaping() → bool#: Checks whether the terminal shapes Arabic text.

Added in version 0.58.

get_enable_sixel() → bool#: Added in version 0.62.

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_font_options() → FontOptions | None#: Added in version 0.74.

get_font_scale() → float#

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_input_enabled() → bool#: Returns whether the terminal allow user input.

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_pty() → Pty#: Returns the Pty of terminal.

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_row_count() → int#

get_scroll_on_insert() → bool#: Added in version 0.76.

get_scroll_on_keystroke() → bool#: Added in version 0.52.

get_scroll_on_output() → bool#: Added in version 0.52.

get_scroll_unit_is_pixels() → bool#: Added in version 0.66.

get_scrollback_lines() → int#: Added in version 0.52.

get_termprop_bool(prop: str) → tuple[bool, bool]#

For a BOOL termprop, sets value to prop's value,: or to False if prop is unset, or prop is not a registered property.

Added in version 0.78.

Parameters:: prop – a termprop name

get_termprop_bool_by_id(prop: int) → tuple[bool, bool]#

Like get_termprop_bool() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

get_termprop_data(prop: str) → list[int]#

Returns the value of a DATA termprop, or None if: prop is unset, or prop is not a registered property.

Added in version 0.78.

Parameters:: prop – a termprop name

get_termprop_data_by_id(prop: int) → list[int]#

Like get_termprop_data() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

get_termprop_double(prop: str) → tuple[bool, float]#

For a DOUBLE termprop, sets value to prop's value,: which is finite; or to 0.0 if prop is unset, or prop is not a registered property.

Added in version 0.78.

Parameters:: prop – a termprop name

get_termprop_double_by_id(prop: int) → tuple[bool, float]#

Like get_termprop_double() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

get_termprop_int(prop: str) → tuple[bool, int]#

For a INT termprop, sets value to prop's value, or to 0 if prop is unset, or if prop is not a registered property.

If only a subset or range of values are acceptable for the given property, the caller must validate the returned value and treat any out-of-bounds value as if the termprop had no value; in particular it must not clamp the values to the expected range.

Added in version 0.78.

Parameters:: prop – a termprop name

get_termprop_int_by_id(prop: int) → tuple[bool, int]#

Like get_termprop_int() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

get_termprop_rgba(prop: str) → tuple[bool, RGBA]#

Stores the value of a RGB or RGBA termprop in color and returns True if the termprop is set, or stores rgb(0,0,0) or rgba(0,0,0,1) in color and returns False if the termprop is unset.

Added in version 0.78.

Parameters:: prop – a termprop name

get_termprop_rgba_by_id(prop: int) → tuple[bool, RGBA]#

Like get_termprop_rgba() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

get_termprop_string(prop: str) → tuple[str | None, int]#

Returns the value of a STRING termprop, or None if: prop is unset, or prop is not a registered property.

Added in version 0.78.

Parameters:: prop – a termprop name

get_termprop_string_by_id(prop: int) → tuple[str | None, int]#

Like get_termprop_string() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

get_termprop_uint(prop: str) → tuple[bool, int]#

For a UINT termprop, sets value to prop's value, or to 0 if prop is unset, or prop is not a registered property.

Added in version 0.78.

Parameters:: prop – a termprop name

get_termprop_uint_by_id(prop: int) → tuple[bool, int]#

Like get_termprop_uint() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

get_termprop_value(prop: str) → tuple[bool, Value]#

Returns True with the value of prop stored in value (if not None) if,: the termprop has a value, or False if prop is unset, or prop is not a registered property; in that case value will not be set.

The value type returned depends on the termprop type: * A VALUELESS termprop stores no value, and returns False

from this function.

* A BOOL termprop stores a bool value. * A INT termprop stores a int value. * A UINT termprop stores a unsigned int value. * A DOUBLE termprop stores a float value. * A RGB termprop stores a boxed RGBA value with alpha 1.0 on gtk3,

and nothing on gtk4.

* A RGBA termprop stores a boxed RGBA value on gtk3,: and nothing on gtk4.

* A STRING termprop stores a str value. * A DATA termprop stores a boxed Bytes value. * A UUID termprop stores a boxed Uuid value. * A URI termprop stores a boxed Uri value.

Added in version 0.78.

Parameters:: prop – a termprop name

get_termprop_value_by_id(prop: int) → tuple[bool, Value]#

Like get_termprop_value() except that it takes the termprop by ID. See that function for more information.

Added in version 0.78.

Parameters:: prop – a termprop ID

get_text(is_selected: Callable[[Terminal, int, int, Any], bool] | None = None, user_data: Any = None) → tuple[str | None, list[CharAttributes] | None]#

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 return None. Since 0.72, passing a non-None is_selected parameter will make this function itself return None.

Deprecated since version 0.76: Use get_text_format() instead

Parameters:

is_selected – a SelectionFunc callback. Deprecated: 0.44: Always pass None 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[[Terminal, int, int, Any], bool] | None = None, user_data: Any = None) → tuple[str, list[CharAttributes] | None]#

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 return None. Since 0.72, passing a non-None is_selected parameter will make this function itself return None.

Deprecated since version 0.56: Use get_text_format() instead.

Parameters:

is_selected – a SelectionFunc callback. Deprecated: 0.44: Always pass None 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[[Terminal, int, int, Any], bool] | None = None, user_data: Any = None) → tuple[str | None, list[CharAttributes] | None]#

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 and end_row, and returned in attributes 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 function

itself 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 pass None here
user_data – user data to be passed to the callback

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 use
start_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 supports HTML 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_window_title() → str | None#: Deprecated since version 0.78: Use the TERMPROP_XTERM_TITLE termprop.

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.

get_xalign() → Align#: Added in version 0.76.

get_xfill() → bool#: Added in version 0.76.

get_yalign() → Align#: Added in version 0.76.

get_yfill() → bool#: Added in version 0.76.

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 PCRE2_MULTILINE 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 not None, the number associated with the matched regular expression will be stored in tag.

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 to cursor.

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, or None 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 the GDK_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 from feed_child() in that it may process text 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 from Terminal:emulation, and sets the size using terminal's size.

See vte_pty_new() for more information.

Parameters:

flags – flags from PtyFlags
cancellable – a Cancellable, or None

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_get_regex() → Regex#: Added in version 0.46.

search_get_wrap_around() → bool#

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 PCRE2_MULTILINE flag.

Added in version 0.46.

Parameters:

regex – a Regex, or None
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

select_all() → None#: Selects all text within the terminal (not including the scrollback buffer).

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 is None 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: list[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 is None and palette_size is greater than 0, the new foreground color is taken from palette[7]. If background is None and palette_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

set_context_menu(menu: Widget | None = None) → None#

Sets menu as the context menu in terminal. Use None 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

set_context_menu_model(model: MenuModel | None = None) → None#

Sets model as the context menu model in terminal. Use None 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 the Settings::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_default_colors() → None#: Reset the terminal palette to reasonable compiled-in default color.

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_legacy_osc777(enable: bool) → None#

Sets whether legacy OSC 777 sequences are translated to their corresponding termprops.

Added in version 0.78.

Parameters:: enable – whether to enable legacy OSC 777

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 is None, 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, or None

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 a FontOptions 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 in terminal. Use None to unset the PTY.

Parameters:: pty – a Pty, or None

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_suppress_legacy_signals() → None#: Suppress emissions of signals and property notifications that are deprecated.

Added in version 0.78.

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 if exceptions 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

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

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 to START, 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: list[str], envv: list[str] | None, spawn_flags: SpawnFlags, child_setup: Callable[[Any], None] | None, timeout: int, cancellable: Cancellable | None = None, callback: Callable[[Terminal, int, GError | None, Any], None] | None = None, user_data: Any = None) → None#

A convenience function that wraps creating the Pty and spawning the child process on it. Like spawn_with_fds_async(), except that this function does not allow passing file descriptors to the child process. See spawn_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 directory
argv – 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, or None
callback – a TerminalSpawnAsyncCallback, or None
user_data – user data for callback, or None

spawn_sync(pty_flags: PtyFlags, working_directory: str | None, argv: list[str], envv: list[str] | None, spawn_flags: SpawnFlags, child_setup: Callable[[Any], None] | None = None, child_setup_data: Any = None, cancellable: Cancellable | None = None) → tuple[bool, int]#

Starts the specified command under a newly-allocated controlling pseudo-terminal. The argv and envv lists should be None-terminated. The “TERM” environment variable is automatically set to a default value, but can be overridden from envv. pty_flags controls logging the session to the specified system log files.

Note that %G_SPAWN_DO_NOT_REAP_CHILD will always be added to spawn_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 in spawn_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() and watch_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 of working_directory, e.g. by using get_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 directory
argv – 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
child_setup_data – user data for child_setup
cancellable – a Cancellable, or None

spawn_with_fds_async(pty_flags: PtyFlags, working_directory: str | None, argv: list[str], envv: list[str] | None, fds: list[int] | None, map_fds: list[int] | None, spawn_flags: SpawnFlags, child_setup: Callable[[Any], None] | None, timeout: int, cancellable: Cancellable | None = None, callback: Callable[[Terminal, int, GError | None, Any], None] | None = None, user_data: Any = None) → None#

A convenience function that wraps creating the Pty and spawning the child process on it. See new_sync(), spawn_with_fds_async(), and spawn_finish() for more information.

When the operation is finished successfully, callback will be called with the child Pid, and a None Error. The child PID will already be watched via watch_child().

When the operation fails, callback will be called with a -1 Pid, 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 in spawn_flags, since stdin, stdout and stderr of the child process will always be connected to the PTY.

If fds is not None, the child process will map the file descriptors from fds according to map_fds; n_map_fds must be less or equal to n_fds. This function will take ownership of the file descriptors in fds; 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 in spawn_flags, the newly created child process will be moved to its own systemd user scope; and if SPAWN_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 a None terminal; you must not do anything in the callback besides freeing any resources associated with user_data, but taking care not to access the now-destroyed Terminal. Note that in this case, if spawning was successful, the child process will be aborted automatically.

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 directory
argv – 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, or None
callback – a TerminalSpawnAsyncCallback, or None
user_data – user data for callback, or None

unselect_all() → None#: Clears the current selection.

watch_child(child_pid: int) → None#

Watches child_pid. When the process exists, the Terminal::child-exited signal will be called with the child’s exit status.

Prior to calling this function, a Pty must have been set in terminal using set_pty(). When the child exits, the terminal’s Pty will be set to None.

Note: child_watch_add() or child_watch_add_full() must not have been called for child_pid, nor a Source for it been created with child_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) to stream according to flags.

If cancellable is not None, 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 in error.

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 to
flags – a set of WriteFlags
cancellable – a Cancellable object, or None

Properties#

class Terminal

props.allow_bold: bool#: The type of the None singleton.

Deprecated since version 0.60: There’s probably no reason for this feature to exist.

props.allow_hyperlink: bool#: The type of the None singleton.

Added in version 0.50.

props.audible_bell: bool#: The type of the None singleton.

props.backspace_binding: EraseBinding#: The type of the None singleton.

props.bold_is_bright: bool#: The type of the None singleton.

Added in version 0.52.

props.cell_height_scale: float#: The type of the None singleton.

Added in version 0.52.

props.cell_width_scale: float#: The type of the None singleton.

Added in version 0.52.

props.cjk_ambiguous_width: int#: The type of the None singleton.

props.context_menu: Popover#: The type of the None singleton.

Added in version 0.76.

props.context_menu_model: MenuModel#: The type of the None singleton.

Added in version 0.76.

props.current_directory_uri: str#: The type of the None singleton.

Deprecated since version 0.78: Use the TERMPROP_CURRENT_DIRECTORY_URI termprop.

props.current_file_uri: str#: The type of the None singleton.

Deprecated since version 0.78: Use the TERMPROP_CURRENT_FILE_URI termprop.

props.cursor_blink_mode: CursorBlinkMode#: The type of the None singleton.

props.cursor_shape: CursorShape#: The type of the None singleton.

props.delete_binding: EraseBinding#: The type of the None singleton.

props.enable_a11y: bool#: The type of the None singleton.

Added in version 0.78.

props.enable_bidi: bool#: The type of the None singleton.

Added in version 0.58.

props.enable_fallback_scrolling: bool#: The type of the None singleton.

props.enable_legacy_osc777: bool#: The type of the None singleton.

Added in version 0.78.

props.enable_shaping: bool#: The type of the None singleton.

Added in version 0.58.

props.enable_sixel: bool#: The type of the None singleton.

Added in version 0.62.

props.encoding: str#

The type of the None singleton.

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#: The type of the None singleton.

props.font_options: FontOptions#: The type of the None singleton.

Added in version 0.74.

props.font_scale: float#: The type of the None singleton.

props.hyperlink_hover_uri: str#: The type of the None singleton.

Added in version 0.50.

props.icon_title: str#: The type of the None singleton.

Deprecated since version 0.54: This property is always None.

props.input_enabled: bool#: The type of the None singleton.

props.pointer_autohide: bool#: The type of the None singleton.

props.pty: Pty#: The type of the None singleton.

props.rewrap_on_resize: bool#: The type of the None singleton.

Deprecated since version 0.58: Please do not use it in newly written code

props.scroll_on_insert: bool#: The type of the None singleton.

Added in version 0.76.

props.scroll_on_keystroke: bool#: The type of the None singleton.

props.scroll_on_output: bool#: The type of the None singleton.

props.scroll_unit_is_pixels: bool#: The type of the None singleton.

Added in version 0.66.

props.scrollback_lines: int#: The type of the None singleton.

props.text_blink_mode: TextBlinkMode#: The type of the None singleton.

Added in version 0.52.

props.window_title: str#: The type of the None singleton.

Deprecated since version 0.78: Use the TERMPROP_XTERM_TITLE termprop.

props.word_char_exceptions: str#: The type of the None singleton.

Added in version 0.40.

props.xalign: Align#: The type of the None singleton.

Added in version 0.76.

props.xfill: bool#: The type of the None singleton.

Added in version 0.76.

props.yalign: Align#: The type of the None singleton.

Added in version 0.76.

props.yfill: bool#: The type of the None singleton.

Added in version 0.76.

Signals#

class Terminal.signals

bell() → None#: The type of the None singleton.

char_size_changed(width: int, height: int) → None#

The type of the None singleton.

Parameters:

width – the new character cell width
height – the new character cell height

child_exited(status: int) → None#

The type of the None singleton.

Parameters:: status – the child’s exit status

commit(text: str, size: int) → None#

The type of the None singleton.

Parameters:

text – a string of text
size – the length of that string of text

contents_changed() → None#: The type of the None singleton.

copy_clipboard() → None#: The type of the None singleton.

current_directory_uri_changed() → None#

The type of the None singleton.

Deprecated since version 0.78:

Use the Terminal:termprop-changed signal: for the TERMPROP_CURRENT_DIRECTORY_URI termprop.

current_file_uri_changed() → None#

The type of the None singleton.

Deprecated since version 0.78:

Use the Terminal:termprop-changed signal: for the TERMPROP_CURRENT_FILE_URI termprop.

cursor_moved() → None#: The type of the None singleton.

decrease_font_size() → None#: The type of the None singleton.

deiconify_window() → None#: The type of the None singleton.

Deprecated since version 0.60: Please do not use it in newly written code

encoding_changed() → None#: The type of the None singleton.

eof() → None#: The type of the None singleton.

hyperlink_hover_uri_changed(uri: str, bbox: Rectangle) → None#

The type of the None singleton.

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

icon_title_changed() → None#: The type of the None singleton.

Deprecated since version 0.54: This signal is never emitted.

iconify_window() → None#: The type of the None singleton.

Deprecated since version 0.60: Please do not use it in newly written code

increase_font_size() → None#: The type of the None singleton.

lower_window() → None#: The type of the None singleton.

Deprecated since version 0.60: Please do not use it in newly written code

maximize_window() → None#: The type of the None singleton.

Deprecated since version 0.60: Please do not use it in newly written code

move_window(x: int, y: int) → None#

The type of the None singleton.

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#: The type of the None singleton.

raise_window() → None#: The type of the None singleton.

Deprecated since version 0.60: Please do not use it in newly written code

refresh_window() → None#: The type of the None singleton.

Deprecated since version 0.60: Please do not use it in newly written code

resize_window(width: int, height: int) → None#

The type of the None singleton.

Parameters:

width – the desired number of columns
height – the desired number of rows

restore_window() → None#: The type of the None singleton.

Deprecated since version 0.60: Please do not use it in newly written code

selection_changed() → None#: The type of the None singleton.

setup_context_menu(context: EventContext | None = None) → None#

The type of the None singleton.

Parameters:: context – the context

termprop_changed(name: str) → None#

The type of the None singleton.

Added in version 0.78.

Parameters:: name – the name of the changed property

termprops_changed(props: list[int]) → bool#

The type of the None singleton.

Added in version 0.78.

Parameters:: props – an array of termprop IDs

window_title_changed() → None#

The type of the None singleton.

Deprecated since version 0.78:

Use the Terminal:termprop-changed signal: for the TERMPROP_XTERM_TITLE termprop.

Virtual Methods#

class Terminal

do_bell() → None#: The type of the None singleton.

do_char_size_changed(char_width: int, char_height: int) → None#

The type of the None singleton.

Parameters:

char_width
char_height

do_child_exited(status: int) → None#

The type of the None singleton.

Parameters:: status

do_commit(text: str, size: int) → None#

The type of the None singleton.

Parameters:

text
size

do_contents_changed() → None#: The type of the None singleton.

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() with TEXT: instead.

do_cursor_moved() → None#: The type of the None singleton.

do_decrease_font_size() → None#: The type of the None singleton.

do_deiconify_window() → None#: The type of the None singleton.

do_encoding_changed() → None#: The type of the None singleton.

do_eof() → None#: The type of the None singleton.

do_icon_title_changed() → None#: The type of the None singleton.

do_iconify_window() → None#: The type of the None singleton.

do_increase_font_size() → None#: The type of the None singleton.

do_lower_window() → None#: The type of the None singleton.

do_maximize_window() → None#: The type of the None singleton.

do_move_window(x: int, y: int) → None#

The type of the None singleton.

Parameters:

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.

do_raise_window() → None#: The type of the None singleton.

do_refresh_window() → None#: The type of the None singleton.

do_resize_window(width: int, height: int) → None#

The type of the None singleton.

Parameters:

width
height

do_restore_window() → None#: The type of the None singleton.

do_selection_changed() → None#: The type of the None singleton.

do_setup_context_menu(context: EventContext) → None#

The type of the None singleton.

Parameters:: context

do_termprop_changed(prop: str) → None#

The type of the None singleton.

Parameters:: prop

do_termprops_changed(props: int, n_props: int) → bool#

The type of the None singleton.

Parameters:

props
n_props

do_window_title_changed() → None#: The type of the None singleton.

Fields#

class Terminal

widget#

Terminal#

Constructors#

Methods#

Properties#

Signals#

Virtual Methods#

Fields#

This Page