This article needs a technical review. How you can help.
The Notifications.jsm JavaScript code module offers utility routines dealing with showing system notifications in Fennec. It duplicates some of what is available in the nsIAlertService already, but exposes to more advanced Android functionality.
Components.utils.import("resource://gre/modules/Notifications.jsm");
Basic usage
Notifications.jsm exports a Notification object that can be used to show, update, and cancel notifications.
The API allows you to register a handler with the Notifications object at startup. The handler object is called whenever a notification is tapped or cancelled, and passed the original cookies object. Notifications should pass in a handlerKey when they are created to ensure the right handlers are notified when they are clicked.
Example:
const MY_KEY = "this is my key";
// Added in Firefox 33
let myHandler = {
onClick: function(cookie) { },
onCancel: function(cookie) { },
onButtonClick: function(buttonId,cookie) { }
};
Notifications.registerHandler(MY_KEY, myHandler);
var buttons=[{buttonId:"Pause",title:"Pause",icon:"drawable://pause"}];
let id = Notifications.create({
icon: "drawable://stop",
title: "Stop!"
message: "This is a stop message",
handlerKey: MY_KEY,
buttons:buttons
});
...
Notifications.cancel(id);
Notifications.unregisterHandler(MY_KEY, myHandler);
Method overview
| id = create(options) | Create a new notifcation. |
| update(id, options) | Update an existing notification. |
| cancel(id) | Cancel an exsting notification |
| registerHandler(key, handler) | Register a handler to be notified when a notification is clicked/cancelled |
| unregisterHandler(key, handler) | Unregister a handler registered using registerHandler |
Methods
Notifications.create()
Adds a notification with the given options
String guid add(Object options);
Parameters
- options
- A set of options describing the notification
Option Description icon An icon to show in the system tray. MANDATORY title An title to show in the notification tray and in the system bar. MANDATORY message A message to show in the notification tray priority An integer (-2 to +2) to describe the priority of this notification. buttons An array of buttons to show on the notification. Maximum of three. ongoing Boolean describing whether this notification is ongoing. Ongoing notifications can't be swiped away by the user, and use a service to try and hold Fennec open until the ongoing process (for instance a WebRTC session) is done. progress An integer between 0 and 100 (or NaN for indeterminate notification) describing the progress of this notification. cookie A cookie that's passed back to the onClick/onCancel/onButtonClick handlers. In Firefox 33+, the API was adjusted to better handle notifications that are clicked when Fennec is no longer running. For those notifications its better to use only serializable properties. handleKey A key that's used to determine who to notify when the notification is clicked or cancelled.
Returns
- guid
- Returns an id for the notification that was shown. You can hold on to this to hide or update the notification at some later point.
Example
var id = Notifications.create({
title: "My title",
message: "My message",
icon: "drawable://stop",
});
update()
Updates an existing notification
void update(String guid, Object options)
Parameters
- guid
- The guid you were handed when you created this notification
- options
- Same as the options argument that was passed to the create method. Any options you don't specify will be refilled from the original options you passed in when the Notification was created. i.e. You don't need to update every option every time you call update.
Example
Notifications.update(id, {
progress: newProgress
});
cancel()
Remove a notification from the system bar
void cancel(String guid);
Parameters
- guid
- The guid you were handed when you created this notification
Example
Notifications.cancel(id);
unregisterHandler()
Unregisters a handler registered using registerHandler
void unregisterHandler(String key, NotificationHandler handler);
Parameters
- key
- The key this handler registered under.
- handler
- The NotificationHandler to unregister.
registerHandler()
Register a handler to be notified when notifications with a given key are clicked or cancelled
void registerHandler(String key, NotificationHandler handler);
Parameters
- key
- The key this handler would like to register under. Any notifications with this key will call this handler when they're clicked/cancelled.
- handler
- A NotificationHandler that will be called whenver notifications with this key are clicked or cancelled.