ArtisanalApp class final

A high-level root shell for artisanal widget applications.

ArtisanalApp configures theming, terminal background publication, navigation, and window title handling on top of WidgetApp.

For simple apps, pass a home widget and optional named routes:

final app = ArtisanalApp(
  title: 'Demo',
  themeMode: ThemeMode.system,
  home: HomeScreen(),
);

If you already have a fully composed widget tree, pass child instead.

Inheritance

Constructors

ArtisanalApp({String? title, Theme? theme, Theme? darkTheme, ThemeMode themeMode = ThemeMode.system, Theme themeBuilder()?, ImageAutoMode imageAutoMode = ImageAutoMode.environment, Widget? child, Widget? home, Map<String, RouteWidgetBuilder>? routes, String? initialRoute, RouteFactory? onGenerateRoute, RouteFactory? onUnknownRoute, PopBehavior popBehavior = PopBehavior.defaultBehavior, List<NavigatorObserver> observers = const [], DebugConsoleController? debugConsoleController, int debugConsoleHeight = 8, bool debugConsoleCapturePrint = false, bool debugConsoleCaptureErrors = false, 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.
finalinherited
backgroundColorBuilder → Color? Function()?
Optional callback to resolve terminal background color at render time.
finalinherited
child → Widget?
Fully composed widget tree to render directly.
final
darkTheme → Theme?
Explicit dark theme used when themeMode resolves to ThemeMode.dark or a terminal-driven dark system theme.
final
debugConsoleCaptureErrors → bool
Whether runArtisanalApp should capture uncaught zone errors into the attached debugConsoleController.
final
debugConsoleCapturePrint → bool
Whether runArtisanalApp should capture print() output into the attached debugConsoleController.
final
debugConsoleController → DebugConsoleController?
Optional developer console controller exposed to the app subtree.
final
debugConsoleHeight → int
Number of visible log rows in the built-in debug console.
final
debugOverlay → bool
Whether the built-in debug overlay is initially enabled.
finalinherited
debugOverlayEnabled → bool
Whether the debug overlay is currently visible.
no setterinherited
debugOverlayPosition → DebugOverlayPosition
Where the debug overlay is positioned on screen.
finalinherited
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).
finalinherited
enableRenderMetricsInjection → bool
Whether to listen to RenderMetricsInjector updates.
finalinherited
handleFrameTick → bool
finalinherited
hashCode → int
The hash code for this object.
no setterinherited
home → Widget?
Root widget for the navigator's default '/' route.
final
imageAutoMode ↔ ImageAutoMode
getter/setter pairinherited
initialRoute → String?
Initial named route to display.
final
latestRenderMetrics → RenderMetrics?
The most recent RenderMetrics from the TUI runtime, or null if none has been received yet.
no setterinherited
observers → List<NavigatorObserver>
Navigation observers attached to the shell navigator.
final
onGenerateRoute → RouteFactory?
Route factory used when routes cannot resolve a route.
final
onUnknownRoute → RouteFactory?
Fallback route factory for unknown routes.
final
performanceSnapshot → PerformanceMetricsSnapshot
Returns a combined snapshot of runtime and widget-level performance data.
no setterinherited
popBehavior → PopBehavior
Keyboard pop behavior for the navigator.
final
root ↔ Widget
getter/setter pairinherited
routes → Map<String, RouteWidgetBuilder>?
Named routes for the app shell navigator.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scanZones → bool
Legacy no-op compatibility flag.
finalinherited
theme → Theme?
Explicit theme for the app shell.
final
themeBuilder → Theme Function()?
Optional dynamic theme callback evaluated during each view build.
final
themeMode → ThemeMode
Controls whether the shell follows the terminal background or forces a specific light/dark theme choice.
final
title → String?
Terminal window title published via View.windowTitle.
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.
finalinherited
wantsFrameTicks → bool
Whether the model wants to receive frame tick messages.
no setterinherited
wantsRenderMetrics → bool
Whether the model wants to receive render metrics updates.
no setterinherited

Methods

addFrameTimingCallback(WidgetFrameTimingCallback callback) → void
Registers a callback that fires after each widget frame with timing data.
inherited
buildAccessibilityTree() → A11yTree
Builds and returns the current accessibility tree snapshot.
inherited
debugElements() → List<Element>
Returns all mounted elements in depth-first order.
inherited
debugElementsWhere(bool predicate(Element element)) → List<Element>
Returns mounted elements that satisfy predicate.
inherited
diffAccessibilityTree(A11yTree previousTree) → A11yTreeDiff
Diffs the current accessibility tree against previousTree.
inherited
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.
inherited
init() → Cmd?
Returns an optional command to execute on program startup.
inherited
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.
inherited
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.
inherited
view() → Object
Renders the current model state for display.
override

Operators

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