nsIAlertsService

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.0
28
Introduced
Gecko 1.7
Inherits from: nsISupports Last changed in Gecko 22 (Firefox 22 / Thunderbird 22 / SeaMonkey 2.19)

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.

Note: 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.

Note:  Since Gecko 22, the notifications are provided by Firefox and have become platform-independent.

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.

Note: 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 Firefox 22.

void showAlertNotification(
  in AString imageUrl,
  in AString title,
  in AString text,
  in boolean textClickable, Optional
  in AString cookie, Optional
  in nsIObserver alertListener, Optional
  in AString name, Optional 
  in AString dir, Optional Requires Gecko 22
  in AString lang Optional Requires Gecko 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
If true, the text is made to look like a link; if the user clicks on it, the listener is notified.
cookie Optional
A blind cookie the alert passes back to the consumer during alert listener callbacks.
alertListener Optional
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
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 Requires Gecko 22
Bidi override for the title. Valid values are "auto", "ltr" or "rtl". Only available on supported platforms.
lang Optional Requires Gecko 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 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

Attachments

File Size Date Attached by
se-resize.gif
97 bytes 2009-04-21 16:03:53 Jürgen Jeka
AlertsServiceNotification.png
6353 bytes 2006-01-09 01:43:22 Nickolay

Document Tags and Contributors

Last updated by: Sheppy,