The PopupNotifications.jsm
JavaScript code module provides a popup notification box service. This service is used, for example, to display Geolocation related notifications.
To use this, you first need to import the code module into your JavaScript scope:
Components.utils.import("resource://gre/modules/PopupNotifications.jsm");
Once you've imported the module, you can then use the PopupNotifications
object it exports; this object provides methods for creating and displaying popup notification panels.
void locationChange(); |
Notification getNotification(id, browser); |
void remove(notification); |
Notification show(browser, id, message, anchorID, mainAction, secondaryActions, options); |
Attribute | Type | Description |
isPanelOpen |
Boolean |
Returns true if the notification panel is currently visible, false if it is not. |
The consumer can call this method to let the popup notification module know that the current browser's location has changed. This lets the notification service update the active notifications as appropriate.
void locationChange();
None.
Retrieve a Notification object associated with the browser/ID pair.
Notification
getNotification(
string id
XULElement browser
);
id
Notification
ID to search for.browser
<xul:browser>
element whose notifications should be searched. If null
, the currently selected <xul:browser>
's notifications will be searched.The corresponding Notification
object, or null
if no such notification exists.
Removes the specified notification.
void remove( Notification notification );
notification
Notification
object representing the notification to remove.Adds a new popup notification, displaying it to the user.
Notification show( browser, id, message, anchorID, mainAction, secondaryActions, options );
browser
<xul:browser>
element with which the notification is associated. This must not be null
; you can, however, simply specify gBrowser.selectedBrowser
to associate it with the current tab.id
message
anchorID
null
, the notification will be anchored to the PopupNotification object's icon box. This anchorID must point to an element contained inside the PopupNotification object's icon box (for Firefox windows, the global PopupNotifications object uses the notification-popup-box
element).mainAction
secondaryActions
options
Returns the Notification
object corresponding to the added notification.
Notification action objects describe the user interface for actions associated with the notification. The main action is used to describe the button presented in the notification panel, while secondary actions are displayed in the drop-down menu associated with the button.
A notification action object must contain the following properties:
label
accessKey
callback
The notification options object lets you further customize the notification panel. Any combination of the following properties may be provided:
persistence
timeout
Date.now()
plus an offset indicating the amount of time the notification should be kept open (for example, Date.now() + 30000
for 30 seconds).persistWhileVisible
true
, the notification will remain visible even if the browser navigates to a different location.dismissed
eventCallback
neverShow
removeOnDismissal
true
will be removed when they would have otherwise been dismissed (that is, any time the popup is closed due to user interaction).popupIconURL
list-style-image
and the .popup-notification-icon[popupid=...]
selector.If you specify an event callback using the options
parameter when calling show()
, the callback function gets invoked when the state of the notification changes. The first parameter to the callback is a string identifying the state change, and may be one of the following:
Each notification is represented by a Notification
object. This object contains all the data necessary to present and manage the notification, and has one method. The anchorElement
property returns the notification's anchor element. The remove()
method removes the notification.