event/target

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.

Create objects that broadcast events. Users of the object can listen to the events using the standard on() and once() functions.

Usage

Many objects in the SDK can broadcast events. For example, a panel instance emits an show event when the panel is shown. With this module you can create your own objects that emit events.

This module provides an exemplar EventTarget object, that implements an interface for adding and removing event listeners of a specific type. EventTarget is the base class for all objects in SDK on which events are emitted.

Instantiation

For a convenience though optional options arguments may be used, in which case all the function properties with keys like: onMessage, onMyEvent... will be auto registered for associated 'message', 'myEvent' events on the created instance. All other properties of options will be ignored.

Adding listeners

EventTarget interface defines on method, that can be used to register event listeners on them for the given event type:

Sometimes event listener may care only about very first event of specific type. EventTarget interface defines convenience method for adding one shot event listeners via method once. Such listeners are called only once next time event of the specified type is emitted:

Removing listeners

Emitting events

EventTarget interface intentionally does not define an API for emitting events. In majority of cases party emitting events is different from party registering listeners. In order to emit events one needs to use event/core module instead: