ActiveController class abstract

An application or feature owner for state, subscriptions and asynchronous work.

Disposal is terminal and idempotent. activeAsync tracks work; it does not cancel I/O. Check isDisposed after awaits before applying results; use generation tokens for stale responses (see the recipes gallery).

Gallery walkthrough · browser route /#/async. These examples use the current checkout; published 1.x APIs can differ.

Track an asynchronous operation

import 'package:activity/activity.dart';

class SampleController extends ActiveController {
  final value = ActiveString('idle');
  @override
  Iterable<ActiveType> get activities => [value];
}

Future<void> main() async {
  final controller = SampleController(); // This function owns it.
  try {
    await controller.activeAsync(() async {
      assert(controller.isTaskRunning(isRunningKey: 'load'));
      controller.value('ready');
    }, isRunningKey: 'load');
    assert(!controller.actively);
  } finally {
    await controller.dispose(); // Views borrowing it must not dispose it.
  }
}

Recover without discarding state

import 'package:activity/activity.dart';

class SampleController extends ActiveController {
  final value = ActiveString('draft');
  @override
  Iterable<ActiveType> get activities => [value];
}

Future<void> main() async {
  final controller = SampleController(); // This function owns it.
  try {
    try {
      await controller.activeAsync<void>(
        () async => throw StateError('offline'),
        isRunningKey: 'save',
      );
    } on StateError {
      assert(controller.value.value == 'draft'); // Retain the draft for retry.
    }
    assert(!controller.actively);
  } finally {
    await controller.dispose(); // Views borrowing it must not dispose it.
  }
}

Constructors

ActiveController()

Properties

actively → bool: no setter
activeTasks → List<String>: no setter
activities → Iterable<ActiveType>: List of all ActiveType instances managed by this controller.
no setter
hashCode → int: The hash code for this object.
no setterinherited
isDisposed → bool: no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

activate(Iterable<ActiveUpdate> updates) → void: Commits typed assignments with one notification.
activateTypes(List<Map<ActiveType, dynamic>> activeTypeList) → void: Updates multiple ActiveTypes with a single notification.
activeAsync<T>(Future<T> task(), {required String isRunningKey}) → Future<T>: Runs an async task and updates running status before and after.
addOnStateChangedListener(void onStateChanged(List<ActiveStateChanged> events)) → StreamSubscription<List<ActiveStateChanged>>: Adds a listener to state changes.
cancelSubscription(StreamSubscription? subscription) → Future<void>: Cancels a specific subscription.
dispose() → Future<void>: Terminal, idempotent cleanup. Pending tasks retain their result/error.
isTaskRunning({String? isRunningKey}) → bool: Checks if a task is currently running.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyActivities(List<ActiveStateChanged> events) → void: Notifies listeners of state changes.
onActiveError(ErrorEvent event) → void: Emits an error event to listeners.
onActiveErrorListener(void onError(ErrorEvent event)) → StreamSubscription<ErrorEvent>: Adds a listener to error events.
register(ActiveType value) → void: Register a value created after controller construction.
resetActivities() → Future<void>: Cleans up all resources and closes streams.
resetAllActiveTypes() → void: Resets all ActiveType values to their original state.
setIdle({required String isRunningKey}) → void: Marks the controller as idle (not running the task).
setRunning({required String isRunningKey}) → void: Marks the controller as currently running a task.
setRunningStatus({required bool isRunning, required String isRunningKey}) → void: Updates the running state and notifies listeners.
toString() → String: A string representation of this object.
inherited

Operators

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