Event
API for creating event dispatchers, binding listeners to those dispatchers, and dispatching events to those bound listeners.
It's safe to expose this API to addons, but you should avoid exposing the dispatcher objects themselves. The dispatcher is a regular table containing all bound event listeners, and while the structure of that table (i.e. the supported events) is immutable, the individual lists of callbacks for each event are not!
Instead, you should create wrappers for adding and removing listeners. For example:
def addEventListenerForAddons = fn(eventName, arg1, arg2)
return Event.addListener(myDispatcher, eventName, arg1, arg2)
end
Functions
Event.createDispatcher
Creates a new dispatcher with the given supported events. Calling any of the functions taking a dispatcher and event name will raise an error if the given event is not in this list.
Event.createDispatcher(eventNames: string[]): Dispatcher
Parameters
| Name | Type | Description |
|---|---|---|
| eventNames | string[] | List of supported event names. |
Returns
| Name | Type | Description |
|---|---|---|
| dispatcher | Dispatcher | No description |
Event.dispatch
Dispatch the given event to all listeners bound to it.
Event.dispatch(dispatcher: Dispatcher, eventName: string, ...: ...any)
Parameters
| Name | Type | Description |
|---|---|---|
| dispatcher | Dispatcher | Dispatcher to trigger the event on. |
| eventName | string | Event to dispatch. Must be supported by the dispatcher. |
| ... | ...any | Any additional arguments to pass to the listeners. |
Event.addListener
Bind a callback to listen to a dispatcher's event.
Event.addListener(dispatcher: Dispatcher, eventName: string, callback: fun(...: ...any)): function
Parameters
| Name | Type | Description |
|---|---|---|
| dispatcher | Dispatcher | Dispatcher to listen to. |
| eventName | string | Event to listen to. Must be supported by the dispatcher. |
| callback | fun(...: ...any) | Called when the event is fired with arguments passed by Event.dispatch. |
Returns
| Name | Type | Description |
|---|---|---|
| callback | function | Callback function that was passed in (for convenience to remove the listener later) |
Event.removeListener
Remove a callback that was bound to a dispatcher's event.
Event.removeListener(dispatcher: Dispatcher, eventName: string, callback: function)
Parameters
| Name | Type | Description |
|---|---|---|
| dispatcher | Dispatcher | Dispatcher to remove the listener from. |
| eventName | string | Event to remove the listener from. Must be supported by the dispatcher. |
| callback | function | Callback to remove. |
Types
Dispatcher
Table containing all event listeners bound to the dispatcher. Note that the dispatcher itself is immutable, however the lists of callbacks on each event name are not.
type Dispatcher = { .listeners: table }
Properties
| Field | Type | Description |
|---|---|---|
| listeners | table | Arrays of callbacks keyed off of the event names supported by the dispatcher. |