Jump to:

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. 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.

Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.

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,