RtState

Tip

This documentation assumes you’ve already read the State Management. It’s recommended read that first if you’re new in Reactter.

The RtState class is a foundational class in the Reactter framework, designed to manage state in a Dart application. It provides a structured way to create, update, and dispose of state, ensuring that state changes are tracked and propagated efficiently. This class is typically extended to create custom state that can be used within the Reactter ecosystem.

Syntax

abstract class RtState<E extends RtState<E>> {
  String? get debugLabel;
  Map<String, dynamic> get debugInfo;
  void update(Function? fnUpdate)
  void notify()
  void bind(Object instance)
  void unbind()
  void dispose()
}

Properties & Methods

• debugLabel: A string that represents the label of the state object for debugging purposes.
• debugInfo: A map that contains debug information about the state object.

• update : Executes a callback function and notify its observers that the state has changed. When it is invoked, it emits two lifecycle events to signal the state transition:
  • Lifecycle.willUpdate is emitted first, indicating the impending update.
  • Lifecycle.didUpdate is emitted once the update process is complete.
• notify : Forces the state to notify its observers. Unlike update , it emits only the Lifecycle.didUpdate event, as it doesn’t involve any preparatory steps before the notification.
• bind : Establishes a connection between the state and a specific instance. This connection allows the instance to reactively update based on changes to the state. By binding the state, the instance becomes aware of changes to the state and can appropriately reflect those changes in its behavior.
• unbind : Releases the connection between the state and the instance. When unbinding, the instance will no longer receive updates from the state. This can be useful when an instance is no longer actively using the state or when it needs to detach from the state temporarily or permanently.
• dispose : Is responsible for cleaning up the state and any associated observers or resources. Disposing of the state ensures that it is properly released and no longer consumes memory or processing resources unnecessarily.

Note

While the bind , unbind and dispose methods are normally used to manage the lifecycle of a state, Reactter handles this automatically, when the state is declared inside an instance that exists within Reactter’s context via the dependecy injection, so you don’t need to worry about it(Learn more about Binding State to Dependency).

Usage

Declaration

To create a custom state, extend the RtState class and define the state properties and methods. Register the state using Rt.registerState or as a dependency within the Reactter framework, e.g.:

class MyState extends RtState<MyState> {
  int _value = 0;
  int get value => _value;
  set value(int n) {
    if (n == _value) return;
    update(() => _value = n); // set new value and notify observers
  }

  MyState([int value = 0]) : _value = value;
}

final state = Rt.registerState<MyState>(() => MyState()); // Register state

Rt.on(
  state,
  Lifecycle.didUpdate,
  (_, __) => print('State updated: ${state.value}')
);

state.value = 42; // Calls update internally

Tip

You can also use the factory constructor to create a state, e.g.:

class MyState extends RtState<MyState> {
  int _value = 0;
  int get value => _value;
  set value(int n) {
    if (n == _value) return;
    update(() => _value = n); // set new value and notify observers
  }

  MyState._([int value = 0]) : _value = value;

  factory MyState(int value) {
    return Rt.registerState(() => MyState._(value)); // Register state
  }
}

Rt.on(
  state,
  Lifecycle.didUpdate,
  (_, __) => print('State updated: ${state.value}')
);

state.value = 42; // Calls update internally

This approach allows you to create a state directly without the need to call the Rt.registerState method explicitly.

Updating the state

To update the state, call the update method and provide a callback function that modifies the state, e.g.:

class MyState extends RtState<MyState> {
  int _value = 0;
  int get value => _value;
  set value(int n) {
    if (n == _value) return;
    update(() => _value = n); // set new value and notify observers
  }

  MyState._([int value = 0]) : _value = value;

  factory MyState(int value) {
    return Rt.registerState(() => MyState._(value)); // Register state
  }
}

Rt.on(
  state,
  Lifecycle.didUpdate,
  (_, __) => print('State updated: ${state.value}')
);

state.value = 42; // Calls update internally

Listening to changes

When a state is updated, it emits the following lifecycle events:

• Lifecycle.willUpdate event is triggered before the callback function of update method have been executed.
• Lifecycle.didUpdate event is triggered after the callback function of update method have been executed or after the notify method have been invoked.

class MyState extends RtState<MyState> {
  int _value = 0;
  int get value => _value;
  set value(int n) {
    if (n == _value) return;
    update(() => _value = n); // set new value and notify observers
  }

  MyState._([int value = 0]) : _value = value;

  factory MyState(int value) {
    return Rt.registerState(() => MyState._(value)); // Register state
  }
}

Rt.on(
  state,
  Lifecycle.didUpdate,
  (_, __) => print('State updated: ${state.value}')
);

state.value = 42; // Calls update internally