ZenRoute class

A stateful widget that creates a ZenScope, initializes a ZenModule, and provides the scope to its child widget tree.

This widget handles the complete lifecycle of module-based dependency injection:

  • Creates or inherits a ZenScope with stack-based parent resolution
  • Registers and initializes a ZenModule
  • Provides scope access to child widgets
  • Handles cleanup on disposal
  • Maintains scope stack for hierarchical inheritance

Key features:

  • Stack-based hierarchical scope inheritance
  • Smart auto-dispose defaults
  • Comprehensive error handling
  • Layout-aware loading/error states
  • Debug logging integration
  • Automatic cleanup when navigating to routes with useParentScope=false
  • Proper Zen.currentScope synchronization

Example usage:

ZenRoute(
  moduleBuilder: () => MyModule(),
  page: MyPage(),
  scopeName: 'MyScope',
  useParentScope: true,
  autoDispose: true,
)
Inheritance

Constructors

ZenRoute.new({Key? key, required ZenModule moduleBuilder(), required Widget page, String? scopeName, bool? autoDispose, Widget onError(Object error)?, Widget? loadingWidget, bool? useParentScope, ZenScope? parentScope})
Creates a ZenRoute widget.
const

Properties

autoDispose bool?
Whether to automatically dispose the scope when the widget is disposed. If null, uses smart defaults based on parent scope presence.
final
hashCode int
The hash code for this object.
no setterinherited
key Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loadingWidget Widget?
Custom loading widget shown during module initialization. If not provided, shows a default loading UI that adapts to layout context.
final
moduleBuilder ZenModule Function()
Factory function that creates the module instance. Called during widget initialization.
final
onError Widget Function(Object error)?
Custom error handler for module initialization failures. If not provided, shows a default error UI with retry option.
final
page Widget
The main content widget that will receive the initialized scope.
final
parentScope ZenScope?
Explicit parent scope to inherit from. Takes precedence over useParentScope auto-discovery.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
scopeName String?
Optional name for the created scope. If not provided, a unique name will be generated.
final
useParentScope bool
Whether to automatically discover and inherit from parent scope. Uses stack-based tracking for reliable parent resolution. When false, this route acts as a "reset point" that cleans up other scopes.
final

Methods

createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() State<ZenRoute>
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