event/core

We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.

Don't use these techniques to develop new add-ons. Use WebExtensions instead.

If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions instead.

Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

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

Document Tags and Contributors

 Contributors to this page: wbamberg, jsantell
 Last updated by: wbamberg,