TerminalEngine class

Public, consumer-facing handle to the alacritty engine.

Wraps TerminalEngineClient + MirrorGrid + EngineBinding behind:

  • feed(bytes) — PTY → engine,
  • write(bytes) / output — view ↔ engine ↔ PTY,
  • title / bell / clipboardStore — engine → host signals.

The four on* binding callbacks become streams/notifiers here; consumers no longer wire them by hand.

Construction is lazy: the underlying EngineBinding (which boots the native engine) is built on the first feed / resize call, so consumers can construct a TerminalEngine cheaply (e.g. for tests, or to read the default title) without paying the native init cost.

Constructors

TerminalEngine({required TerminalConfig config, EngineFactory? engineFactory})
Default ctor: lazy. The engineFactory (defaults to FrbEngineBinding.new) is invoked on the first feed / resize.
TerminalEngine.fromBinding(EngineBinding binding, {required TerminalConfig config, void schedule(void ())?})
Test-only escape hatch: wire a pre-built EngineBinding. This skips the lazy-init path and constructs the TerminalEngineClient eagerly so the test can assert on it immediately. An optional schedule hook lets the test drive the drain pipeline synchronously (no real frame pumping).
factory

Properties

bell → Stream<void>
One event per Event::Bell.
no setter
cellPixelHeight → double
Last cell height passed to setCellPixels. Used by hosts for pixel scroll math (scrollbar drags, etc.) so they stay aligned with the engine.
no setter
clipboardLoad → Stream<void>
One event per OSC 52 paste request (host should read clipboard and call respondClipboardLoad).
no setter
clipboardStore → Stream<String>
One event per OSC 52 SET.
no setter
grid → TerminalGridView
Read-only view of the terminal grid. Consumers can read cell content, cursor position, mode flags, displayOffset, and listen for changes via the inherited Listenable — but cannot mutate. The mutable handle is reserved for the in-package TerminalView painter via gridForView.
no setter
gridForView → MirrorGrid
Package-internal: the rendering view needs the mutable MirrorGrid to wire CustomPaint(repaint: ...) and read cells. External consumers should use grid instead — mutating the returned MirrorGrid will corrupt the engine's mirror. (Cannot use @internal here because this lives in a public-library element; see follow-up note in 2W findings about moving the engine to lib/src/ to fix the annotation.)
no setter
hashCode → int
The hash code for this object.
no setterinherited
isBound → bool
Whether the native binding has been created (i.e. a real size has landed).
no setter
notify → Stream<String>
One event per OSC 9 / OSC 777 desktop notification. Payload is either the notification body (OSC 9) or "title\0body" (OSC 777).
no setter
onCancelCoalescedScroll ↔ VoidCallback?
Host hook: cancel coalesced wheel/pan/fling history scroll (see TerminalScrollController.cancelPendingHistory). TerminalView wires this.
getter/setter pair
onDrainHistoryScroll ↔ Future<void> Function()?
Host hook: wait for in-flight gesture scroll before absolute scroll. TerminalView wires this to TerminalScrollController.drainHistoryScroll.
getter/setter pair
onPtyResize ↔ void Function(int columns, int rows)?
Host transport hook. Invoked only after the native engine and mirror grid have adopted columns×rows. Wire to PtyBackend.resize(rows, columns).
getter/setter pair
output → Stream<Uint8List>
Engine → PTY (and write(bytes) echoes). Drain into the PTY directly: engine.output.listen(pty.write).
no setter
pendingWriteBytesForTest → int
no setter
repaint → Listenable
Listenable for external consumers who want to drive a CustomPaint(repaint: ...) directly. The in-package TerminalView rebinds the grid in each build instead and does not read this. Same object as the underlying MirrorGrid, which is a ChangeNotifier.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
title → ValueListenable<String>
Current terminal title. Updated on Event::Title and Event::ResetTitle.
no setter
workingDir → ValueListenable<String>
Current working directory reported via OSC 7 (file://host/path). Updated each time the shell emits an OSC 7 sequence.
no setter

Methods

cancelCoalescedScrollInput() → void
clearHistory() → void
Clear scrollback history (alacritty ClearHistory). No-op until bound.
dispose() → void
drainForTest() → Future<void>
Awaits pending PTY batches. Use in tests before reading grid.
feed(Uint8List bytes) → void
PTY → engine. Buffers until the first resize establishes a real grid width — parsing terminal output before the line width is known would write into a fabricated grid (see _pendingFeed).
hyperlinkAt(int row, int col) → String?
URL-launcher helper: returns the hyperlink URI at (row, col), or null.
initializeEmpty(int rows, int columns) → void
Initialize the mirror grid to an empty viewport. Useful at startup so the first paint pass doesn't show a stale grid before the first damage arrives. The mirror is then resized on the first apply.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
reconfigure(TerminalConfig config) → void
Live-apply engine-side config (scrollback, palette, semantic chars, cursor defaults, osc52) without re-spawning. Safe to call repeatedly.
refreshView() → void
Force a viewport refresh from the engine (used after selection changes, which alter FLAG_SELECTED on otherwise-unchanged cells).
resize({required int columns, required int rows}) → void
Cell-grid resize. This is the authoritative size source: it creates the native binding on first call and then replays anything that arrived early.
respondClipboardLoad(String text) → void
Answer a pending OSC 52 paste request with text (host reads the system clipboard, then calls this). Encoded reply goes out on output.
scheduleTask(void cb()) → void
Microtask-batched scheduling shared by scroll coalescing and scheduleWrite.
scheduleWrite(Uint8List bytes) → void
Coalesce PTY-bound bytes (TUI scroll, batched arrows) to one output event per scheduling tick — same hop model as scroll coalescing.
scrollLines(int delta) → Future<void>
scrollPixels(double deltaPx) → Future<void>
Awaited sub-cell scroll (touch pan / fling via TerminalScrollController).
scrollToBottom() → Future<void>
scrollToBottomSnap() → Future<void>
Edge snap during an in-progress gesture flush. Skips coalesced-input cancel/drain — TerminalScrollController already serializes the queue.
scrollToOffset(double offsetLines) → Future<void>
Absolute scroll offset in lines (0 = live bottom, historySize = top).
scrollToTop() → Future<void>
scrollToTopSnap() → Future<void>
See scrollToBottomSnap.
searchClear() → void
searchNext() → bool
searchPrev() → bool
searchSet(String pattern) → bool
selectionClear() → void
selectionStart(int row, int col, bool rightHalf, int kind) → void
selectionText() → String?
selectionUpdate(int row, int col, bool rightHalf) → void
setCellPixels(int width, int height) → void
Push the measured cell pixel size so the engine can answer CSI 14/18 t. Carries no grid dimensions, so it never creates the binding; if it arrives before sizing it is stashed and applied when the grid is built.
toString() → String
A string representation of this object.
inherited
write(Uint8List bytes) → void
View → engine (keystrokes, paste bytes, mouse reports). Bytes appear on output in the same tick — single ordered sink with Event::PtyWrite.

Operators

operator ==(Object other) → bool
The equality operator.
inherited