Signal

Signal is reactive state that encapsulate a value changing over time. When the value of a signal changes, it automatically notifies its observers.

Syntax

  Signal<T>(T initialValue);

Signal accepts this parameter:

• initialValue: Initial value of T type that the it will hold.

Properties & Methods

Signal provides the following properties and methods:

• value: A getter/setter that allows to read and write its state.

• Various properties and methods depending on the type of T . For example, if T is a List , you can use the methods and properties of the List class:

  final listSignal = Signal<List<int>>([]);
  listSignal.addAll([1, 2, 3]);
  listSignal.removeAt(0);
  listSignal.clear();

Properties and methods inherited from RtState

• 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

Signal can be initialized using the constructor class:

final intSignal = Signal<int>(0);
final strSignal = Signal("initial value");
final userSignal = Signal(User());

Note

In some cases, you may need to declare a state variable that will be initialized later. For this, you can use the late keyword. When using Signal as late within a dependency(class registered via the dependency injection), use Rt.lazyState (Learn more about Lazy state binding). e.g:

counter_controller.dart

class CounterController {
  final int initialCount;

  late final count = Rt.lazyState(
    () => Signal(this.initialCount),
    this
  );

  Counter([this.initialCount = 0]);
}

Reading and writing the value

Signal has a value property that allows to read and write its state:

intSignal.value = 10;
print("Current state: ${intSignal.value}");

or also can use the callable function:

intSignal(10);
print("Current state: ${intSignal()}");

or simply use .toString() implicit to get its value as String:

print("Current state: $intSignal");

Note

Signal notifies that its value has changed when the previous value is different from the current value. If its value is an Object , it does not detect internal changes, only when value is setted to another Object . Learn more about updating objects in state.

Updating the value

Use update method to notify changes after run a set of instructions:

userSignal.update((user) {
  user.firstname = "Firstname";
  user.lastname = "Lastname";
});

Use notify method to force to notify changes.

userSignal.notify();

Listening to changes

When value has changed, the Signal will emit the following events(learn about it here):

• Lifecycle.willUpdate event is triggered before the change in value or update method have been invoked.
• Lifecycle.didUpdate event is triggered after the change in value or after update or notify methods have been invoked.

Example of listening to changes:

Rt.on(
  mySignal,
  Lifecycle.didUpdate,
  (_, state) => print("State value has changed to: ${state.value}"),
);

With Flutter

RtSignalWatcher is a way to keep the widgets automatically updates, accessing the value of Signal reactively.