Revision 583739 of nsIAlertsService

  • Revision slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIAlertsService
  • Revision title: nsIAlertsService
  • Revision id: 583739
  • Created:
  • Creator: trevorh
  • Is current revision? No
  • Comment Clickable notifications are no longer styled as hyperlinks, see bug 1001204

Revision Content

{{ IFSummary("toolkit/components/alerts/nsIAlertsService.idl", "nsISupports", "Scriptable", "22", "This interface can be used to notify the user of something that does not require an immediate reaction. For example, it can be used to notify the user that their downloads are complete or that they have new mail.","1.7") }}

A notification displayed by the alerts serviceBy default a message is displayed in a small window that slides up from the bottom of the screen, holds there for a few seconds, then slides down. The specific appearance varies from platform to platform.

{{ NoteStart() }}Prior Firefox 22, the alerts service was only supported on Windows in {{ gecko("1.7") }}, had no effect on Mac OS X in {{ gecko("1.8") }}, but was fully supported in Mac OS X in {{ gecko("1.9") }}.{{ NoteEnd() }}

{{ NoteStart() }} Since {{ gecko("22") }}, the notifications are provided by Firefox and have become platform-independent.{{ NoteEnd() }}

Implemented by: @mozilla.org/alerts-service;1 as a service:

var alertsService = Components.classes["@mozilla.org/alerts-service;1"]
                    .getService(Components.interfaces.nsIAlertsService);

Method overview

void showAlertNotification(in AString imageUrl, in AString title, in AString text, [optional] in boolean textClickable, [optional] in AString cookie, [optional] in nsIObserver alertListener, [optional] in AString name, [optional] in AString dir, [optional] in AString lang);

Methods

showAlertNotification()

Displays a notification window.

{{ NoteStart() }}If you are calling this function from JavaScript, you should wrap it in a try/catch because it can fail on Mac OS X prior to Firefox 22.{{ NoteEnd() }}

void showAlertNotification(
  in AString imageUrl,
  in AString title,
  in AString text,
  in boolean textClickable, {{ optional_inline() }}
  in AString cookie, {{ optional_inline() }}
  in nsIObserver alertListener, {{ optional_inline() }}
  in AString name, {{ optional_inline() }} {{ gecko_minversion_inline("1.9") }}
  in AString dir, {{ optional_inline() }} {{ gecko_minversion_inline("22") }}
  in AString lang {{ optional_inline() }} {{ gecko_minversion_inline("22") }}
);
Parameters
imageUrl
A URL identifying the image to display in the notification alert.
title
The title for the alert.
text
The text to display in the alert, explaining the alert condition. The text must not be too long, otherwise it might be truncated to a platform-specific length. If the text is too long, try to use line returns in the text to have it split and displayed over multiple lines.
textClickable {{ optional_inline() }}
If true, if the user clicks on it, the listener is notified; when hovered the notification background becomes lighter and the cursor turns to a pointer. Prior to Gecko 32 the
text was made to look like a link.
cookie {{ optional_inline() }}
A blind cookie the alert passes back to the consumer during alert listener callbacks.
alertListener {{ optional_inline() }}
An object to receive callbacks from the alert; may be null if you don't care about callbacks. It must implement an observe() method that accepts three parameters:
  • subject: always null.
  • topic: "alertfinished" when the alert disappears, "alertclickcallback" if the user clicks the text or "alertshow" (since Gecko 22) when the alert is shown.
  • data: The value of the cookie parameter passed into the showAlertNotification method.
name {{ optional_inline() }} {{ gecko_minversion_inline("1.9") }}
A name for the notification; this is not displayed in the alert. However, certain notification systems (such as Growl on Mac OS X) allow the user to disable alerts by name. This name is used in that configuration panel. On Android the name is hashed and used as a notification ID.
dir {{ optional_inline() }} {{ gecko_minversion_inline("22") }}
Bidi override for the title. Valid values are "auto", "ltr" or "rtl". Only available on supported platforms.
lang {{ optional_inline() }} {{ gecko_minversion_inline("22") }}
Language of title and text of the alert. Only available on supported platforms.
Exceptions thrown
NS_ERROR_NOT_AVAILABLE
Unable to display the notification; this may happen, for example, on Mac OS X if Growl is not installed.

Example

Simple usage

The following code was used to display the above notification.

var alertsService = Components.classes["@mozilla.org/alerts-service;1"].
                      getService(Components.interfaces.nsIAlertsService);
try {
  alertsService.showAlertNotification("chrome://mozapps/skin/downloads/downloadIcon.png", 
                                      "Alert title", "Alert text goes here.", 
                                      false, "", null, "");
} catch (e) {
  // This can fail on Mac OS X
}

Listening for callbacks

You can be notified when the notification window disappears or the user clicks on the message by passing an object implementing {{ interface("nsIObserver") }} as the alertListener parameter:

var listener = {
  observe: function(subject, topic, data) {
    alert("subject=" + subject + ", topic=" + topic + ", data=" + data);
  }
}
var alertsService = Components.classes["@mozilla.org/alerts-service;1"].
                              getService(Components.interfaces.nsIAlertsService);
try {
  alertsService.showAlertNotification("",  "Alerts service test", "Click me", 
                                      true, "cookie", listener, "");
} catch (e) {
  // This can fail on Mac OS X
}

See also

Revision Source

<p>{{ IFSummary("toolkit/components/alerts/nsIAlertsService.idl", "nsISupports", "Scriptable", "22", "This interface can be used to notify the user of something that does not require an immediate reaction. For example, it can be used to notify the user that their downloads are complete or that they have new mail.","1.7") }}</p>
<p><img align="right" alt="A notification displayed by the alerts service" class="internal" src="/@api/deki/files/31/=AlertsServiceNotification.png" />By default a message is displayed in a small window that slides up from the bottom of the screen, holds there for a few seconds, then slides down. The specific appearance varies from platform to platform.</p>
<p>{{ NoteStart() }}Prior Firefox 22, the alerts service was only supported on Windows in {{ gecko("1.7") }}, had no effect on Mac OS X in {{ gecko("1.8") }}, but was fully supported in Mac OS X in {{ gecko("1.9") }}.{{ NoteEnd() }}</p>
<p>{{ NoteStart() }} Since {{ gecko("22") }}, the notifications are provided by Firefox and have become platform-independent.{{ NoteEnd() }}</p>
<p>Implemented by: <code>@mozilla.org/alerts-service;1</code> as a service:</p>
<pre class="eval">
var alertsService = Components.classes["@mozilla.org/alerts-service;1"]
                    .getService(Components.interfaces.nsIAlertsService);
</pre>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<table class="standard-table">
 <tbody>
  <tr>
   <td><code>void <a href="#showAlertNotification()">showAlertNotification</a>(in AString imageUrl, in AString title, in AString text, [optional] in boolean textClickable, [optional] in AString cookie, [optional] in nsIObserver alertListener, [optional] in AString name, [optional] in AString dir, [optional] in AString lang);</code></td>
  </tr>
 </tbody>
</table>
<h2 id="Methods" name="Methods">Methods</h2>
<h3 id="showAlertNotification()" name="showAlertNotification()">showAlertNotification()</h3>
<p>Displays a notification window.</p>
<p>{{ NoteStart() }}If you are calling this function from JavaScript, you should wrap it in a try/catch because it can fail on Mac OS X prior to Firefox 22.{{ NoteEnd() }}</p>
<pre class="eval">
void showAlertNotification(
  in AString imageUrl,
  in AString title,
  in AString text,
  in boolean textClickable, {{ optional_inline() }}
  in AString cookie, {{ optional_inline() }}
  in nsIObserver alertListener, {{ optional_inline() }}
  in AString name, {{ optional_inline() }} {{ gecko_minversion_inline("1.9") }}
  in AString dir, {{ optional_inline() }} {{ gecko_minversion_inline("22") }}
  in AString lang {{ optional_inline() }} {{ gecko_minversion_inline("22") }}
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
 <dt>
  <code>imageUrl</code></dt>
 <dd>
  A URL identifying the image to display in the notification alert.</dd>
 <dt>
  <code>title</code></dt>
 <dd>
  The title for the alert.</dd>
 <dt>
  <code>text</code></dt>
 <dd>
  The text to display in the alert, explaining the alert condition. The text must not be too long, otherwise it might be truncated to a platform-specific length. If the text is too long, try to use line returns in the text to have it split and displayed over multiple lines.</dd>
 <dt>
  <code>textClickable</code> {{ optional_inline() }}</dt>
 <dd>
  If <code>true</code>, if the user clicks on it, the listener is notified; when hovered the notification background becomes lighter and the cursor turns to a pointer. Prior to Gecko 32 the<br />
  text was made to look like a link.</dd>
 <dt>
  <code>cookie</code> {{ optional_inline() }}</dt>
 <dd>
  A blind cookie the alert passes back to the consumer during alert listener callbacks.</dd>
 <dt>
  <code>alertListener</code> {{ optional_inline() }}</dt>
 <dd>
  An object to receive callbacks from the alert; may be null if you don't care about callbacks. It must implement an <code>observe()</code> method that accepts three parameters:
  <ul>
   <li><code><strong>subject</strong></code>: always null.</li>
   <li><code><strong>topic</strong></code>: "alertfinished" when the alert disappears, "alertclickcallback" if the user clicks the text or "alertshow" (since Gecko 22) when the alert is shown.</li>
   <li><code><strong>data</strong></code>: The value of the <code>cookie</code> parameter passed into the <code>showAlertNotification</code> method.</li>
  </ul>
 </dd>
 <dt>
  <code>name</code> {{ optional_inline() }} {{ gecko_minversion_inline("1.9") }}</dt>
 <dd>
  A name for the notification; this is not displayed in the alert. However, certain notification systems (such as Growl on Mac OS X) allow the user to disable alerts by name. This name is used in that configuration panel. On Android the name is hashed and used as a notification ID.</dd>
 <dt>
  <code>dir</code> {{ optional_inline() }} {{ gecko_minversion_inline("22") }}</dt>
 <dd>
  Bidi override for the title. Valid values are "auto", "ltr" or "rtl". Only available on supported platforms.</dd>
 <dt>
  <code>lang</code> {{ optional_inline() }} {{ gecko_minversion_inline("22") }}</dt>
 <dd>
  Language of title and text of the alert. Only available on supported platforms.</dd>
</dl>
<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6>
<dl>
 <dt>
  <code>NS_ERROR_NOT_AVAILABLE</code></dt>
 <dd>
  Unable to display the notification; this may happen, for example, on Mac OS X if Growl is not installed.</dd>
</dl>
<h3 id="Example" name="Example">Example</h3>
<h4 id="Simple_usage" name="Simple_usage">Simple usage</h4>
<p>The following code was used to display the above notification.</p>
<pre class="brush: js">
var alertsService = Components.classes["@mozilla.org/alerts-service;1"].
                      getService(Components.interfaces.nsIAlertsService);
try {
  alertsService.showAlertNotification("<a class="external" href="chrome://mozapps/skin/downloads/downloadIcon.png" rel="freelink">chrome://mozapps/skin/downloads/downloadIcon.png</a>", 
                                      "Alert title", "Alert text goes here.", 
                                      false, "", null, "");
} catch (e) {
  // This can fail on Mac OS X
}
</pre>
<h4 id="Listening_for_callbacks" name="Listening_for_callbacks">Listening for callbacks</h4>
<p>You can be notified when the notification window disappears or the user clicks on the message by passing an object implementing {{ interface("nsIObserver") }} as the <code>alertListener</code> parameter:</p>
<pre class="brush: js">
var listener = {
  observe: function(subject, topic, data) {
    alert("subject=" + subject + ", topic=" + topic + ", data=" + data);
  }
}
var alertsService = Components.classes["@mozilla.org/alerts-service;1"].
                              getService(Components.interfaces.nsIAlertsService);
try {
  alertsService.showAlertNotification("",  "Alerts service test", "Click me", 
                                      true, "cookie", listener, "");
} catch (e) {
  // This can fail on Mac OS X
}
</pre>
<h2 id="See_also" name="See_also">See also</h2>
<ul>
 <li><a href="/en/Code_snippets/Alerts_and_Notifications" title="en/Code snippets/Alerts and Notifications">Alerts and Notifications</a></li>
 <li><a href="https://bugzilla.mozilla.org/show_bug.cgi?id=782211">Bug 782211 - Implement notification API spec</a></li>
</ul>
Revert to this revision