classDocs / Event

Event

classsharedsource

Object → Event

A named list of handlers called one after another, a simpler Hook.

There are no stages and no return values: call runs every handler in priority order (lower first, equal priorities keep attach order) and returns nothing. Each handler runs in protected mode, a failing handler is reported and never stops the others.

Calls may nest, handlers attached during a call run from the next call on, handlers detached during a call are skipped right away.

Constructor

Event(name: string?): Event

Fields

Name	Type	Description
`name`	`string`	The name of the event.

Methods

`attach`	Attaches a handler to the event.
`await`	Suspends the caller until the event is next called, then returns its arguments.
`call`	Runs every attached handler with ..., in priority order.
`clear`	Removes every handler attached to the event.
`detach`	Detaches a handler previously passed to attach or once.
`isRunning`	Checks if the event is running currently.
`once`	Attaches a one-shot handler, detached right before it runs.

#Event:attach

sharedsource

function Event:attach(handler: Event.Handler, priority: integer | nil)

Attaches a handler to the event.

If the handler is already attached, only its priority is updated (when a new one is supplied); it will not be attached twice.

Parameters

Name	Type	Description
`handler`	`Event.Handler`	The callback or callable object, receives the `call` arguments.
`priority`	`integer \| nil`	The priority of the handler; handlers with a lower value run earlier. Defaults to `0`.

#Event:await

sharedasyncsource

async function Event:await(): any

Suspends the caller until the event is next called, then returns its arguments.

Returns

Type	Name	Description
`any`	`...`	The arguments the event was called with.

#Event:call

sharedsource

function Event:call(...: any)

Runs every attached handler with ..., in priority order.

Each handler runs in protected mode: errors are reported and the rest still run. Non-function handlers are called through their __call metamethod with themselves first.

Parameters

Name	Type	Description
`...`	`any`	Arguments forwarded to every handler.

#Event:clear

sharedsource

function Event:clear()

Removes every handler attached to the event.

Handlers still pending in a running call are skipped.

#Event:detach

sharedsource

function Event:detach(handler: Event.Handler): boolean

Detaches a handler previously passed to attach or once.

Detaching during a call skips the handler in every call in progress.

Parameters

Name	Type	Description
`handler`	`Event.Handler`	The exact handler reference.

Returns

Type	Name	Description
`boolean`	`is_detached`	Returns `true` if the handler was attached, otherwise `false`.

#Event:isRunning

sharednodiscardsource

function Event:isRunning(): boolean

Checks if the event is running currently.

Returns

Type	Name	Description
`boolean`	`is_running`	Returns `true` if the event is running currently, otherwise `false`.

#Event:once

sharedsource

function Event:once(handler: Event.Handler, priority: integer | nil)

Attaches a one-shot handler, detached right before it runs.

It can still be removed with detach using the same handler reference.

Parameters

Name	Type	Description
`handler`	`Event.Handler`	The callback or callable object, receives the `call` arguments.
`priority`	`integer \| nil`	The priority of the handler; handlers with a lower value run earlier. Defaults to `0`.