CobaltAppScope class

Owns the root scope for as long as the app is mounted.

Declares the graph the same way CobaltApplication.start takes it, builds it, publishes it, and disposes it on unmount. The counterpart to CobaltScopeWidget, which owns a child scope; this one has no ancestor to push from, so it starts the graph itself.

The usual place for it is MaterialApp.builder, through CobaltAppScope.builder — there loading and errorBuilder are rendered with the app's theme and directionality, so they can be an ordinary screen rather than a second app:

void main() => runApp(
  MaterialApp(
    theme: ThemeData(colorSchemeSeed: Colors.indigo),
    builder: CobaltAppScope.builder(
      root: const AppScope(),
      loading: const Scaffold(body: Center(child: CircularProgressIndicator())),
    ),
    home: const HomeScreen(),
  ),
);

Awaiting the graph inside runApp rather than before it buys two things: a startup failure becomes a screen with a retry instead of an app that dies without a frame, and WidgetsFlutterBinding is already initialized when @CobaltBootstrap steps run.

CobaltAppScope.of(context).restart() tears the graph down and builds a new one — the same call that retries a failed start.

Inheritance

Constructors

CobaltAppScope({required CobaltScopeBuilder root, required Widget child, List<CobaltBootstrapStep> bootstrap()?, String rootName = 'root', List<CobaltObserver> observers = const [], List<CobaltOverride<Object>> overrides()?, Duration? initTimeout, List<CobaltKey> warmUp = const [], Widget? loading, Widget errorBuilder(BuildContext context, Object error, VoidCallback retry)?, bool disposeOnExitRequest = false, bool restartOnGraphChange = true, Key? key})
Creates the owner of an app's root scope from the graph's parts.
const
CobaltAppScope.start({required Future<CobaltScope> start(), required Widget child, List<CobaltKey> warmUp = const [], Widget? loading, Widget errorBuilder(BuildContext context, Object error, VoidCallback retry)?, bool disposeOnExitRequest = false, Key? key})
Creates the owner from a function that returns a started scope.
const

Properties

bootstrap → List<CobaltBootstrapStep> Function()?
Produces the phase-0 steps, called once per start.
final
child → Widget
Shown once the graph is ready, below a CobaltScopeProvider.
final
disposeOnExitRequest → bool
Whether to dispose the graph when the OS asks the app to quit.
final
errorBuilder → Widget Function(BuildContext context, Object error, VoidCallback retry)?
Shown when the start throws. retry runs it again.
final
hashCode → int
The hash code for this object.
no setterinherited
initTimeout → Duration?
How long the graph may take to start before errorBuilder shows a CobaltInitTimeoutError naming what had not been built — the difference between a splash screen that hangs and one that says why. Null waits as long as it takes. Not used by CobaltAppScope.start, whose function starts the graph itself.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loading → Widget?
Shown while the graph starts, and again while a restart is in flight.
final
observers → List<CobaltObserver>
Observers for the whole tree; child scopes inherit them.
final
overrides → List<CobaltOverride<Object>> Function()?
Produces replacements for registrations root makes, called once per start.
final
restartOnGraphChange → bool
Whether a hot reload that changed what root registers restarts the graph.
final
root → CobaltScopeBuilder?
Declares what the root scope contains. Null only for CobaltAppScope.start.
final
rootName → String
Names the root scope in diagnostics. cobaltRootScopeName when generated.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
start → Future<CobaltScope> Function()?
Builds the root scope. Null unless built with CobaltAppScope.start.
final
warmUp → List<CobaltKey>
Lazy async registrations to start building as soon as the graph is up.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<CobaltAppScope>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

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

Static Methods

builder({required CobaltScopeBuilder root, List<CobaltBootstrapStep> bootstrap()?, String rootName = 'root', List<CobaltObserver> observers = const [], List<CobaltOverride<Object>> overrides()?, Duration? initTimeout, List<CobaltKey> warmUp = const [], Widget? loading, Widget errorBuilder(BuildContext context, Object error, VoidCallback retry)?, bool disposeOnExitRequest = false, bool restartOnGraphChange = true}) → TransitionBuilder
A CobaltAppScope shaped for MaterialApp.builder and its siblings.
of(BuildContext context) → CobaltAppScopeController
The controller of the nearest CobaltAppScope above context.