Improve events page

Author: SerafimArts

Writerside/topics/application.md

@@ -160,11 +160,32 @@ if ($app1->id->equals($app2->id)) {
 The application will automatically emit the following events (and intentions)
 during its lifecycle.
 
+To subscribe to events, you can use direct access to the
+<a href="events.md#event-listener">event listener</a>, using
+`Application::$events` property.
+
+```php
+$app->events->addEventListener(Event::class, function(Event $e) {
+    var_dump($e);
+});
+```
+
+The application instance also supports a more convenient and simple way of 
+registering events using the `on()` method.
+
+```php
+$app->on(function(Event $event): void {
+    var_dump($event);
+});
+```
+
 <note>
 More information about events can be found in the <a href="events.md">events 
 documentation</a>.
 </note>
 
+
+
 ### Starting Intention
 <secondary-label ref="intention"/>
 

Writerside/topics/events.md

@@ -60,26 +60,26 @@ that were registered after.
 
 ```php
 // ❌ event will NOT fired
-$parent->events->addEventListener(Event::class, fn($e) => ...);
+$app->events->addEventListener(Event::class, fn($e) => ...);
 
 // ✅ event will be fired (registered BEFORE the propagation stop)
-$child->events->addEventListener(Event::class, fn($e) => ...);
+$app->window->events->addEventListener(Event::class, fn($e) => ...);
 
 // ✅ event will be fired (callback stops "event bubbling")
-$child->events->addEventListener(Event::class, function($e): void {
+$app->window->events->addEventListener(Event::class, function($e): void {
     $e->stopPropagation();
 });
 
 // ❌ event will NOT fired (registered AFTER the propagation stop)
-$child->events->addEventListener(Event::class, fn($e) => ...);
+$app->window->events->addEventListener(Event::class, fn($e) => ...);
 ```
 
 The read-only property `Event::$isPropagationStopped` (or alternative 
 PSR-compatible method `Event::isPropagationStopped()`) is available to check 
 for propagation stop events.
 
 ```php
-if ($event->isPropagationStopped) {
+if ($app->event->isPropagationStopped) {
     echo 'Event propagation is stopped';
 }
 ```
@@ -107,7 +107,117 @@ application, the application will not be stopped. Therefore, the application
 stop event will not be called either.
 
 ```php
-$events->addEventListener(ApplicationStopping::class, function($e): void {
+$app->events->addEventListener(ApplicationStopping::class, function($e) {
     $e->cancel();
 });
 ```
+
+## Listener Provider
+
+Each core class such as [Application](application.md),
+[Window](window.md) and [WebView](webview.md) exposes
+events using `Boson\Dispatcher\EventListenerProviderInterface`.
+
+The provider exposes a property `EventListenerProviderInterface::$events`
+that contains an instance of `EventListenerInterface` (described below) and 
+a method `EventListenerProviderInterface::on()` that provides a simpler and 
+more convenient way to subscribe to events.
+
+### Simple Listen Events
+
+To subscribe to events, it is enough to call the `on()` method, which must 
+contain a callback with one parameter, which contains the event type.
+
+For example, to subscribe to the window creation event, you can write 
+the following code.
+
+```php
+use Boson\Application;
+use Boson\Window\Event\WindowCreated;
+
+$app = new Application();
+
+$app->on(function(WindowCreated $e): void {
+    echo 'Window ' . $e->subject->id . ' has been created';
+});
+```
+
+If you don't need to process the event object, you can use an alternative 
+option by passing the event name as the first parameter and the callback 
+as the second.
+
+```php
+use Boson\Application;
+use Boson\Window\Event\WindowCreated;
+
+$app = new Application();
+
+$app->on(WindowCreated::class, function(): void {
+    echo 'Window has been created';
+});
+```
+
+<tip>
+The second callback parameter also allows the event object to be present 
+as the first argument.
+
+<code-block lang="php">
+$app->on(Event::class, function(Event $e) { ... });
+</code-block>
+</tip>
+
+
+## Event Listener
+
+The `Boson\Dispatcher\EventListenerInterface` provides a way to subscribe to 
+and handle events in the Boson application. It allows you to register callbacks 
+that will be executed when specific events occur.
+
+### Listen Events
+
+To subscribe to events, you need to use the 
+`EventListenerInterface::addEventListener()` method:
+
+```php
+$app->events->addEventListener(Event::class, function(Event $event): void {
+    // Handle the event
+});
+```
+
+The first parameter is the event class you want to listen to, and the second 
+parameter is a callback function that will be executed when the event occurs.
+
+### Cancel Subscription
+
+Each `EventListenerInterface::addEventListener()` returns the 
+`SubscriptionInterface` object. To cancel a subscription, 
+use the `cancel()` method.
+
+```php
+$subscription = $app->events->addEventListener($event, $callback);
+
+// Cancel subscription
+$subscription->cancel();
+```
+
+<tip>
+The <code>EventListenerProviderInterface::on()</code> method also returns 
+a subscription object.
+
+<code-block lang="PHP">
+$subscription = $app->on(function(Event $e) { ... });
+
+// Cancel subscription
+$subscription->cancel();
+</code-block>
+</tip>
+
+### Cancel All Subscriptions
+
+To cancel all existing event subscriptions of a certain type, 
+call the `removeAllEventListenersForEvent()` method.
+
+```php
+// Cancel all EventName subscriptions
+$app->events->removeAllEventListenersForEvent(EventName::class);
+```

Writerside/topics/webview.md

@@ -150,6 +150,25 @@ enum State
 The webview will automatically emit the following events (and intentions)
 during its lifecycle.
 
+To subscribe to events, you can use direct access to the 
+<a href="events.md#event-listener">event listener</a>, using
+`WebView::$events` property.
+
+```php
+$app->events->addEventListener(Event::class, function(Event $e) {
+    var_dump($e);
+});
+```
+
+The webview instance also supports a more convenient and simple way of
+registering events using the `on()` method.
+
+```php
+$app->webview->on(function(Event $event): void {
+    var_dump($event);
+});
+```
+
 <note>
 More information about events can be found in the <a href="events.md">events 
 documentation</a>.

Writerside/topics/window.md

@@ -837,6 +837,25 @@ be used with caution.
 The window will automatically emit the following events (and intentions)
 during its lifecycle.
 
+To subscribe to events, you can use direct access to the
+<a href="events.md#event-listener">event listener</a>, using
+`Window::$events` property.
+
+```php
+$app->events->addEventListener(Event::class, function(Event $e) {
+    var_dump($e);
+});
+```
+
+The window instance also supports a more convenient and simple way of
+registering events using the `on()` method.
+
+```php
+$app->window->on(function(Event $event): void {
+    var_dump($event);
+});
+```
+
 <note>
 More information about events can be found in the <a href="events.md">events 
 documentation</a>.