MastroBox<T extends MastroEvent> class abstract

MastroBox

A lightweight orchestrator for executing MastroEvents with well-defined concurrency semantics (solo / sequential / parallel). It also provides conveniences for UI signaling, loose callbacks, view lifecycle hooks, and automatic teardown of registered resources.

Key Responsibilities

Event Execution: Safely runs business logic encapsulated in MastroEvents.
Concurrency Control: Manages how events run relative to each other, preventing race conditions.
State Teardown: Automatically disposes of resources (like Mastro state) created within its scope.
UI Interaction: Signals view rebuilds and blocks back navigation during critical operations.
Lifecycle Hooks: Reacts to views being attached or detached.

Lifetime & Disposal

A MastroBox is typically provided to the widget tree via BoxScope and lives for the duration of that scope.

When the BoxScope is removed from the tree, internalDispose is called automatically.
Disposal is idempotent (safe to call multiple times).
After disposal, all public APIs will throw a StateError.
Resources created within the box are automatically cleaned up via Autowire.

Event Execution Policies

Each MastroEvent has an EventRunningMode that governs how it's scheduled:

parallel (default): Runs immediately without any coordination.
solo: If an event of the same type is already running, subsequent invocations are ignored until the first one completes. Use this for idempotent operations like a "Sync" button.
sequential: Events of the same type are queued and executed in FIFO order. Only one event of this type runs at a time. Use this for operations that must not overlap, like form submissions.

Use executeBlockPop to run an event while preventing the user from navigating back.
This requires a MastroHooks widget in the ancestor tree to handle the pop scope behavior.
For sequential events, the entire queue is processed under a single pop guard.

UI Signaling

Call tag with a string key to notify reactive widgets like MastroZone that are listening to that specific tag, triggering a rebuild.

Example

class AuthBox extends MastroBox<AuthEvent> {
  final user = Mastro<User?>.late();

  void onLoginSuccess(User loggedInUser) {
    user.value = loggedInUser;
    tag(tag: 'user-changed');
  }
}

// In your view:
await box.executeBlockPop(context, LoginEvent(email, pass));

Constructors

MastroBox(): Constructs a new MastroBox and calls the user-overridable init method.

Properties

hashCode → int: The hash code for this object.
no setterinherited
isDisposed → bool: Returns true if this box has been disposed.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

call({required String key, Map<String, dynamic>? data}) → void: Invokes a registered callback by its key.
dispose() → void: Called just before the box is permanently destroyed.
execute(T event, {Callbacks? callbacks, EventRunningMode? mode}) → Future<void>: Executes a MastroEvent.
executeBlockPop(BuildContext context, T event, {Callbacks? callbacks, EventRunningMode? mode}) → Future<void>: Executes an event while blocking back navigation.
init() → void: Called once after the box is constructed.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
onViewAttached(ViewMetaData metadata) → void: A lifecycle hook called after a MastroWidget attaches to this box.
onViewDetached(ViewMetaData metadata) → void: A lifecycle hook called after a MastroWidget detaches from this box.
registerCallback({required String key, required void callback(Map<String, dynamic>? data)}) → void: Registers (or overwrites) a callback for a given key.
tag({required String tag}) → void: Triggers a UI signal identified by tag.
toString() → String: A string representation of this object.
inherited
unregisterCallback({required String key}) → void: Removes a callback previously registered with key.

Operators

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