Events

Mixin

Mix this into another class to enable event handling.

Basic usage

Listeners can be added either through config:

let button = new Button({
  listeners: {
    click: () => {},
    press: () => {},
    ...
  }
});

NOTE: Do not reuse listeners config object, use new every time:

// wrong
let config = { click : () => {} }
new Button({
    listeners : config
})
new Button({
    listeners : config
})
// right
new Button({
    listeners : { click : () => {} }
})
new Button({
    listeners : { click : () => {} }
})

Or by calling on()/addListener():

let button = new Button();

button.addListener('press', () => {});
// on is an alias for addListener
button.on('click', () => {});

This style also accepts multiple listeners in same way as when using config:

button.on({
  click: () => {},
  press: () => {},
  ...
});

Handlers as function name

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., the owning 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
    }
});

Listener options

Once

Listeners can be configured to automatically deregister after first trigger by specifying config option once:

button.on({
  click: () => {},
  once: true
});

Priority

Specifying priority affects the order in which listeners are called when triggering an event. Higher priorities will be called before lower. Default value is 0.

button.on({
  click: this.onClick,
  prio: 1
});

This reference

If desired, you can specify thisObj when configuring listeners. There is no need if you are using arrow functions as listeners, but might be handy in other cases. Of course, you can also use bind to set this reference.

button.on({
  click: this.onClick,
  thisObj: this
});

// or

button.on({
  click: this.onClick.bind(this)
});

Buffering

By specifying a buffer events that fire frequently can be grouped together and delayed. A handler for the event will be called once only, when no new event has been fired during the specified buffer time:

button.on({
  click  : this.onClick,
  buffer : 200 // in milliseconds
});

In this example, if a user clicked the button 6 times very fast (<200ms between each click), the this.onClick handler would be called only once 200 milliseconds after the last click.

Throttling

Create a "debounced" function which will call on the "leading edge" of a timer period. When first invoked will call immediately, but invocations after that inside its buffer period will be rejected, and one invocation will be made after the buffer period has expired.

This is useful for responding immediately to a first mousemove, but from then on, only calling the action function on a regular timer while the mouse continues to move.

button.on({
  click    : this.onClick,
  throttle : 200 // in milliseconds
});

In this example, if a user clicked the button 6 times very fast, the this.onClick handler would be called once immediately on the first click and a second time 200 milliseconds after the first click. So in reality the click event handler will be called every 200ms independent of amount of click in a middle, if the event was triggered at least once during the throttle timeout.

Detacher

A convenient way of unregistering events is to use a detacher, a function returned when adding listeners that you call later to deregister them. As of version 1.0, detachable defaults to true.

let detacher = button.on({
  click: () => {},
  press: () => {},
  detachable: true
});

// when you want to detach, for example in destroy()
detacher();

Named listeners

Named listeners allow you to define event handlers with a specific name linked to the passed thisObj. This can be used to easily remove them later.

// The name is registered with the thisObj
button.on({
  name    : 'myButtonListeners',
  click   : 'myClickHandler',
  thisObj : this
});

And later you can remove them like this:

this.detachListeners('myButtonListeners');

Note that all listeners registered on that thisObj with the specified name on this object will be removed.

Auto detaching

When listeners are bound to a class instance using thisObj, the thisObj's doDestroy method is overridden to remove the listeners before calling the overridden doDestroy.

class MyClass extends Base {
  construct() {
    let button = new Button({
      listeners: {
        click: () => {},
        thisObj: this
      }
    });
  }

  doDestroy() {
    // clean up stuff
  }
}

let myObj = new MyClass();
// clean up, also removes listeners
myObj.destroy();

On-functions

When mixing Events into another class it can be configured to call on-functions when events are triggered. On-functions are functions named 'onEventName', for example 'onClick', 'onPress' declared on the class triggering the event.

// mix Events in with on-functions activated
let button = new Button({
  callOnFunctions: true,

  onClick: () => {}
});

// or add a getter in class declaration

Returning false from an on-function will prevent triggering listeners for the event.

Catching all events

By specifying a listener for catchAll a function can be notified when any event is triggered:

const button = new Button({
   listeners : {
       catchAll(event) {
           // All events on the button will pass through here
       }
   }
});

Preventable events

By returning false from a listener for an event documented as preventable the action that would otherwise be executed after the event is prevented. These events are usually named beforeXX, for example beforeRemove, beforeDragStart etc.

taskBoard.on({
    beforeColumnDrag({ columnRecord }) {
        if (columnRecord.locked) {
            return false;
        }
    }
});

const App = props => {
    function onBeforeColumnDrag({ columnRecord }) {
        if (columnRecord.locked) {
            return false;
        }
    }

    return (
        <>
            <BryntumTaskBoard onBeforeColumnDrag={onBeforeColumnDrag} />
        </>
    )
}

<bryntum-task-board @beforeColumnDrag="onBeforeColumnDrag" />

export default {
    methods : {
        onBeforeColumnDrag({ columnRecord }) {
            if (columnRecord.locked) {
                return false;
            }
        }
   }
}

<bryntum-task-board (onBeforeColumnDrag)="onBeforeColumnDrag({event : $event})"></bryntum-task-board>

export class AppComponent {
    onBeforeColumnDrag({ event }: { event: any }): void {
        event.returnValue = !event.columnRecord.locked;
    }
 }

Useful configs and functions

See also

• BryntumListenerConfig - Listener configuration options
• Delayable - Timer management mixin