PromptRunner<T> class

A helper class to run an interactive terminal prompt inline. It encapsulates the event loop, rendering to an inline buffer, and lifecycle management.

Example:

final name = await PromptRunner<String>(
  terminal: terminal,
  widget: Column([
    const Text('Enter name:'),
    TextField(controller: myController, focused: true),
  ]),
  exitConditions: {
    PromptExitTrigger.enter: PromptExitAction.complete,
    PromptExitTrigger.escape: PromptExitAction.cancel,
  },
  onComplete: () => myController.text,
).run();

Implemented types

• ListenableSceneRenderer
• Reassemblable

Constructors

PromptRunner({required Terminal terminal, required Widget widget, Map<PromptExitTrigger, PromptExitAction>? exitConditions, bool onKeyEvent(KeyEvent event)?, void onPasteEvent(PasteEvent event)?, T onComplete()?, bool alternateScreen = false, void onFramePainted(Buffer buffer)?, ExecutionMode mode = ExecutionMode.standalone})

Creates a new PromptRunner.

Properties

alternateScreen → bool

Whether to render in alternate screen mode.

final

currentBuffer → Buffer?

Exposes the current buffer containing the rendered output.

no setter, override

exitConditions → Map<PromptExitTrigger, PromptExitAction>

Mapping of exit triggers to their corresponding actions.

final

hashCode → int

The hash code for this object.

no setter, inherited

hasScheduledFrame → bool

Exposes whether a draw frame is currently scheduled.

no setter

isDirty → bool

Whether the renderer needs a visual rebuild/update.

no setter, override

isDisposed → bool

Exposes whether the prompt runner is disposed.

no setter

lastMousePosition → Point<int>?

The last known mouse position coordinate.

no setter

mode → ExecutionMode

The execution mode of this runner.

final

onComplete → T Function()?

An optional completion callback returning the final value of type T.

final

onFramePainted → void Function(Buffer buffer)?

Callback after each frame is painted onto the buffer.

final

onKeyEvent → bool Function(KeyEvent event)?

An optional key event handler callback. Returns true if prompt is completed.

final

onNeedVisualUpdate ↔ void Function()?

Callback triggered when this renderer's visual content changes and needs to be composited/repainted.

getter/setter pair, override

onPasteEvent → void Function(PasteEvent event)?

An optional paste event handler callback.

final

requestedCursorPosition → Point<int>?

The requested cursor coordinates, if any.

no setter, override

rootElement → Element?

Exposes the root element of the mounted widget tree for testing.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

showsCursor → bool

Whether the hardware terminal cursor should be shown.

no setter, override

terminal → Terminal

The active terminal instance.

final

wantsAlternateScreen → bool

Whether alternate screen buffer mode is requested.

no setter, override

wantsMouseTracking → bool

Whether mouse tracking features are requested.

no setter, override

widget ↔ Widget

The root widget configuration to display.

getter/setter pair

Methods

abort([Object? exception]) → void

Public programmatic abort.

dispose() → void

Public programmatic dispose/cleanup.

override

handleKeyEvent(KeyEvent event) → bool

Handles key events routed to this renderer. Returns true if handled.

override

handleMouseEvent(MouseEvent event) → bool

Handles mouse events routed to this renderer. Returns true if the event was consumed.

override

handlePasteEvent(PasteEvent event) → void

Handles bracketed paste events.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

pump() → void

Forces a rebuild of the element tree and repaints to the internal buffer.

reassemble() → void

Called during hot reload to force the entire widget tree to rebuild and repaint.

override

render() → void

Recalculates layout and paints the widget tree to the internal buffer.

override

resize(int width, int height) → void

Programmatically resizes the runner viewport and updates layout/buffers.

override

run() → Future<T?>

Starts the inline prompt loop and returns a Future containing the final result.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

onPromptEnded ↔ void Function(PromptRunner runner)?

Static hook called when a prompt runner ends/disposes.

getter/setter pair

onPromptStarted ↔ void Function(PromptRunner runner)?

Static hook called when a prompt runner starts running.

getter/setter pair

Constants

defaultExitConditions → const Map<PromptExitTrigger, PromptExitAction>

Default exit conditions mapping.