playcanvas/build/playcanvas/src/core/event-handler.d.ts

PlayCanvas WebGL game engine

/**
 * Callback used by {@link EventHandler} functions. Note the callback is limited to 8 arguments.
 */
export type HandleEventCallback = (arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any) => void;
/**
 * @callback HandleEventCallback
 * Callback used by {@link EventHandler} functions. Note the callback is limited to 8 arguments.
 * @param {any} [arg1] - First argument that is passed from caller.
 * @param {any} [arg2] - Second argument that is passed from caller.
 * @param {any} [arg3] - Third argument that is passed from caller.
 * @param {any} [arg4] - Fourth argument that is passed from caller.
 * @param {any} [arg5] - Fifth argument that is passed from caller.
 * @param {any} [arg6] - Sixth argument that is passed from caller.
 * @param {any} [arg7] - Seventh argument that is passed from caller.
 * @param {any} [arg8] - Eighth argument that is passed from caller.
 * @returns {void}
 */
/**
 * Abstract base class that implements functionality for event handling.
 *
 * ```javascript
 * const obj = new EventHandlerSubclass();
 *
 * // subscribe to an event
 * obj.on('hello', (str) => {
 *     console.log('event hello is fired', str);
 * });
 *
 * // fire event
 * obj.fire('hello', 'world');
 * ```
 */
export class EventHandler {
    /**
     * @type {Map<string,Array<EventHandle>>}
     * @private
     */
    private _callbacks;
    /**
     * @type {Map<string,Array<EventHandle>>}
     * @private
     */
    private _callbackActive;
    /**
     * Reinitialize the event handler.
     * @ignore
     */
    initEventHandler(): void;
    /**
     * Registers a new event handler.
     *
     * @param {string} name - Name of the event to bind the callback to.
     * @param {HandleEventCallback} callback - Function that is called when event is fired. Note
     * the callback is limited to 8 arguments.
     * @param {object} scope - Object to use as 'this' when the event is fired, defaults to
     * current this.
     * @param {boolean} once - If true, the callback will be unbound after being fired once.
     * @returns {EventHandle} Created {@link EventHandle}.
     * @ignore
     */
    _addCallback(name: string, callback: HandleEventCallback, scope: object, once: boolean): EventHandle;
    /**
     * Attach an event handler to an event.
     *
     * @param {string} name - Name of the event to bind the callback to.
     * @param {HandleEventCallback} callback - Function that is called when event is fired. Note
     * the callback is limited to 8 arguments.
     * @param {object} [scope] - Object to use as 'this' when the event is fired, defaults to
     * current this.
     * @returns {EventHandle} Can be used for removing event in the future.
     * @example
     * obj.on('test', (a, b) => {
     *     console.log(a + b);
     * });
     * obj.fire('test', 1, 2); // prints 3 to the console
     * @example
     * const evt = obj.on('test', (a, b) => {
     *     console.log(a + b);
     * });
     * // some time later
     * evt.off();
     */
    on(name: string, callback: HandleEventCallback, scope?: object): EventHandle;
    /**
     * Attach an event handler to an event. This handler will be removed after being fired once.
     *
     * @param {string} name - Name of the event to bind the callback to.
     * @param {HandleEventCallback} callback - Function that is called when event is fired. Note
     * the callback is limited to 8 arguments.
     * @param {object} [scope] - Object to use as 'this' when the event is fired, defaults to
     * current this.
     * @returns {EventHandle} - can be used for removing event in the future.
     * @example
     * obj.once('test', (a, b) => {
     *     console.log(a + b);
     * });
     * obj.fire('test', 1, 2); // prints 3 to the console
     * obj.fire('test', 1, 2); // not going to get handled
     */
    once(name: string, callback: HandleEventCallback, scope?: object): EventHandle;
    /**
     * Detach an event handler from an event. If callback is not provided then all callbacks are
     * unbound from the event, if scope is not provided then all events with the callback will be
     * unbound.
     *
     * @param {string} [name] - Name of the event to unbind.
     * @param {HandleEventCallback} [callback] - Function to be unbound.
     * @param {object} [scope] - Scope that was used as the this when the event is fired.
     * @returns {EventHandler} Self for chaining.
     * @example
     * const handler = () => {};
     * obj.on('test', handler);
     *
     * obj.off(); // Removes all events
     * obj.off('test'); // Removes all events called 'test'
     * obj.off('test', handler); // Removes all handler functions, called 'test'
     * obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
     */
    off(name?: string, callback?: HandleEventCallback, scope?: object): EventHandler;
    /**
     * Detach an event handler from an event using EventHandle instance. More optimal remove
     * as it does not have to scan callbacks array.
     *
     * @param {EventHandle} handle - Handle of event.
     * @ignore
     */
    offByHandle(handle: EventHandle): this;
    /**
     * Fire an event, all additional arguments are passed on to the event listener.
     *
     * @param {string} name - Name of event to fire.
     * @param {any} [arg1] - First argument that is passed to the event handler.
     * @param {any} [arg2] - Second argument that is passed to the event handler.
     * @param {any} [arg3] - Third argument that is passed to the event handler.
     * @param {any} [arg4] - Fourth argument that is passed to the event handler.
     * @param {any} [arg5] - Fifth argument that is passed to the event handler.
     * @param {any} [arg6] - Sixth argument that is passed to the event handler.
     * @param {any} [arg7] - Seventh argument that is passed to the event handler.
     * @param {any} [arg8] - Eighth argument that is passed to the event handler.
     * @returns {EventHandler} Self for chaining.
     * @example
     * obj.fire('test', 'This is the message');
     */
    fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler;
    /**
     * Test if there are any handlers bound to an event name.
     *
     * @param {string} name - The name of the event to test.
     * @returns {boolean} True if the object has handlers bound to the specified event name.
     * @example
     * obj.on('test', () => {}); // bind an event to 'test'
     * obj.hasEvent('test'); // returns true
     * obj.hasEvent('hello'); // returns false
     */
    hasEvent(name: string): boolean;
}
import { EventHandle } from './event-handle.js';