MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla

Revision 508935 of event/target

  • Revision slug: Mozilla/Add-ons/SDK/Low-Level_APIs/event_target
  • Revision title: event/target
  • Revision id: 508935
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

Stable

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.

Also see the tutorial on implementing event targets to get started with this API.

Instantiation

It's easy to create event target objects, no special arguments are required.

const { EventTarget } = require("sdk/event/target");
let target = EventTarget();

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:

target.on('message', function onMessage(message) {
  // Note: `this` pseudo variable is an event `target` unless
  // intentionally overridden via `.bind()`.
  console.log(message);
});

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:

target.once('ready', function onReady() {
  // Do the thing once ready!
});

Removing listeners

EventTarget interface defines API for unregistering event listeners, via removeListener method:

target.removeListener('message', onMessage);

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:

let { emit } = require('sdk/event/core');

target.on('hi', function(person) { console.log(person + ' says hi'); });
emit(target, 'hi', 'Mark'); // info: 'Mark says hi'

For more details see event/core documentation.

More details

Listeners registered during the event propagation (by one of the listeners) won't be triggered until next emit of the matching type:

let { emit } = require('sdk/event/core');

target.on('message', function onMessage(message) {
  console.log('listener triggered');
  target.on('message', function() {
    console.log('nested listener triggered');
  });
});

emit(target, 'message'); // info: 'listener triggered'
emit(target, 'message'); // info: 'listener triggered'
                         // info: 'nested listener triggered'

Exceptions in the listeners can be handled via 'error' event listeners:

target.on('boom', function() {
  throw Error('Boom!');
});
target.once('error', function(error) {
  console.log('caught an error: ' + error.message);
});
emit(target, 'boom');
// info: caught an error: Boom!

If there is no listener registered for error event or if it also throws exception then such exceptions are logged into a console.

Chaining

Emitters can also have their methods chained:

target.on('message', handleMessage)
  .on('data', parseData)
  .on('error', handleError);

EventTarget

Methods

initialize()

Method initializes this event source. It goes through properties of a given options and registers listeners for the ones that look like event listeners.

on(type, listener)

Registers an event listener that is called every time events of specified type are emitted.

worker.on('message', function (data) {
  console.log('data received: ' + data)
});
Parameters

type : String
The type of event.

listener : Function
The listener function that processes the event.

Returns

EventTarget : Returns the EventTarget instance

once(type, listener)

Registers an event listener that is called only once: the next time an event of the specified type is emitted.

Parameters

type : String
The type of event.

listener : Function
The listener function that processes the event.

Returns

EventTarget : Returns the EventTarget instance

removeListener(type, listener)

Removes an event listener for the given event type.

Parameters

type : String
The type of event.

listener : Function
The listener function that processes the event.

Returns

EventTarget : Returns the EventTarget instance

off()

An alias for removeListener.

Revision Source

<div class="note">
 <p>Stable</p>
</div>
<p><span class="seoSummary">Create objects that broadcast events.</span> Users of the object can listen to the events using the standard <code>on()</code> and <code>once()</code> functions.</p>
<h2 id="Usage">Usage</h2>
<p>Many objects in the SDK can broadcast events. For example, a <a href="modules/sdk/panel.html"><code>panel</code></a> instance emits an <code>show</code> event when the panel is shown. With this module you can create your own objects that emit events.</p>
<p>This module provides an exemplar <code>EventTarget</code> object, that implements an interface for adding and removing event listeners of a specific type. <code>EventTarget</code> is the base class for all objects in SDK on which events are emitted.</p>
<p>Also see the <a href="dev-guide/tutorials/event-targets.html">tutorial on implementing event targets</a> to get started with this API.</p>
<h3 id="Instantiation">Instantiation</h3>
<p>It's easy to create event target objects, no special arguments are required.</p>
<pre class="brush: js">
const { EventTarget } = require("sdk/event/target");
let target = EventTarget();</pre>
<p>For a convenience though optional <code>options</code> arguments may be used, in which case all the function properties with keys like: <code>onMessage</code>, <code>onMyEvent</code>... will be auto registered for associated <code>'message'</code>, <code>'myEvent'</code> events on the created instance. <em>All other properties of <code>options</code> will be ignored</em>.</p>
<h3 id="Adding_listeners">Adding listeners</h3>
<p><code>EventTarget</code> interface defines <code>on</code> method, that can be used to register event listeners on them for the given event type:</p>
<pre class="brush: js">
target.on('message', function onMessage(message) {
  // Note: `this` pseudo variable is an event `target` unless
  // intentionally overridden via `.bind()`.
  console.log(message);
});</pre>
<p>Sometimes event listener may care only about very first event of specific <code>type</code>. <code>EventTarget</code> interface defines convenience method for adding one shot event listeners via method <code>once</code>. Such listeners are called only once next time event of the specified type is emitted:</p>
<pre class="brush: js">
target.once('ready', function onReady() {
  // Do the thing once ready!
});</pre>
<h3 id="Removing_listeners">Removing listeners</h3>
<p><code>EventTarget</code> interface defines API for unregistering event listeners, via <code>removeListener</code> method:</p>
<pre class="brush: js">
target.removeListener('message', onMessage);</pre>
<h3 id="Emitting_events">Emitting events</h3>
<p><code>EventTarget</code> 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 <code>event/core</code> module instead:</p>
<pre class="brush: js">
let { emit } = require('sdk/event/core');

target.on('hi', function(person) { console.log(person + ' says hi'); });
emit(target, 'hi', 'Mark'); // info: 'Mark says hi'</pre>
<p>For more details see <strong>event/core</strong> documentation.</p>
<h3 id="More_details">More details</h3>
<p>Listeners registered during the event propagation (by one of the listeners) won't be triggered until next emit of the matching type:</p>
<pre class="brush: js">
let { emit } = require('sdk/event/core');

target.on('message', function onMessage(message) {
  console.log('listener triggered');
  target.on('message', function() {
    console.log('nested listener triggered');
  });
});

emit(target, 'message'); // info: 'listener triggered'
emit(target, 'message'); // info: 'listener triggered'
                         // info: 'nested listener triggered'</pre>
<p>Exceptions in the listeners can be handled via <code>'error'</code> event listeners:</p>
<pre class="brush: js">
target.on('boom', function() {
  throw Error('Boom!');
});
target.once('error', function(error) {
  console.log('caught an error: ' + error.message);
});
emit(target, 'boom');
// info: caught an error: Boom!</pre>
<p>If there is no listener registered for <code>error</code> event or if it also throws exception then such exceptions are logged into a console.</p>
<h3 id="Chaining">Chaining</h3>
<p>Emitters can also have their methods chained:</p>
<pre class="brush: js">
target.on('message', handleMessage)
  .on('data', parseData)
  .on('error', handleError);</pre>
<h2 id="EventTarget">EventTarget</h2>
<h3 id="Methods">Methods</h3>
<h4 class="addon-sdk-api-name" id="initialize()"><code>initialize()</code></h4>
<p>Method initializes <code>this</code> event source. It goes through properties of a given <code>options</code> and registers listeners for the ones that look like event listeners.</p>
<h4 class="addon-sdk-api-name" id="on(type.2C_listener)"><code>on(type, listener)</code></h4>
<p>Registers an event <code>listener</code> that is called every time events of specified <code>type</code> are emitted.</p>
<pre class="brush: js">
worker.on('message', function (data) {
  console.log('data received: ' + data)
});</pre>
<h5 id="Parameters">Parameters</h5>
<p><strong>type : String</strong><br />
 The type of event.</p>
<p><strong>listener : Function</strong><br />
 The listener function that processes the event.</p>
<h5 id="Returns">Returns</h5>
<p><strong>EventTarget</strong> : Returns the EventTarget instance</p>
<h4 class="addon-sdk-api-name" id="once(type.2C_listener)"><code>once(type, listener)</code></h4>
<p>Registers an event <code>listener</code> that is called only once: the next time an event of the specified <code>type</code> is emitted.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>type : String</strong><br />
 The type of event.</p>
<p><strong>listener : Function</strong><br />
 The listener function that processes the event.</p>
<h5 id="Returns">Returns</h5>
<p><strong>EventTarget</strong> : Returns the EventTarget instance</p>
<h4 class="addon-sdk-api-name" id="removeListener(type.2C_listener)"><code>removeListener(type, listener)</code></h4>
<p>Removes an event <code>listener</code> for the given event <code>type</code>.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>type : String</strong><br />
 The type of event.</p>
<p><strong>listener : Function</strong><br />
 The listener function that processes the event.</p>
<h5 id="Returns">Returns</h5>
<p><strong>EventTarget</strong> : Returns the EventTarget instance</p>
<h4 class="addon-sdk-api-name" id="off()"><code>off()</code></h4>
<p>An alias for <a href="modules/sdk/event/target.html#removeListener(type, listener)">removeListener</a>.</p>
Revert to this revision