Events

Configs

Common

The listener set for this object.

An object whose property names are the names of events to handle, or options which modifiy how the handlers are called.

See addListener for details about the options.

Listeners can be specified in target class config and they will be merged with any listeners specified in the instantiation config. Class listeners will be fired first:

class MyStore extends Store({
    static configurable = {
        listeners : {
            myCustomEvent() {
            },
            load : {
                prio : 10000,
                fn() { // this load listener handles things first }
            }
        }
    };
});

let store = new MyStore({
  listeners: {
    load: () => { // This load listener runs after the class's },
    ...
  }
});

Handlers as function name

Object event handlers may be specified as a function name. If a string is specified, it is the name of the function in the thisObj object.

If the string begins with up., this object's ownership hierarchy (if present) is scanned for an object which implements that function name:

new Popup({
    tbar : {
        items : {
            myCombo : {
                type      : 'combo',
                editable  : false,
                label     : 'Type',
                listeners : {
                    // Look in owner chain for this function name
                    change : 'up.onFilterChange'
                },
                items     : [
                    'Event',
                    'Task',
                    'Appointment'
                ]
            }
        }
    },
    items : {
        ...
    },
    onFilterChange({ value }) {
        // Handle event type selection here
    }
});

Misc

bubbleEvents: Object

An object where property names with a truthy value indicate which events should bubble up the ownership hierarchy when triggered.

const container = new Container({
    items : [
       { type : 'text', bubbleEvents : { change : true }}
    ],

    listeners : {
        change() {
            // Will catch change event from the text field
        }
    }
});

callOnFunctions: Boolean= falseAlso a property

Set to true to call onXXX method names (e.g. onShow, onClick), as an easy way to listen for events.

const container = new Container({
    callOnFunctions : true

    onHide() {
         // Do something when the 'hide' event is fired
    }
});

Other

catchEventHandlerExceptions: Boolean= falseAlso a property

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed.

Set this to true to catch exceptions thrown by this object's event handlers and continue processing the event. The exception will be rethrown on a zero millisecond timeout, so it will not destroy the stack.

Properties

Class hierarchy

isEvents: Boolean= truereadonly

Identifies an object as an instance of Events class, or subclass thereof.

isEvents: Boolean= truereadonlystatic

Identifies an object as an instance of Events class, or subclass thereof.

Misc

callOnFunctions: Boolean= falseAlso a config

Set to true to call onXXX method names (e.g. onShow, onClick), as an easy way to listen for events.

const container = new Container({
    callOnFunctions : true

    onHide() {
         // Do something when the 'hide' event is fired
    }
});

Other

catchEventHandlerExceptions: Boolean= falseAlso a config

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed.

Functions

addListener

Adds an event listener. This method accepts parameters in the following format:

 myObject.addListener({
     thisObj    : this,          // The this reference for the handlers
     eventname2 : 'functionName' // Resolved at invocation time using the thisObj,
     otherevent : {
         fn      : 'handlerFnName',
         once    : true          // Just this handler is auto-removed on fire
     },
     yetanother  : {
         fn      : 'yetAnotherHandler',
         args    : [ currentState1, currentState2 ] // Capture info to be passed to handler
     },
     prio        : 100           // Higher prio listeners are called before lower
 });

When listeners have a thisObj option, they are linked to the lifecycle of that object. When it is destroyed, those listeners are removed.

The config parameter allows supplying options for the listener(s), for available options see BryntumListenerConfig.

A simpler signature may be used when only adding a listener for one event and no extra options (such as once or delay) are required:

myObject.addListener('click', myController.handleClicks, myController);

The args in this simple case are eventName, handler and thisObj

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed. Set the catchEventHandlerExceptions config to true to catch exceptions thrown by this object's event handlers and allow the event to continue processing. The exception will be rethrown on a zero millisecond timeout,

Parameter	Type	Description
`config`	BryntumListenerConfig \| String	An object containing listener definitions, or the event name to listen for
`thisObj`	Object \| function	Default `this` reference for all listeners in the config object, or the handler function to call if providing a string as the first arg.
`oldThisObj`	Object	The `this` reference if the old signature starting with a string event name is used..

Returns: function -

Returns a detacher function unless configured with detachable: false. Call detacher to remove listeners

hasListener

Returns true if any listener is registered for the specified eventName, or if null, for any event.

Parameter	Type	Description
`eventName`	String	The event to test for listeners, or `null` for any event.

Returns: Boolean -

true if listener is registered, otherwise false

Alias for addListener. Adds an event listener. This method accepts parameters in the following format:

 myObject.on({
     thisObj    : this,          // The this reference for the handlers
     eventname2 : 'functionName' // Resolved at invocation time using the thisObj,
     otherevent : {
         fn      : 'handlerFnName',
         once    : true          // Just this handler is auto-removed on fire
     },
     yetanother  : {
         fn      : 'yetAnotherHandler',
         args    : [ currentState1, currentState2 ] // Capture info to be passed to handler
     },
     prio        : 100           // Higher prio listeners are called before lower
 });

When listeners have a thisObj option, they are linked to the lifecycle of that object. When it is destroyed, those listeners are removed.

The config parameter allows supplying options for the listener(s), for available options see BryntumListenerConfig.

A simpler signature may be used when only adding a listener for one event and no extra options (such as once or delay) are required:

myObject.on('click', myController.handleClicks, myController);

The args in this simple case are eventName, handler and thisObj

Parameter	Type	Description
`config`	BryntumListenerConfig \| String	An object containing listener definitions, or the event name to listen for
`thisObj`	Object \| function	Default `this` reference for all listeners in the config object, or the handler function to call if providing a string as the first arg.
`oldThisObj`	Object	The `this` reference if the old signature starting with a string event name is used..

Returns: function -

Returns a detacher function unless configured with detachable: false. Call detacher to remove listeners

relayAll

Relays all events through another object that also implements Events mixin. Adds a prefix to the event name before relaying, for example add -> storeAdd

// Relay all events from store through grid, will make it possible to listen for store events prefixed on grid:
'storeLoad', 'storeChange', 'storeRemoveAll' etc.
store.relayAll(grid, 'store');

grid.on('storeLoad', () => console.log('Store loaded');

Parameter	Type	Description
`through`	Events	Object to relay the events through, needs to mix Events mixin in
`prefix`	String	Prefix to add to event name
`transformCase`	Boolean	Specify false to prevent making first letter of event name uppercase

removeAllListeners

Removes all listeners registered to this object by the application.

removeListener

Removes an event listener. Same API signature as addListener

Parameter	Type	Description
`config`	Object \| String	A config object or the event name
`thisObj`	Object \| function	`this` reference for all listeners, or the listener function
`oldThisObj`	Object	`this` The `this` object for the legacy way of adding listeners

Returns: Boolean -

true if at least one listener was found and removed

resumeEvents

Resume event triggering after a call to suspendEvents(). If any triggered events were queued they will be triggered.

Returns: Boolean -

true if events have been resumed (multiple calls to suspend require an equal number of resume calls to resume).

suspendEvents

Prevents events from being triggered until resumeEvents() is called. Optionally queues events that are triggered while suspended. Multiple calls stack to require matching calls to resumeEvents() before actually resuming.

Parameter	Type	Description
`queue`	Boolean	Specify true to queue events triggered while suspended

trigger

Triggers an event, calling all registered listeners with the supplied arguments. Returning false from any listener makes function return false.

Parameter	Type	Description
`eventName`	String	Event name for which to trigger listeners
`param`	Object	Single parameter passed on to listeners, source property will be added to it (this)
`param.bubbles`	Boolean	Pass as `true` to indicate that the event will bubble up the widget ownership hierarchy. For example up a `Menu`->`parent` Menu tree, or a `Field`->`Container` tree.

Returns: Boolean | Promise -

Returns false if any listener returned false, or a Promise yielding true / false based on what is returned from the async listener functions, otherwise true

Shorthand for removeListener

Parameter	Type	Description
`config`	Object \| String	A config object or the event name
`thisObj`	Object \| function	`this` reference for all listeners, or the listener function
`oldThisObj`	Object	`this` The `this` object for the legacy way of adding listeners

Returns: Boolean -

true if at least one listener was found and removed

Events

beforeDestroy

Fires before an object is destroyed.

// Adding a listener using the "on" method
events.on('beforeDestroy', ({ source }) => {

});

Parameter	Type	Description
`source`	Base	The Object that is being destroyed.

catchAll

Fires when any other event is fired from the object.

Note: catchAll is fired for both public and private events. Please rely on the public events only.

// Adding a listener using the "on" method
events.on('catchAll', ({ event, event.type }) => {

});

Parameter	Type	Description
`event`	Object	The Object that contains event details
`event.type`	String	The type of the event which is caught by the listener

destroy

Fires when an object is destroyed.

// Adding a listener using the "on" method
events.on('destroy', ({ source }) => {

});

Parameter	Type	Description
`source`	Base	The Object that is being destroyed.

Event handlers

onBeforeDestroy

Called before an object is destroyed.

new Events({
    onBeforeDestroy({ source }) {

    }
});

Parameter	Type	Description
`source`	Base	The Object that is being destroyed.

onCatchAll

Called when any other event is called from the object.

Note: catchAll is called for both public and private events. Please rely on the public events only.

new Events({
    onCatchAll({ event }) {

    }
});

Parameter	Type	Description
`event`	Object	The Object that contains event details
`event.type`	String	The type of the event which is caught by the listener

onDestroy

Called when an object is destroyed.

new Events({
    onDestroy({ source }) {

    }
});

Parameter	Type	Description
`source`	Base	The Object that is being destroyed.

Typedefs

Parameter	Type	Description
`thisObj`	Object	The `this` reference for all listeners. May be overridden if a handler is specified in object form.
`once`	Boolean	Specify as `true` to remove the listener as soon as it is invoked.
`expires`	Number \| Object	The listener only waits for a specified time before being removed. The value may be a number or an object containing an expiry handler.
`expires.delay`	Number	How long to wait for the event for.
`expires.alt`	String \| function	The function to call when the listener expires without having been triggered.
`args`	Object[]	An array of arguments to be passed to the handler before the event object.
`prio`	Number	The priority for all listeners; higher priority listeners are called before lower.
`buffer`	Number	A buffer time in milliseconds to wait after last event trigger to call the handler, to reduce the amount of handler calls for frequent events.
`throttle`	Number	A millisecond timeout value to throttle event triggering. With it specified a handler will be called once immediately and then all following calls during the timeout period will be grouped together into one call once per throttle period.
`asap`	Boolean	Specify as `true` to invoke the listener in the next microtask, skipping the current call stack. This is useful to allow the current processing to complete before the handler is invoked.