# Events

Class

Source: https://github.com/playcanvas/playcanvas-observer/blob/7b88674dee207b87954eabfb61685546418ad536/src/events.ts#L38

Base class for event handling, providing mechanisms to register, emit, and unbind events. This
class supports adding event listeners, emitting events with up to 8 arguments, and managing
multiple emitters.

**Example**

```ts
// Create an instance of the Events class
const events = new Events();

// Register an event listener
events.on('testEvent', (arg1, arg2) => {
    console.log('Event triggered with arguments:', arg1, arg2);
});

// Emit the event
events.emit('testEvent', 'value1', 'value2');

// Unbind the event listener
events.unbind('testEvent');
```

## Constructors

### constructor

```ts
new Events()
```

Creates a new Events instance.

## Accessors

### suspendEvents

```ts
get suspendEvents(): boolean
set suspendEvents(value: boolean)
```

Gets whether events are suspended.

## Methods

### addEmitter

```ts
addEmitter(emitter: Events): void
```

Adds another emitter. Any events fired by this instance will also be fired on the additional
emitter.

**Parameters**

- `emitter` ([`Events`](https://api.playcanvas.com/observer/classes/Events.md)): The emitter

### emit

```ts
emit(name: string, arg0?: any, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any): Events
```

Emits the specified event, executing all registered listeners for that event with the
provided arguments. If events are suspended, the emit operation will be ignored.

**Parameters**

- `name` (`string`): The name of the event to emit.
- `arg0` (`any`, optional): The first argument to pass to the event listeners.
- `arg1` (`any`, optional): The second argument to pass to the event listeners.
- `arg2` (`any`, optional): The third argument to pass to the event listeners.
- `arg3` (`any`, optional): The fourth argument to pass to the event listeners.
- `arg4` (`any`, optional): The fifth argument to pass to the event listeners.
- `arg5` (`any`, optional): The sixth argument to pass to the event listeners.
- `arg6` (`any`, optional): The seventh argument to pass to the event listeners.
- `arg7` (`any`, optional): The eighth argument to pass to the event listeners.

**Returns** [`Events`](https://api.playcanvas.com/observer/classes/Events.md): The current instance for chaining.

**Example**

```ts
// Register an event listener
events.on('testEvent', (arg1, arg2) => {
    console.log('Event triggered with arguments:', arg1, arg2);
});

// Emit the event
events.emit('testEvent', 'value1', 'value2');

// Emit the event with more arguments
events.emit('testEvent', 'value1', 'value2', 'value3', 'value4');
```

### on

```ts
on(name: string, fn: HandleEvent): EventHandle
```

Registers an event listener for the specified event name. If the event is emitted,
the callback function is executed with up to 8 arguments.

**Parameters**

- `name` (`string`): The name of the event to listen for.
- `fn` ([`HandleEvent`](https://api.playcanvas.com/observer/types/HandleEvent.md)): The callback function to be executed when the event is emitted.

**Returns** [`EventHandle`](https://api.playcanvas.com/observer/classes/EventHandle.md): An EventHandle object that can be used to unbind the event listener.

**Example**

```ts
// Register an event listener
events.on('testEvent', (arg1, arg2) => {
    console.log('Event triggered with arguments:', arg1, arg2);
});

// Emit the event
events.emit('testEvent', 'value1', 'value2');
```

### once

```ts
once(name: string, fn: HandleEvent): EventHandle
```

Registers a one-time event listener for the specified event name. The callback function is
executed the next time the event is emitted, and then automatically unbound.

**Parameters**

- `name` (`string`): The name of the event to listen for.
- `fn` ([`HandleEvent`](https://api.playcanvas.com/observer/types/HandleEvent.md)): The callback function to be executed once when the event is emitted.

**Returns** [`EventHandle`](https://api.playcanvas.com/observer/classes/EventHandle.md): An EventHandle object that can be used to unbind the event listener
before it is triggered.

**Example**

```ts
// Register a one-time event listener
events.once('testEvent', (arg1, arg2) => {
    console.log('Event triggered once with arguments:', arg1, arg2);
});

// Emit the event
events.emit('testEvent', 'value1', 'value2'); // The callback will be called and then unbound.

// Emit the event again
events.emit('testEvent', 'value1', 'value2'); // The callback will not be called this time.
```

### removeEmitter

```ts
removeEmitter(emitter: Events): void
```

Removes emitter.

**Parameters**

- `emitter` ([`Events`](https://api.playcanvas.com/observer/classes/Events.md)): The emitter

### unbind

```ts
unbind(name?: string, fn?: HandleEvent): Events
```

Unbinds an event listener for the specified event name. If a callback function is provided,
only that specific listener is removed. If no callback is provided, all listeners for the
event are removed. If no event name is provided, all listeners for all events are removed.

**Parameters**

- `name` (`string`, optional): The name of the event to unbind. If not provided, all events are
  unbound.
- `fn` ([`HandleEvent`](https://api.playcanvas.com/observer/types/HandleEvent.md), optional): The specific callback function to remove. If not provided, all
  listeners for the event are removed.

**Returns** [`Events`](https://api.playcanvas.com/observer/classes/Events.md): The current instance for chaining.

**Example**

```ts
// Register an event listener
const callback = (arg1, arg2) => {
    console.log('Event triggered with arguments:', arg1, arg2);
};
events.on('testEvent', callback);

// Unbind the specific event listener
events.unbind('testEvent', callback);

// Unbind all listeners for a specific event
events.unbind('testEvent');

// Unbind all listeners for all events
events.unbind();
```