Unstable
The event/core module allows the creation of APIs to broadcast and subscribe to events.
Usage
Many modules in the SDK can broadcast events. For example, the tabs module emits an open event when a new tab is opened.
Also see the tutorial on implementing event targets to get started with this API.
An event listener may be registered to any event target using the on function:
var { on, once, off, emit } = require('sdk/event/core');
var target = { name: 'target' };
on(target, 'message', function listener(event) {
console.log('hello ' + event);
});
on(target, 'data', console.log);
An event of a specific type may be emitted on any event target object using the emit function. This will call all registered listeners for the given type on the given event target in the same order they were registered.
emit(target, 'message', 'event');
// info: 'hello event'
emit(target, 'data', { type: 'data' }, 'second arg');
// info: [Object object] 'second arg'
Registered event listeners may be removed using off function:
off(target, 'message'); emit(target, 'message', 'bye'); // info: 'hello bye'
Sometimes listener only cares about first event of specific type. To avoid hassles of removing such listeners there is a convenient once function:
once(target, 'load', function() {
console.log('ready');
});
emit(target, 'load')
// info: 'ready'
emit(target, 'load')
There are also convenient ways to remove registered listeners. All listeners of the specific type can be easily removed (only two argument must be passed):
off(target, 'message');
Also, removing all registered listeners is possible (only one argument must be passed):
off(target);
Globals
Functions
on(target, type, listener)
Registers an event listener that is called every time events of the specified type is emitted on the given event target.
Parameters
target : Object
Event target object.
type : String
The type of event.
listener : Function
The listener function that processes the event.
once(target, type, listener)
Registers an event listener that is called only once: the next time an event of the specified type is emitted on the given event target.
Parameters
target : Object
Event target object.
type : String
The type of event.
listener : Function
The listener function that processes the event.
emit(target, type, message, arguments)
Execute each of the listeners in order with the supplied arguments. All the exceptions that are thrown by listeners during the emit are caught and can be handled by listeners of 'error' event. Thrown exceptions are passed as an argument to an 'error' event listener. If no 'error' listener is registered exception will be logged into an error console.
Parameters
target : Object
Event target object.
type : String
The type of event.
message : Object|Number|String|Boolean
First argument that will be passed to listeners.
arguments : Object|Number|String|Boolean
More arguments that will be passed to listeners.
off(target, type, listener)
Removes an event listener for the given event type on the given event target. If no listener is passed removes all listeners of the given type. If type is not passed removes all the listeners of the given event target.
Parameters
target : Object
Event target object.
type : String
The type of event.
listener : Function
The listener function that processes the event.
count()
Returns a number of event listeners registered for the given event type on the given event target.
Returns
number : Number of listeners