mozilla

Revision 421403 of nsIAlertsService

  • Revision slug: XPCOM_Interface_Reference/nsIAlertsService
  • Revision title: nsIAlertsService
  • Revision id: 421403
  • Created:
  • Creator: MKaply
  • Is current revision? No
  • Comment Add notes about using a try catch because of failures on Mac OS X

Revision Content

{{ IFSummary("toolkit/components/alerts/public/nsIAlertsService.idl", "nsISupports", "Scriptable", "1.9", "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() }}The alerts service is only supported on Windows in {{ gecko("1.7") }}, has no effect on Mac OS X in {{ gecko("1.8") }}, but is fully supported in Mac OS X in {{ gecko("1.9") }}.{{ 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);

Methods

showAlertNotification()

Displays a notification window. Its specific appearance varies from platform to platform. For example, on Windows it is a sliding window that slides out of the taskbar, pauses for a few seconds, then glides back off the screen. On Mac OS X ({{ gecko("1.9") }} and later), the popular Growl notification system is used to display notifications in a customizable fashion.

{{ 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.{{ 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") }}
);
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, the text is made to look like a link; if the user clicks on it, the listener is notified.
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 or "alertclickcallback" if the user clicks the text.
  • 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.
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/public/nsIAlertsService.idl", "nsISupports", "Scriptable", "1.9", "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() }}The alerts service is only supported on Windows in {{ gecko("1.7") }}, has no effect on Mac OS X in {{ gecko("1.8") }}, but is fully supported in Mac OS X in {{ gecko("1.9") }}.{{ 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);</code></td>
    </tr>
  </tbody>
</table>
<h2 id="Methods" name="Methods">Methods</h2>
<h3 id="showAlertNotification()" name="showAlertNotification()">showAlertNotification()</h3>
<p>Displays a notification window. Its specific appearance varies from platform to platform. For example, on Windows it is a sliding window that slides out of the taskbar, pauses for a few seconds, then glides back off the screen. On Mac OS X ({{ gecko("1.9") }} and later), the popular <a class="external" href="http://growl.info/">Growl</a> notification system is used to display notifications in a customizable fashion.</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.{{ 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") }}
);
</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>, the text is made to look like a link; if the user clicks on it, the listener is notified.</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 or "alertclickcallback" if the user clicks the text.</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>
</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>
</ul>
Revert to this revision