mozilla
Your Search Results

    Notifications.jsm

    Note: Notifications.jsm is still under development. The API may change. Use with care!

    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 was changed significantly in Firefox 33 to better handle situations where a Firefox is killed between the time a Notification was created and when it was cancelled. The new 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,
      // pre Firefox 33 you could add listeners here
      onClick: function() { },
      onCancel: function() { },
    });
    
    ...
    
    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) Firefox 33 Register a handler to be notified when a notification is clicked/cancelled
    unregisterHandler(key, handler) Firefox 33 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.
    onCancel Obsolete since Gecko 33 A function that's called when the notification is dismissed by swiping it away or tapping the close all button.
    onClick Obsolete since Gecko 33 A function that's called when the notification is clicked. The notification won't necessarily be dismissed when this is called.
    cookie A cookie that's passed back to the onClick/onCancel/onButtonClick handlers. Prior to Firefox 33, this cookie was stored in Gecko and could be anything. 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 Firefox 33 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()

    Firefox 33 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()

    Firefox 33 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.
     

    Document Tags and Contributors

    Contributors to this page: evilpie, TonyHEssex, leibovic, wesj, wbamberg, lbernd
    Last updated by: lbernd,
    Hide Sidebar