Class TerminalEmulator

Terminal emulator that implements IVTParserHandler to translate VT/ANSI escape sequences into CellGrid state mutations. Supports cursor movement, SGR (Select Graphic Rendition), scroll regions, alternate screen buffer, cursor shapes (DECSCUSR), the DEC Special Graphics line-drawing character set, and standard DEC terminal modes.

Inheritance

object

TerminalEmulator

Implements

IVTParserHandler

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.TextMode

Assembly: ScyllaTextMode.dll

Syntax

public class TerminalEmulator : IVTParserHandler

Constructors

TerminalEmulator(CellGrid, GlyphAtlasCache, int)

Creates a new terminal emulator with the specified grid and glyph cache.

Declaration

public TerminalEmulator(CellGrid grid, GlyphAtlasCache glyphCache, int scrollbackCapacity = 1000)

Parameters

Type	Name	Description
CellGrid	grid	The cell grid to render into.
GlyphAtlasCache	glyphCache	The glyph atlas cache for stamping cells.
int	scrollbackCapacity	Maximum scrollback lines. 0 = no scrollback.

Fields

OnActiveGridChanged

Invoked when the active cell grid changes (e.g., alternate screen switch). The parameter is the new active CellGrid that views should render.

Declaration

public Action<CellGrid> OnActiveGridChanged

Field Value

Type	Description
Action<CellGrid>

OnBell

Invoked when the terminal receives a BEL (0x07) control character.

Declaration

public Action OnBell

Field Value

Type	Description
Action

OnClipboardRead

Invoked when the terminal reads clipboard content (OSC 52 query). Should return the current clipboard text, or null if unavailable.

Declaration

public Func<string> OnClipboardRead

Field Value

Type	Description
Func<string>

OnClipboardWrite

Invoked when the terminal sets clipboard content (OSC 52 write). The parameter is the decoded UTF-8 string to place on the clipboard.

Declaration

public Action<string> OnClipboardWrite

Field Value

Type	Description
Action<string>

OnCursorStyleChanged

Invoked when the host changes the cursor shape or blinking through DECSCUSR, or when a reset drops that choice. Read HasCursorStyleOverride, CursorStyle and CursorBlinking to apply it.

Declaration

public Action OnCursorStyleChanged

Field Value

Type	Description
Action

OnTerminalOutput

Invoked when the terminal needs to send response bytes back to the host process. Used for OSC 52 clipboard query responses and DSR (Device Status Report) replies.

Declaration

public Action<byte[]> OnTerminalOutput

Field Value

Type	Description
Action<byte[]>

OnTitleChanged

Invoked when the terminal title changes (via OSC 0 or OSC 2).

Declaration

public Action<string> OnTitleChanged

Field Value

Type	Description
Action<string>

Properties

AllowClipboardRead

Controls whether clipboard read queries (OSC 52 '?') are allowed. Disabled by default for security (prevents clipboard exfiltration).

Declaration

public bool AllowClipboardRead { get; set; }

Property Value

Type	Description
bool

AlternateGrid

Gets the alternate screen's grid, whichever screen is active. Null until a program has switched to the alternate screen for the first time.

Declaration

public CellGrid AlternateGrid { get; }

Property Value

Type	Description
CellGrid

ApplicationCursorKeys

Gets whether application cursor keys mode is enabled.

Declaration

public bool ApplicationCursorKeys { get; }

Property Value

Type	Description
bool

ApplicationKeypad

Gets whether application keypad mode is enabled.

Declaration

public bool ApplicationKeypad { get; }

Property Value

Type	Description
bool

BracketedPasteMode

Gets whether bracketed paste mode is enabled.

Declaration

public bool BracketedPasteMode { get; }

Property Value

Type	Description
bool

Columns

Gets the number of columns.

Declaration

public int Columns { get; }

Property Value

Type	Description
int

CurrentBG

Gets the current background color.

Declaration

public Color32 CurrentBG { get; }

Property Value

Type	Description
Color32

CurrentFG

Gets the current foreground color.

Declaration

public Color32 CurrentFG { get; }

Property Value

Type	Description
Color32

CursorBlinking

Gets whether the cursor should blink. Only meaningful while HasCursorStyleOverride is true.

Declaration

public bool CursorBlinking { get; }

Property Value

Type	Description
bool

CursorCol

Gets the current cursor column.

Declaration

public int CursorCol { get; }

Property Value

Type	Description
int

CursorRow

Gets the current cursor row.

Declaration

public int CursorRow { get; }

Property Value

Type	Description
int

CursorStyle

Gets the cursor style.

Declaration

public CursorStyle CursorStyle { get; }

Property Value

Type	Description
CursorStyle

CursorVisible

Gets whether the cursor is visible.

Declaration

public bool CursorVisible { get; }

Property Value

Type	Description
bool

Grid

Gets the underlying cell grid.

Declaration

public CellGrid Grid { get; }

Property Value

Type	Description
CellGrid

HasActiveHyperlink

Gets whether a hyperlink is currently active for new characters.

Declaration

public bool HasActiveHyperlink { get; }

Property Value

Type	Description
bool

HasCursorStyleOverride

Gets whether the host has chosen a cursor shape through DECSCUSR (CSI Ps SP q). When false, the view should use its own configured cursor.

Declaration

public bool HasCursorStyleOverride { get; }

Property Value

Type	Description
bool

IsAlternateScreen

Gets whether the alternate screen buffer is active.

Declaration

public bool IsAlternateScreen { get; }

Property Value

Type	Description
bool

IsDECGraphicsActive

Gets whether characters printed now are translated through the DEC Special Graphics character set, which maps ASCII letters to line-drawing characters.

Declaration

public bool IsDECGraphicsActive { get; }

Property Value

Type	Description
bool

MouseEncodingMode

Gets the current mouse encoding mode.

Declaration

public MouseEncodingMode MouseEncodingMode { get; }

Property Value

Type	Description
MouseEncodingMode

MouseTrackingMode

Gets the current mouse tracking mode.

Declaration

public MouseTrackingMode MouseTrackingMode { get; }

Property Value

Type	Description
MouseTrackingMode

Parser

Gets the VT parser for feeding input.

Declaration

public VTParser Parser { get; }

Property Value

Type	Description
VTParser

PrimaryGrid

Gets the primary screen's grid, whichever screen is active.

Declaration

public CellGrid PrimaryGrid { get; }

Property Value

Type	Description
CellGrid

Rows

Gets the number of rows.

Declaration

public int Rows { get; }

Property Value

Type	Description
int

Scrollback

Gets the scrollback buffer.

Declaration

public ScyllaRingBuffer<Cell[]> Scrollback { get; }

Property Value

Type	Description
ScyllaRingBuffer<Cell[]>

Methods

CSIDispatch(ReadOnlySpan<int>, ReadOnlySpan<byte>, byte)

A CSI (Control Sequence Introducer) sequence has been parsed. CSI sequences are the primary mechanism for cursor movement, erasing, SGR, etc.

Declaration

public void CSIDispatch(ReadOnlySpan<int> parameters, ReadOnlySpan<byte> intermediates, byte finalByte)

Parameters

Type	Name	Description
ReadOnlySpan<int>	parameters	Parsed numeric parameters (semicolon-separated in the escape sequence).
ReadOnlySpan<byte>	intermediates	Intermediate bytes (between CSI and final byte).
byte	finalByte	The final byte that identifies the specific command.

ClearScrollback()

Discards every line saved in the scrollback. The screen is left as it is.

Declaration

public void ClearScrollback()

DCSHook(ReadOnlySpan<int>, ReadOnlySpan<byte>, byte)

A DCS (Device Control String) sequence is starting.

Declaration

public void DCSHook(ReadOnlySpan<int> parameters, ReadOnlySpan<byte> intermediates, byte finalByte)

Parameters

Type	Name	Description
ReadOnlySpan<int>	parameters	Parsed numeric parameters.
ReadOnlySpan<byte>	intermediates	Intermediate bytes.
byte	finalByte	The final byte.

DCSPut(byte)

Data within a DCS passthrough sequence.

Declaration

public void DCSPut(byte data)

Parameters

Type	Name	Description
byte	data	The passthrough byte.

DCSUnhook()

A DCS sequence has ended.

Declaration

public void DCSUnhook()

ESCDispatch(ReadOnlySpan<byte>, byte)

An ESC (Escape) sequence has been parsed. Used for simpler sequences like DECSC, DECRC, and character set selection.

Declaration

public void ESCDispatch(ReadOnlySpan<byte> intermediates, byte finalByte)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	intermediates	Intermediate bytes.
byte	finalByte	The final byte.

Execute(byte)

A C0 or C1 control character should be executed. Common controls: BEL (0x07), BS (0x08), HT (0x09), LF (0x0A), CR (0x0D).

Declaration

public void Execute(byte control)

Parameters

Type	Name	Description
byte	control	The control byte.

Feed(ReadOnlySpan<byte>)

Feeds raw bytes to the terminal emulator for processing. Callers should batch input for best performance; cursor cell update runs once at the end of each Feed call regardless of input size.

Declaration

public void Feed(ReadOnlySpan<byte> data)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	data	Input data bytes.

FeedString(string)

Feeds a string to the terminal emulator. Callers should batch input for best performance; cursor cell update runs once at the end of each FeedString call regardless of input size.

Declaration

public void FeedString(string text)

Parameters

Type	Name	Description
string	text	Input text.

GetHyperlinkAt(int, int)

Returns the hyperlink URI associated with the cell at the specified position in the currently active grid (primary or alternate screen), or null if no hyperlink is set.

Declaration

public string GetHyperlinkAt(int row, int col)

Parameters

Type	Name	Description
int	row	The row index.
int	col	The column index.

Returns

Type	Description
string	The hyperlink URI string, or null.

GetHyperlinkURI(CellAttributes)

Returns the hyperlink URI for a cell's attributes, or null if the cell has no hyperlink.

Declaration

public string GetHyperlinkURI(CellAttributes attributes)

Parameters

Type	Name	Description
CellAttributes	attributes	The attributes of the cell.

Returns

Type	Description
string	The hyperlink URI string, or null.

Remarks

Unlike GetHyperlinkAt(int, int), this works for any cell the emulator produced, including cells from Scrollback or a grid composed from it.

OSCDispatch(ReadOnlySpan<byte>)

An OSC (Operating System Command) sequence has been parsed. Used for window title, hyperlinks, clipboard, etc.

Declaration

public void OSCDispatch(ReadOnlySpan<byte> data)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	data	The raw OSC data bytes.

Print(int)

A printable character should be displayed at the current cursor position.

Declaration

public void Print(int codepoint)

Parameters

Type	Name	Description
int	codepoint	Unicode codepoint to print.

Reset()

Resets the terminal to its initial state.

Declaration

public void Reset()

Resize(int, int)

Resizes the terminal. Both the primary and the alternate screen take the new size, the scroll region resets to the full screen, and the cursor is clamped into bounds.

Declaration

public void Resize(int rows, int columns)

Parameters

Type	Name	Description
int	rows	New row count.
int	columns	New column count.

Remarks

Call this whenever the view showing the terminal changes size. A view that resizes only the grid it is rendering leaves the other screen at the old size and the scroll region pointing at rows that may no longer exist.

When the primary screen loses rows and the cursor would end up below the new last row, the screen first scrolls up far enough to keep the cursor's line on screen, and the lines that leave the top go into the scrollback. The line being typed and the output just above it stay visible. The alternate screen is cut at the bottom, as before, because a full-screen program redraws itself after a resize anyway.

SetANSIPalette(ColorPalette)

Gives the emulator its own sixteen ANSI colors, so escape sequences that ask for a standard color, such as ESC[31m for red, use this palette rather than the project palette in ANSIColor.

Declaration

public void SetANSIPalette(ColorPalette palette)

Parameters

Type	Name	Description
ColorPalette	palette	A palette whose first sixteen entries are the ANSI colors in ANSI order, as in a TextMode theme. Null, or a palette with fewer than sixteen entries, returns to the project palette.

Remarks

Only colors chosen from now on are affected. Cells already written keep the colors they were written with, because every cell stores its own. The 256-color cube, the grey ramp and 24-bit colors do not depend on a palette and are unchanged.

SetDefaultColors(Color32, Color32)

Replaces the colors SGR 39 and SGR 49 reset to.

Declaration

public void SetDefaultColors(Color32 foreground, Color32 background)

Parameters

Type	Name	Description
Color32	foreground	The new default foreground.
Color32	background	The new default background.

Remarks

The emulator caches these when it is constructed, because the grid it was built around cannot change its own defaults retroactively for cells already written. That cache is what "default color" means for the whole lifetime of the emulator, so a theme change has to push the new values in here or unstyled text keeps rendering in the colors the terminal happened to be built with.

Text currently using the default colors is updated too, so a reset that has already happened does not leave the next character on a stale color. The same goes for the cursor states DECSC saved for both screens, since leaving the alternate screen restores one of them, and for the default colors of both screen grids, which scrolling and erasing fill with.

SetGlyphCache(GlyphAtlasCache)

Switches to a new glyph cache and restamps every cell the emulator holds with it: both screens and the scrollback.

Declaration

public void SetGlyphCache(GlyphAtlasCache glyphCache)

Parameters

Type	Name	Description
GlyphAtlasCache	glyphCache	The cache of the font now in use.

Remarks

Call this after the view showing the terminal changed its font. Cells carry the atlas coordinates of the font they were written with, and the view disposes the old cache when its font changes. An emulator left holding it writes the old font's fallback glyph into every new cell, and the cells already on screen point into the wrong atlas.

Implements

IVTParserHandler