Revision 764483 of system/events

Revision slug: Mozilla/Add-ons/SDK/Low-Level_APIs/system_events
Revision title: system/events
Revision id: 764483
Created: Feb 28, 2015, 5:12:12 AM
Creator: grbradt
Is current revision? No
Comment typo

Revision Content

Unstable

API for working with the application observer service.

Usage

The system/events module provides core (low level) API for working with the application observer service, also known as nsIObserverService. You can find a list of events dispatched by firefox codebase here.

var events = require("sdk/system/events");
var { Ci } = require("chrome");

function listener(event) {
  var channel = event.subject.QueryInterface(Ci.nsIHttpChannel);
  channel.setRequestHeader("User-Agent", "MyBrowser/1.0", false);
}

events.on("http-on-modify-request", listener);

Globals

Functions

`emit(type, event)`

Send an event to observer service

Parameters

type : string
The event type.

event : object
An optional object object with data and subject attributes. data refers to a string that you would like to pass through this event. subject should refer to the actual actor/subject of this event (ie: the object emitting the event).

`on(type, listener, strong)`

Listen to events of a given type

Parameters

type : string
The event type name to watch.

listener : function
Function that will be called when an event is fired, with a single event object as argument. This object has three attributes:

type: the event type name
subject: the event subject object
data: the event data string

strong : boolean
Default is false, a weak reference, which means it can be garbage collected at any time if there are no other references to it. Determines if we should keep a strong or weak reference to the listener method.

`once(type, listener, strong)`

Listen only once to a particular event type

Parameters

type : string
The event type name to watch.

listener : function
Function that will be called when an event is fired.

`off(type, listener)`

Stop listening for an event

Parameters

type : string
The event type name to unsubscribe to.

listener : function
The function we registered to listen for events.

Revision Source

<div class="note">
<p>Unstable</p>
</div>

<p><span class="seoSummary">API for working with the application observer service.</span></p>

<h2 id="Usage">Usage</h2>

<p>The system/events module provides core (low level) API for working with the application observer service, also known as <a href="https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIObserverService">nsIObserverService</a>. You can find a list of events dispatched by firefox codebase <a href="https://developer.mozilla.org/en-US/docs/Observer_Notifications">here</a>.</p>

<pre class="brush: js">
var events = require("sdk/system/events");
var { Ci } = require("chrome");

function listener(event) {
  var channel = event.subject.QueryInterface(Ci.nsIHttpChannel);
&nbsp; channel.setRequestHeader("User-Agent", "MyBrowser/1.0", false);
}

events.on("http-on-modify-request", listener);
</pre>

<h2 id="Globals">Globals</h2>

<h3 id="Functions">Functions</h3>

<h4 class="addon-sdk-api-name" id="emit(type.2C_event)"><code>emit(type, event)</code></h4>

<p>Send an event to observer service</p>

<h5 id="Parameters">Parameters</h5>

<p><strong>type : string</strong><br />
 The event type.</p>

<p><strong>event : object</strong><br />
 An optional object object with <code>data</code> and <code>subject</code> attributes. <code>data</code> refers to a string that you would like to pass through this event. <code>subject</code> should refer to the actual actor/subject of this event (ie: the object emitting the event).</p>

<h4 class="addon-sdk-api-name" id="on(type.2C_listener.2C_strong)"><code>on(type, listener, strong)</code></h4>

<p>Listen to events of a given type</p>

<h5 id="Parameters_2">Parameters</h5>

<p><strong>type : string</strong><br />
 The event type name to watch.</p>

<p><strong>listener : function</strong><br />
 Function that will be called when an event is fired, with a single <code>event</code> object as argument. This object has three attributes:</p>

<ul>
 <li>type: the event type name</li>
 <li>subject: the event subject object</li>
 <li>data: the event data string</li>
</ul>

<p><strong>strong : boolean</strong><br />
 Default is <code>false</code>, a weak reference, which means it can be garbage collected at any time if there are no other references to it. Determines if we should keep a strong or weak reference to the listener method.</p>

<h4 class="addon-sdk-api-name" id="once(type.2C_listener.2C_strong)"><code>once(type, listener, strong)</code></h4>

<p>Listen only once to a particular event type</p>

<h5 id="Parameters_3">Parameters</h5>

<p><strong>type : string</strong><br />
 The event type name to watch.</p>

<p><strong>listener : function</strong><br />
 Function that will be called when an event is fired.</p>

<p><strong>strong : boolean</strong><br />
 Default is <code>false</code>, a weak reference, which means it can be garbage collected at any time if there are no other references to it. Determines if we should keep a strong or weak reference to the listener method.</p>

<h4 class="addon-sdk-api-name" id="off(type.2C_listener)"><code>off(type, listener)</code></h4>

<p>Stop listening for an event</p>

<h5 id="Parameters_4">Parameters</h5>

<p><strong>type : string</strong><br />
 The event type name to unsubscribe to.</p>

<p><strong>listener : function</strong><br />
 The function we registered to listen for events.</p>

Revert to this revision