mozilla

Revision 510109 of event/core

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

Revision Content

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

Revision Source

<div class="note">
 <p>Unstable</p>
</div>
<p><span class="seoSummary">The <code>event/core</code> module allows the creation of APIs to broadcast and subscribe to events.</span></p>
<h2 id="Usage">Usage</h2>
<p>Many modules in the SDK can broadcast events. For example, the <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code></a> module emits an <code>open</code> event when a new tab is opened.</p>
<p>Also see the <a href="/en-US/Add-ons/SDK/Tutorials/Creating_event_targets">tutorial on implementing event targets</a> to get started with this API.</p>
<p>An event <code>listener</code> may be registered to any event <code>target</code> using the <code>on</code> function:</p>
<pre class="brush: js">
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);</pre>
<p>An event of a specific <code>type</code> may be emitted on any event <code>target</code> object using the <code>emit</code> function. This will call all registered <code>listener</code>s for the given <code>type</code> on the given event <code>target</code> in the same order they were registered.</p>
<pre class="brush: js">
emit(target, 'message', 'event');
// info: 'hello event'
emit(target, 'data', { type: 'data' }, 'second arg');
// info: [Object object] 'second arg'
</pre>
<p>Registered event listeners may be removed using <code>off</code> function:</p>
<pre class="brush: js">
off(target, 'message');
emit(target, 'message', 'bye');
// info: 'hello bye'
</pre>
<p>Sometimes listener only cares about first event of specific <code>type</code>. To avoid hassles of removing such listeners there is a convenient <code>once</code> function:</p>
<pre class="brush: js">
once(target, 'load', function() {
  console.log('ready');
});
emit(target, 'load')
// info: 'ready'
emit(target, 'load')
</pre>
<p>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):</p>
<pre class="brush: js">
off(target, 'message');
</pre>
<p>Also, removing all registered listeners is possible (only one argument must be passed):</p>
<pre class="brush: js">
off(target);
</pre>
<h2 id="Globals">Globals</h2>
<h3 id="Functions">Functions</h3>
<h4 class="addon-sdk-api-name" id="on(target.2C_type.2C_listener)"><code>on(target, type, listener)</code></h4>
<p>Registers an event <code>listener</code> that is called every time events of the specified <code>type</code> is emitted on the given event <code>target</code>.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>target : Object</strong><br />
 Event target object.</p>
<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>
<h4 class="addon-sdk-api-name" id="once(target.2C_type.2C_listener)"><code>once(target, 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 on the given event <code>target</code>.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>target : Object</strong><br />
 Event target object.</p>
<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>
<h4 class="addon-sdk-api-name" id="emit(target.2C_type.2C_message.2C_arguments)"><code>emit(target, type, message, arguments)</code></h4>
<p>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.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>target : Object</strong><br />
 Event target object.</p>
<p><strong>type : String</strong><br />
 The type of event.</p>
<p><strong>message : Object|Number|String|Boolean</strong><br />
 First argument that will be passed to listeners.</p>
<p><strong>arguments : Object|Number|String|Boolean</strong><br />
 More arguments that will be passed to listeners.</p>
<h4 class="addon-sdk-api-name" id="off(target.2C_type.2C_listener)"><code>off(target, type, listener)</code></h4>
<p>Removes an event <code>listener</code> for the given event <code>type</code> on the given event <code>target</code>. If no <code>listener</code> is passed removes all listeners of the given <code>type</code>. If <code>type</code> is not passed removes all the listeners of the given event <code>target</code>.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>target : Object</strong><br />
 Event target object.</p>
<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>
<h4 class="addon-sdk-api-name" id="count()"><code>count()</code></h4>
<p>Returns a number of event listeners registered for the given event <code>type</code> on the given event <code>target</code>.</p>
<h5 id="Returns">Returns</h5>
<p><strong>number</strong> : Number of listeners</p>
Revert to this revision