> For the complete documentation index, see [llms.txt](https://pahutyakv.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pahutyakv.gitbook.io/docs/evently/evently-listener.md).

# Evently Listener

`EventlyListener<T>` represents a single event subscription within the Evently system.\
It acts as a wrapper around the event handler and provides additional functionality such as conditional execution, one-time invocation, and automatic lifetime management.

When you subscribe to an event using `Evently.Subscribe<T>()`, the system returns an `EventlyListener<T>` instance. This instance allows you to further configure how the listener behaves and how long it should remain active.

Example:

```csharp
var listener = Evently.Subscribe<PlayerDiedEvent>(OnPlayerDied);
```

The returned listener can then be configured using the fluent API.

***

### <mark style="color:$success;">Lifecycle</mark>

A listener remains active until one of the following happens:

* it is explicitly disposed
* it is cancelled
* it executes once when `.Once()` is used
* the bound `MonoBehaviour` is destroyed when `.BindTo()` is used

Once disposed, the listener is removed from the Evently bus and will no longer receive events.

***

### <mark style="color:$success;">Manual Cancelling</mark>

A listener can be cancelled manually at any time. Cancelling removes the listener from the Evently bus and prevents it from receiving future events.

Evently provides two equivalent ways to cancel a listener:

```csharp
listener.Cancel();
listener.Dispose();
```

Both methods perform the same operation.\
`Cancel()` exists as a more expressive alias when the intention is to stop listening to an event.

***

### <mark style="color:$success;">Automatic Listener Disposal</mark>

Evently also supports automatic disposal mechanisms that remove listeners without requiring manual cancellation.

A listener may be disposed automatically when:

#### Once()

If `.Once()` is used, the listener automatically disposes itself after the first successful invocation.

```csharp
Evently.Subscribe<PlayerDiedEvent>(OnPlayerDied)
       .Once();
```

#### BindTo()

If `.BindTo()` is used, the listener is disposed when the bound `MonoBehaviour` is destroyed.

```csharp
Evently.Subscribe<PlayerDiedEvent>(OnPlayerDied)
       .BindTo(this);
```

This integrates the listener lifecycle with the Unity object lifecycle and helps avoid forgotten subscriptions.

***

### <mark style="color:$success;">Where()</mark>

The `Where()` method adds a condition that must be satisfied before the listener is invoked.

Instead of executing the handler for every published event, Evently evaluates the provided predicate first.\
The handler is only executed if the condition returns `true`.

This allows listeners to react only to specific events without adding filtering logic inside the handler itself.

Example:

```csharp
Evently.Subscribe<PlayerDiedEvent>(OnPlayerDied)
       .Where(e => e.PlayerId == 5);
```

In this example, the listener will only be triggered when the event's `PlayerId` equals `5`.\
Events that do not satisfy the condition will be ignored.