mozilla

Revision 53301 of nsIObserver

  • Revision slug: XPCOM_Interface_Reference/nsIObserver
  • Revision title: nsIObserver
  • Revision id: 53301
  • Created:
  • Creator: Oeekker
  • Is current revision? No
  • Comment /* Example Code */

Revision Content

{{ Xpcomapi() }}

Summary

nsIObserver is implemented by an object that wishes to observe notifications. These notifications are often, though not always, broadcast via the nsIObserverService.

{{ InterfaceStatus("nsIObserver", "xpcom/ds/nsIObserver.idl", "FROZEN", "Mozilla 0.9.6", "yes") }}

Interface Code

[scriptable, uuid(DB242E01-E4D9-11d2-9DDE-000064657374)]
interface nsIObserver : nsISupports {
    void observe( in nsISupports aSubject,
                  in string      aTopic,
                  in wstring     aData );
};

Methods

observe

    void observe( in nsISupports aSubject,
                  in string      aTopic,
                  in wstring     aData );

observe will be called when there is a notification for the topic that the observer has been registered for.

In general, aSubject reflects the object whose change or action is being observed, aTopic indicates the specific change or action, and aData is an optional parameter or other auxiliary data further describing the change or action.

The specific values and meanings of the parameters provided varies widely, though, according to where the observer was registered, and what topic is being observed.

A single nsIObserver implementation can observe multiple types of notification, and is responsible for dispatching its own behaviour on the basis of the parameters for a given callback. In general, aTopic is the primary criterion for such dispatch; nsIObserver implementations should take care that they can handle being called with unknown values for aTopic.

While some observer-registration systems may make this safe in specific contexts, it is generally recommended that observe implementations not add or remove observers while they are being notified.

Related Interfaces

nsIObserverService

Example Code

The following code is an implementation of nsIObserver that is registered to receive notifications for the "myTopicID" topic. See Global Notifications at XULPlanet for a list of built-in topics possible.

Observing preferences works slightly differently. See Code snippets:Preferences - Using preference observers for an example.

function myObserver()
{
  this.register();
}
myObserver.prototype = {
  observe: function(subject, topic, data) {
     // Do your stuff here.
  },
  register: function() {
    var observerService = Components.classes["@mozilla.org/observer-service;1"]
                          .getService(Components.interfaces.nsIObserverService);
    observerService.addObserver(this, "myTopicID", false);
  },
  unregister: function() {
    var observerService = Components.classes["@mozilla.org/observer-service;1"]
                            .getService(Components.interfaces.nsIObserverService);
    observerService.removeObserver(this, "myTopicID");
  }
}

Instantiation - this should be fired once you're ready to start observing (ex: a window's load event).

observer = new myObserver();

Destruction - this should be fired once you're done observing (ex: a window's unload event). Failure to do so may result in memory leaks.

observer.unregister();
{{ languages( { "pl": "pl/NsIObserver" } ) }}

Revision Source

<p>
{{ Xpcomapi() }}
</p>
<h3 name="Summary"> Summary </h3>
<p><code>nsIObserver</code> is implemented by an object that wishes to observe notifications. These notifications are often, though not always, broadcast via the <a href="en/NsIObserverService">nsIObserverService</a>.
</p><p>{{ InterfaceStatus("nsIObserver", "xpcom/ds/nsIObserver.idl", "FROZEN", "Mozilla 0.9.6", "yes") }}
</p>
<h3 name="Interface_Code"> Interface Code </h3>
<pre>[scriptable, uuid(DB242E01-E4D9-11d2-9DDE-000064657374)]
interface nsIObserver : nsISupports {
    void observe( in nsISupports aSubject,
                  in string      aTopic,
                  in wstring     aData );
};
</pre>
<h3 name="Methods"> Methods </h3>
<h4 name="observe"> observe </h4>
<pre>    void observe( in nsISupports aSubject,
                  in string      aTopic,
                  in wstring     aData );
</pre>
<p><code>observe</code> will be called when there is a notification for the topic that the observer has been registered for.
</p><p>In general, <code>aSubject</code> reflects the object whose change or action is being observed, <code>aTopic</code> indicates the specific change or action, and <code>aData</code> is an optional parameter or other auxiliary data further describing the change or action.
</p><p>The specific values and meanings of the parameters provided varies widely, though, according to where the observer was registered, and what topic is being observed. </p><p>A single <code>nsIObserver</code> implementation can observe multiple types of notification, and is responsible for dispatching its own behaviour on the basis of the parameters for a given callback. In general, <code>aTopic</code> is the primary criterion for such dispatch; <code>nsIObserver</code> implementations should take care that they can handle being called with unknown values for <code>aTopic</code>.
</p><p>While some observer-registration systems may make this safe in specific contexts, it is generally recommended that <code>observe</code> implementations not add or remove observers while they are being notified.
</p>
<h3 name="Related_Interfaces"> Related Interfaces </h3>
<p><a href="en/NsIObserverService">nsIObserverService</a>
</p>
<h3 name="Example_Code"> Example Code </h3>
<p>The following code is an implementation of <code>nsIObserver</code> that is registered to receive notifications for the "myTopicID" topic. See <a class="external" href="http://xulplanet.com/tutorials/mozsdk/observerserv.php">Global Notifications at XULPlanet</a> for a list of built-in topics possible.
</p><p>Observing preferences works slightly differently. See <a href="en/Code_snippets/Preferences#Using_preference_observers"> Code snippets:Preferences - Using preference observers</a> for an example.
</p>
<pre class="eval">function myObserver()
{
  this.register();
}
myObserver.prototype = {
  observe: function(subject, topic, data) {
     // Do your stuff here.
  },
  register: function() {
    var observerService = Components.classes["@mozilla.org/observer-service;1"]
                          .getService(Components.interfaces.nsIObserverService);
    observerService.addObserver(this, "myTopicID", false);
  },
  unregister: function() {
    var observerService = Components.classes["@mozilla.org/observer-service;1"]
                            .getService(Components.interfaces.nsIObserverService);
    observerService.removeObserver(this, "myTopicID");
  }
}
</pre>
<p>Instantiation - this should be fired once you're ready to start observing (ex: a window's load event).
</p>
<pre class="eval">observer = new myObserver();
</pre>
<p>Destruction - this should be fired once you're done observing (ex: a window's unload event). Failure to do so may result in memory leaks.
</p>
<pre class="eval">observer.unregister();
</pre>{{ languages( { "pl": "pl/NsIObserver" } ) }}
Revert to this revision