B2G/gecko/toolkit/content/PopupNotifications.jsm
/**
   * Adds a new popup notification.
   * @param browser
   *        The <xul:browser> element associated with the notification. Must not
   *        be null.
   * @param id
   *        A unique ID that identifies the type of notification (e.g.
   *        "geolocation"). Only one notification with a given ID can be visible
   *        at a time. If a notification already exists with the given ID, it
   *        will be replaced.
   * @param message
   *        The text to be displayed in the notification.
   * @param anchorID
   *        The ID of the element that should be used as this notification
   *        popup's anchor. May be null, in which case the notification will be
   *        anchored to the iconBox.
   * @param mainAction
   *        A JavaScript object literal describing the notification button's
   *        action. If present, it must have the following properties:
   *          - label (string): the button's label.
   *          - accessKey (string): the button's accessKey.
   *          - callback (function): a callback to be invoked when the button is
   *            pressed.
   *        If null, the notification will not have a button, and
   *        secondaryActions will be ignored.
   * @param secondaryActions
   *        An optional JavaScript array describing the notification's alternate
   *        actions. The array should contain objects with the same properties
   *        as mainAction. These are used to populate the notification button's
   *        dropdown menu.
   * @param options
   *        An options JavaScript object holding additional properties for the
   *        notification. The following properties are currently supported:
   *        persistence: An integer. The notification will not automatically
   *                     dismiss for this many page loads.
   *        timeout:     A time in milliseconds. The notification will not
   *                     automatically dismiss before this time.
   *        persistWhileVisible:
   *                     A boolean. If true, a visible notification will always
   *                     persist across location changes.
   *        dismissed:   Whether the notification should be added as a dismissed
   *                     notification. Dismissed notifications can be activated
   *                     by clicking on their anchorElement.
   *        eventCallback:
   *                     Callback to be invoked when the notification changes
   *                     state. The callback's first argument is a string
   *                     identifying the state change:
   *                     "dismissed": notification has been dismissed by the
   *                                  user (e.g. by clicking away or switching
   *                                  tabs)
   *                     "removed": notification has been removed (due to
   *                                location change or user action)
   *                     "shown": notification has been shown (this can be fired
   *                              multiple times as notifications are dismissed
   *                              and re-shown)
   *        neverShow:   Indicate that no popup should be shown for this
   *                     notification. Useful for just showing the anchor icon.
   *        removeOnDismissal:
   *                     Notifications with this parameter set to true will be
   *                     removed when they would have otherwise been dismissed
   *                     (i.e. any time the popup is closed due to user
   *                     interaction).
   *        popupIconURL:
   *                     A string. URL of the image to be displayed in the popup.
   *                     Normally specified in CSS using list-style-image and the
   *                     .popup-notification-icon[popupid=...] selector.
   * @returns the Notification object corresponding to the added notification.
   */
Adds a new popup notification.
@param browser
The  element associated with the notification. Must not
be null.
@param id
A unique ID that identifies the type of notification . Only one notification with a given ID can be visible
at a time. If a notification already exists with the given ID, it
will be replaced.
@param message
The text to be displayed in the notification.
@param anchorID
The ID of the element that should be used as this notification
popup's anchor. May be null, in which case the notification will be
anchored to the iconBox.
@param mainAction
A JavaScript object literal describing the notification button's
action. If present, it must have the following properties:
- label (string): the button's label.
- accessKey (string): the button's accessKey.
- callback (function): a callback to be invoked when the button is
pressed.
If null, the notification will not have a button, and
secondaryActions will be ignored.
@param secondaryActions
An optional JavaScript array describing the notification's alternate
actions. The array should contain objects with the same properties
as mainAction. These are used to populate the notification button's
dropdown menu.
@param options
An options JavaScript object holding additional properties for the
notification. The following properties are currently supported:
persistence: An integer. The notification will not automatically
dismiss for this many page loads.
timeout:     A time in milliseconds. The notification will not
automatically dismiss before this time.
Adds a new popup notification . @param browser The element associated with the notification . Must not be null . @param id A unique ID that identifies the type of notification . Only one notification with a given ID can be visible at a time . If a notification already exists with the given ID it will be replaced . @param message The text to be displayed in the notification . @param anchorID The ID of the element that should be used as this notification popup ' s anchor . May be null in which case the notification will be anchored to the iconBox . @param mainAction A JavaScript object literal describing the notification button ' s action . If present it must have the following properties : - label ( string ) : the button ' s label . - accessKey ( string ) : the button ' s accessKey . - callback ( function ) : a callback to be invoked when the button is pressed . If null the notification will not have a button and secondaryActions will be ignored . @param secondaryActions An optional JavaScript array describing the notification ' s alternate actions . The array should contain objects with the same properties as mainAction . These are used to populate the notification button ' s dropdown menu . @param options An options JavaScript object holding additional properties for the notification . The following properties are currently supported : persistence : An integer . The notification will not automatically dismiss for this many page loads . timeout : A time in milliseconds . The notification will not automatically dismiss before this time .
function PopupNotifications_show(browser, id, message, anchorID,
                                         mainAction, secondaryActions, options) {
    function isInvalidAction(a) {
      return !a || !(typeof(a.callback) == "function") || !a.label || !a.accessKey;
    }
    if (!browser)
      throw "PopupNotifications_show: invalid browser";
    if (!id)
      throw "PopupNotifications_show: invalid ID";
    if (mainAction && isInvalidAction(mainAction))
      throw "PopupNotifications_show: invalid mainAction";
    if (secondaryActions && secondaryActions.some(isInvalidAction))
      throw "PopupNotifications_show: invalid secondaryActions";
    let notification = new Notification(id, message, anchorID, mainAction,
                                        secondaryActions, browser, this, options);
    if (options && options.dismissed)
      notification.dismissed = true;
    let existingNotification = this.getNotification(id, browser);
    if (existingNotification)
      this._remove(existingNotification);
    let notifications = this._getNotificationsForBrowser(browser);
    notifications.push(notification);
    let fm = Cc["@mozilla.org/focus-manager;1"].getService(Ci.nsIFocusManager);
    if (browser == this.tabbrowser.selectedBrowser && fm.activeWindow == this.window) {
      this._update(notification.anchorElement);
    } else {
      this._notify("backgroundShow");
    }
    return notification;
  }
function PopupNotifications_show ( browser , id , message , anchorID , mainAction , secondaryActions , options ) { function isInvalidAction ( a ) { return ! a || ! ( typeof ( a . callback ) == "function" ) || ! a . label || ! a . accessKey ; } if ( ! browser ) throw "PopupNotifications_show: invalid browser" ; if ( ! id ) throw "PopupNotifications_show: invalid ID" ; if ( mainAction && isInvalidAction ( mainAction ) ) throw "PopupNotifications_show: invalid mainAction" ; if ( secondaryActions && secondaryActions . some ( isInvalidAction ) ) throw "PopupNotifications_show: invalid secondaryActions" ; let notification = new Notification ( id , message , anchorID , mainAction , secondaryActions , browser , this , options ) ; if ( options && options . dismissed ) notification . dismissed = true ; let existingNotification = this . getNotification ( id , browser ) ; if ( existingNotification ) this . _remove ( existingNotification ) ; let notifications = this . _getNotificationsForBrowser ( browser ) ; notifications . push ( notification ) ; let fm = Cc [ "@mozilla.org/focus-manager;1" ] . getService ( Ci . nsIFocusManager ) ; if ( browser == this . tabbrowser . selectedBrowser && fm . activeWindow == this . window ) { this . _update ( notification . anchorElement ) ; } else { this . _notify ( "backgroundShow" ) ; } return notification ; }
Adds a new popup notification.
Adds a new popup notification .
// show panel now // Otherwise, update() will display the notification the next time the // relevant tab/window is selected. // Notify observers that we're not showing the popup (useful for testing)