Events

Events are a way to get notified of important lifecycle events in the Vyuh Framework as well to communicate between features.

The framework leverages a built-in EventPlugin to handle the propagation of events. It is a global event system that even allows features to communicate with each other. The event plugin can be referenced with vyuh.event.

Listening for Events

To listen for an event, you can use the on method on vyuh.event. The on<T>() method is a generic method based on the type of the Event and takes a typed-listener that matches the generic type. The method returns a disposer function that be invoked at a later point to cancel the event listener.

A typical place to set up an event-listener would be in the init method of a feature.

feature.dart

final feature = FeatureDescriptor(
  name: 'root',
  title: 'Vyuh Root Feature',
  description: 'The root feature for the Vyuh Demo app',
  init: () async {
    final disposer = vyuh.event.on<SystemReadyEvent>((event) {
      print('System is ready');
    });

    // At a later point, invoke the subscription disposer to cancel the event listener
    disposer();
  },

  // rest of the feature configuration
);

Tip

With the on method, you can listen for multiple events by skipping the Type specifier.

final disposer = vyuh.event.on((event) {
  print('${event.runtimeType} event received');
});

Listening for Events Once

You can listen to the events just once with the once method. This will remove the listener after the first time the event is triggered. Using the previous example of the SystemReadyEvent:

vyuh.event.once<SystemReadyEvent>((event) {
  print('System is ready');
});

The once methods also support listening to multiple events without specifying a type.

vyuh.event.once((event) {
  print('${event.runtimeType} event received');
});

Triggering Events

To trigger an event, you can use the emit method on vyuh.event. The emit method emits a type-safe event that is a subclass of VyuhEvent. Here is a simple example where the SystemReadyEvent is emitted:

vyuh.event.emit(SystemReadyEvent());

Elsewhere in the framework, the SystemReadyEvent is defined like so:

final class SystemReadyEvent extends VyuhEvent<void> {
  SystemReadyEvent() : super(name: 'vyuh.event.systemReady');
}

VyuhEvent

The VyuhEvent class is the base class for all events in the Vyuh Framework. It is a generic class that takes a type parameter that represents the payload of the event. The payload can be any type or void if the event does not have a payload.

The name of the event is a string that uniquely identifies the event. It is very common to use a reverse domain name notation for the event name. Additionally, the event class has a timestamp that represents the time when the event was created.

class VyuhEvent<T> {
  final String name;
  final DateTime timestamp;
  final T? data;

  VyuhEvent({
    required this.name,
    this.data,
  }) : timestamp = DateTime.now();
}

Standard Events

Currently, there is only one standard event in the Vyuh Framework:

• SystemReadyEvent: This event is triggered when the system is ready to start the application. It is a good place to initialize the application features.

Custom Events

You can create custom events by extending the VyuhEvent class. Here is an example of a custom event that carries a payload of type String:

class CustomEvent extends VyuhEvent<String> {
  CustomEvent(required super.data) : super(name: 'com.example.customEvent');
}

The custom event can be triggered like so:

vyuh.event.emit(CustomEvent('Hello, World!'));

Event Propagation

The event system in the Vyuh Framework is a global event system. The event propagation is synchronous and happens in the order of the event registration.

When an event is emitted, the event plugin iterates through all the event listeners and invokes them in the order they were registered. As mentioned earlier, you can cancel the event listener by invoking the disposer function returned by the on method.

Summary

Events are a powerful way to communicate between features in the Vyuh Framework. The event system is a global event system that allows features to listen to events and communicate with each other. The event system is synchronous and propagates events in the order of registration.