TerminalWidgetHandle

Namespace: Hex1b

Assembly: Hex1b.dll

A handle that connects a Hex1bTerminal to a TerminalWidget for embedding child terminal sessions within a TUI application.

public sealed class TerminalWidgetHandle : ICellImpactAwarePresentationAdapter, ITerminalLifecycleAwarePresentationAdapter, IHex1bTerminalPresentationAdapter, IAsyncDisposable

Inheritance

Object → TerminalWidgetHandle

Implements

• ICellImpactAwarePresentationAdapter
• ITerminalLifecycleAwarePresentationAdapter
• IHex1bTerminalPresentationAdapter
• IAsyncDisposable

Constructors

TerminalWidgetHandle(int, int)

Creates a new TerminalWidgetHandle with the specified dimensions.

Parameters:

• width (Int32): Initial width in columns.
• height (Int32): Initial height in rows.

public TerminalWidgetHandle(int width = 80, int height = 24)

Properties

Capabilities

Capability hints that inform optimization strategies.

Returns: TerminalCapabilities

public TerminalCapabilities Capabilities { get; }

CursorShape

Gets the current cursor shape requested by the child process.

Returns: CursorShape

public CursorShape CursorShape { get; }

CursorVisible

Gets whether the cursor is currently visible.

Returns: Boolean

public bool CursorVisible { get; }

CursorX

Gets the current cursor X position (0-based).

Returns: Int32

public int CursorX { get; }

CursorY

Gets the current cursor Y position (0-based).

Returns: Int32

public int CursorY { get; }

ExitCode

Gets the exit code of the terminal process, if it has completed.

Returns: Nullable<Int32>

public int? ExitCode { get; }

Height

Gets the current height of the terminal in rows.

Returns: Int32

public int Height { get; }

IconName

Gets the current icon name set by OSC 0 or OSC 1 sequences from the child process.

Returns: String

public string IconName { get; }

IsRunning

Gets whether the terminal is currently running.

Returns: Boolean

public bool IsRunning { get; }

MouseTrackingEnabled

Gets whether the child process has enabled mouse tracking. Mouse events are only forwarded to the child when this is true.

Returns: Boolean

public bool MouseTrackingEnabled { get; }

State

Gets the current lifecycle state of the terminal session.

Returns: TerminalState

public TerminalState State { get; }

Width

Gets the current width of the terminal in columns.

Returns: Int32

public int Width { get; }

WindowTitle

Gets the current window title set by OSC 0 or OSC 2 sequences from the child process.

Returns: String

public string WindowTitle { get; }

Methods

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Returns: ValueTask

A task that represents the asynchronous dispose operation.

public ValueTask DisposeAsync()

EnterRawModeAsync(CancellationToken)

Enter raw mode for proper input capture.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: ValueTask

public ValueTask EnterRawModeAsync(CancellationToken ct = default)

ExitRawModeAsync(CancellationToken)

Exit raw mode and restore normal terminal input handling.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: ValueTask

public ValueTask ExitRawModeAsync(CancellationToken ct = default)

FlushAsync(CancellationToken)

Flush any buffered output immediately.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: ValueTask

public ValueTask FlushAsync(CancellationToken ct = default)

GetCell(int, int)

Gets the cell at the specified position.

Parameters:

• x (Int32):
• y (Int32):

Returns: TerminalCell

public TerminalCell GetCell(int x, int y)

GetCursorPosition()

Gets the current cursor position in the terminal. Returns (0, 0) if the position cannot be determined.

Returns: ValueTuple<Int32, Int32>

A tuple of (Row, Column), both 0-based.

public (int Row, int Column) GetCursorPosition()

GetScreenBuffer()

Gets a copy of the current screen buffer.

Returns: TerminalCell[,]

A copy of the screen buffer cells.

public TerminalCell[,] GetScreenBuffer()

GetScreenBufferSnapshot()

Gets a snapshot of the current screen buffer with its dimensions. This is atomic - the dimensions will always match the buffer.

Returns: ValueTuple<TerminalCell[0:, 0:], Int32, Int32>

A tuple containing the buffer copy, width, and height.

public (TerminalCell[,] Buffer, int Width, int Height) GetScreenBufferSnapshot()

ReadInputAsync(CancellationToken)

Receive input (keystrokes, mouse events as ANSI sequences) FROM the user.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: ValueTask<Byte>>

Raw input bytes from the user, or empty when disconnected.

public ValueTask<ReadOnlyMemory<byte>> ReadInputAsync(CancellationToken ct = default)

Reset()

Resets the terminal state to NotStarted. Used when restarting a terminal.

public void Reset()

Resize(int, int)

Resizes the terminal buffer.

Parameters:

• newWidth (Int32):
• newHeight (Int32):

public void Resize(int newWidth, int newHeight)

SendEventAsync(Hex1bEvent, CancellationToken)

Sends an input event (key or mouse) to the terminal's workload (e.g., child process). Mouse events are only forwarded if the child process has enabled mouse tracking.

Parameters:

• evt (Hex1bEvent): The event to send.
• ct (CancellationToken): Cancellation token.

Returns: Task

A task that completes when the event has been sent.

public Task SendEventAsync(Hex1bEvent evt, CancellationToken ct = default)

SendKeyEventAsync(Hex1bKeyEvent, CancellationToken)

Sends a key event to the terminal's workload (e.g., child process).

Parameters:

• keyEvent (Hex1bKeyEvent): The key event to send.
• ct (CancellationToken): Cancellation token.

Returns: Task

A task that completes when the event has been sent.

[Obsolete("Use SendEventAsync instead.")]
public Task SendKeyEventAsync(Hex1bKeyEvent keyEvent, CancellationToken ct = default)

WriteOutputAsync(ReadOnlyMemory<byte>, CancellationToken)

Fallback for when the terminal doesn't support cell impacts. This should rarely be called since ICellImpactAwarePresentationAdapter.WriteOutputWithImpactsAsync is the preferred path.

Parameters:

• data (ReadOnlyMemory<Byte>):
• ct (CancellationToken):

Returns: ValueTask

public ValueTask WriteOutputAsync(ReadOnlyMemory<byte> data, CancellationToken ct = default)

WriteOutputWithImpactsAsync(IReadOnlyList<AppliedToken>, CancellationToken)

Receives pre-processed cell impacts from the terminal's ANSI parsing logic. This is the main entry point for output - the terminal calls this instead of WriteOutputAsync when it detects we implement ICellImpactAwarePresentationAdapter.

Parameters:

• appliedTokens (IReadOnlyList<AppliedToken>):
• ct (CancellationToken):

Returns: ValueTask

public ValueTask WriteOutputWithImpactsAsync(IReadOnlyList<AppliedToken> appliedTokens, CancellationToken ct = default)

Events

Disconnected

Raised when the presentation layer disconnects (e.g., terminal closed, WebSocket dropped).

Returns: Action

public event Action? Disconnected

IconNameChanged

Event raised when the icon name changes (OSC 0 or OSC 1 from child process).

Returns: Action<String>

public event Action<string>? IconNameChanged

OutputReceived

Event raised when new output has been written to the buffer. TerminalNode subscribes to this to trigger re-renders.

Returns: Action

public event Action? OutputReceived

Resized

Raised when the presentation layer is resized by the user.

Returns: Action<Int32, Int32>

public event Action<int, int>? Resized

StateChanged

Event raised when the terminal state changes.

Returns: Action<TerminalState>

public event Action<TerminalState>? StateChanged

WindowTitleChanged

Event raised when the window title changes (OSC 0 or OSC 2 from child process).

Returns: Action<String>

public event Action<string>? WindowTitleChanged

Remarks

The TerminalWidgetHandle implements to receive pre-processed cell impacts directly from the terminal's ANSI parsing logic. This eliminates the need to duplicate parsing code while maintaining a screen buffer that the TerminalWidget can render from.

Usage:

var terminal = Hex1bTerminal.CreateBuilder()
    .WithPtyProcess("bash")
    .WithTerminalWidget(out var bashHandle)
    .Build();

_ = terminal.RunAsync(appCt);

// In widget tree:
ctx.Terminal(bashHandle);