{{ 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") }}
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.
{{ 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 thecookieparameter passed into theshowAlertNotificationmethod.
-
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
}