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
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
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
output → Stream<Uint8List>
Engine → PTY (and write(bytes) echoes). Drain into the PTY directly: engine.output.listen(pty.write).
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

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. Lazy-inits the binding on first call.
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. Lazy-inits the binding on first call.
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.
scrollBy(int delta) → void
Fire-and-forget scroll for input-driven paths (mouse wheel, trackpad pan, touch fling). Multiple calls within one frame coalesce into one engine call + one snapshot.
scrollByPixels(double deltaPx) → void
Fire-and-forget sub-cell pixel scroll for smooth wheel / trackpad / fling input. Positive deltaPx scrolls up into history. Coalesces per frame like scrollBy; the engine tracks the fractional offset and exposes it on the grid as scrollFraction for the painter.
scrollLines(int delta) → Future<void>
scrollToBottom() → Future<void>
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.
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