Handling events¶
Events are emitted quite often by capabilities. In most cases the capability
will automatically emit events as needed, but when implementing custom
capabilities simply call emitEvent
.
API¶
-
emitEvent
(name[, payload[, options]])¶ Emit an event with the given name. By default only a single event will be emitted during a tick. So doing
emitEvent('test')
twice in a row will only emit a single event, see the options to change the behavior.Arguments: - name (string) – The name of the event.
- payload – Optional payload of the event. Can be any object that can be converted to
JSON. If omitted will be equal to
null
. - options – Optional object containing options for event emittal. The only option
available is
multiple
which can be set to allow multiple events to be emitted during the same tick.
Example:
this.emitEvent('test'); this.emitEvent('rotation', angle(102)); this.emitEvent('action', { name: 'test' }); this.emitEvent('test', null, { multiple: true });
For information about how to listen for events see Using things.
Common patterns¶
It is recommended to emit as few events as possible, such as only emitting an event when something changes.
As many capabilities extend state a common pattern for event emittal looks something like this:
updatePower(newPowerValue) {
if(this.updateState('power', newPowerValue)) {
// Emit event if new value was different from the previous value
this.emitEvent('power', newPowerValue);
}
}