WidgetApp class

Runs a widget tree using an element hierarchy.

Built-in Debug Overlay

Set debugOverlay to true to enable a built-in DebugOverlay that shows FPS, frame counts, and timing data. The overlay can be toggled at runtime by pressing F12. The debugOverlayPosition parameter controls where the overlay appears (defaults to DebugOverlayPosition.topRight).

The F12 toggle works even when debugOverlay starts as false — pressing F12 will enable it on the fly.

Implemented types

Constructors

WidgetApp(Widget root, {Color? backgroundColor, Color? backgroundColorBuilder()?, bool scanZones = false, bool useHitTesting = true, bool handleFrameTick = false, bool enableRenderMetrics = true, bool enableRenderMetricsInjection = true, bool debugOverlay = false, DebugOverlayPosition debugOverlayPosition = DebugOverlayPosition.topRight, bool debugRebuilds = false})

Properties

backgroundColor → Color?: Optional terminal background color.
final
backgroundColorBuilder → Color? Function()?: Optional callback to resolve terminal background color at render time.
final
debugOverlay → bool: Whether the built-in debug overlay is initially enabled.
final
debugOverlayEnabled → bool: Whether the debug overlay is currently visible.
no setter
debugOverlayPosition → DebugOverlayPosition: Where the debug overlay is positioned on screen.
final
enableRenderMetrics → bool: Whether to opt into the TUI runtime's RenderMetricsMsg stream. When true (the default), the runtime starts a periodic timer that sends real renderer metrics (FPS, frame times, render durations).
final
enableRenderMetricsInjection → bool: Whether to listen to RenderMetricsInjector updates.
final
handleFrameTick → bool: final
hashCode → int: The hash code for this object.
no setterinherited
latestRenderMetrics → RenderMetrics?: The most recent RenderMetrics from the TUI runtime, or null if none has been received yet.
no setter
performanceSnapshot → PerformanceMetricsSnapshot: Returns a combined snapshot of runtime and widget-level performance data.
no setter
root ↔ Widget: getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scanZones → bool: Legacy no-op compatibility flag.
final
useHitTesting → bool: When true (the default), mouse events are dispatched via render-tree hit-testing instead of zone scanning. Set to false to fall back to zone-based dispatch.
final
wantsFrameTicks → bool: Whether the model wants to receive frame tick messages.
no setteroverride
wantsRenderMetrics → bool: Whether the model wants to receive render metrics updates.
no setteroverride

Methods

addFrameTimingCallback(WidgetFrameTimingCallback callback) → void: Registers a callback that fires after each widget frame with timing data.
debugElements() → List<Element>: Returns all mounted elements in depth-first order.
debugElementsWhere(bool predicate(Element element)) → List<Element>: Returns mounted elements that satisfy predicate.
hitTestAt(double x, double y) → List<HitTestElementEntry>: Performs a hit-test at the given terminal coordinates against the render tree. Returns the list of hit elements, deepest first.
init() → Cmd?: Returns an optional command to execute on program startup.
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
removeFrameTimingCallback(WidgetFrameTimingCallback callback) → void: Removes a previously registered frame timing callback.
toString() → String: A string representation of this object.
inherited
update(Msg msg) → (Model, Cmd?): Handles a message and returns the new model state and optional command.
override
view() → Object: Renders the current model state for display.
override

Operators

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