PopupNotifications.jsm

  • Revision slug: JavaScript_code_modules/PopupNotifications.jsm
  • Revision title: PopupNotifications.jsm
  • Revision id: 54976
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment even more content; 139 words added

Revision Content

{{ gecko_minversion_header("2.0") }}

The PopupNotifications.jsm JavaScript code module provides a popup notification box service. This service is used, for example, to display Geolocation related notifications.

popupnotification.png

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.

Method overview

boolean isPanelOpen();
locationChange();
remove(notification);
Notification show(browser, id, message, anchorID, mainAction, secondaryActions, options);

Methods

isPanelOpen()

Reports whether or not the notification panel is currently visible.

boolean isPanelOpen();
Parameters

None.

Return value

true if the notification panel is currently visible; otherwise false.

locationChange()

The consumer can cell 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.

Note: You shouldn't need to call this; it's done automatically.
boolean locationChange();
Parameters

None.

Return value

true if the notification persisted across the change; otherwise false.

remove()

Removes the specified notification.

remove(
  Notification notification
);
Parameters
notification
The Notification object representing the notification to remove.

show()

Adds a new popup notification, displaying it to the user.

Notification show(
  browser,
  id,
  message,
  anchorID,
  mainAction,
  secondaryActions,
  options
); 
Parameters
browser
The XUL {{ XULElem("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
A unique ID string for the type of notification being displayed. For example, Geolocation related notifications have the ID "geolocation". Only one notification for each ID can be visible at a time; if one with the specified ID already exists, it will be replaced with the newer notification.
message
A string to display in the notification panel.
anchorID
The ID of the element that should serve as the anchor for the notification popup (that is, the element the arrow on the popup should point to). If you specify null, the notification will be anchored to the icon box at the start of the URL bar.
mainAction
A JavaScript object literal containing fields that define the button to draw in the notification panel. See Notification actions below for details.
secondaryActions
An array of notification action objects; these are used to populate the drop-down menu on the notification panel's button.
options
A JavaScript object containing optional properties for the notification. See Notification options below for details.
Return value

Returns the Notification object corresponding to the added notification.

Notification actions

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
A text label describing the action.
accessKey
A string indicating the keystroke that will trigger the action.
callback
A JavaScript function to be invoked when the action is selected by the user.

Notification options

The notification options object lets you further customize the notification panel. Any combination of the following properties may be provided:

persistence
An integer value indicating the number of page loads for which the notification will persist; once this many page loads have occurred, the notification may dismiss automatically.
timeout
A minimum number of milliseconds the notification will be displayed; it will not automatically dismiss before this amount of time has elapsed. The user may manually dismiss the notification, however.
persistWhileVisible
A Boolean value indicating whether or not the notification should persist across location changes. If true, the notification will remain visible even if the browser navigates to a different location.
dismissed
A Boolean value indicating whether or not the notification should be added as a dismissed notification. Dismissed notifications can be activated by clicking on their anchor. This lets you create a notification that will appear when the user clicks the anchor.
eventCallback
A JavaScript function to be invoked when the notification changes state. The callback's first parameter is a string identifying the state change that occurred. See Notification events below.
neverShow
A Boolean value that, if true, prevents the popup from ever being displayed. This can be used to simply display the anchor icon as a notification.

Notification events

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:

"dismissed"
The notification has been dismissed by the user (for example, by clicking away or by switching tabs). This is different from "removed", in that the notification can be redisplayed.
"removed"
The notification has been removed, either by the user taking action on the notification or by the browser being navigated to a new location.
"shown"
The notification has become visible. This can be fired multiple times as notifications are dismissed and redisplayed.

Revision Source

<p>{{ gecko_minversion_header("2.0") }}</p>
<p>The <code>PopupNotifications.jsm</code> JavaScript code module provides a popup notification box service. This service is used, for example, to display Geolocation related notifications.</p>
<p><img alt="popupnotification.png" class="internal default" src="/@api/deki/files/4905/=popupnotification.png"></p>
<p>To use this, you first need to import the code module into your JavaScript scope:</p>
<pre>Components.utils.import("resource://gre/modules/PopupNotifications.jsm");
</pre>
<p>Once you've imported the module, you can then use the <code>PopupNotifications</code> object it exports; this object provides methods for creating and displaying popup notification panels.</p>
<h2>Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>boolean <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#isPanelOpen()" title="en/JavaScript code modules/PopupNotifications.jsm#isPanelOpen()">isPanelOpen</a>();</code></td> </tr> <tr> <td><code><a href="/en/JavaScript_code_modules/PopupNotifications.jsm#locationChange()" title="en/JavaScript code modules/PopupNotifications.jsm#locationChange()">locationChange</a>();</code></td> </tr> <tr> <td><code><a href="/en/JavaScript_code_modules/PopupNotifications.jsm#remove()" title="en/JavaScript code modules/PopupNotifications.jsm#remove()">remove</a>(notification);</code></td> </tr> <tr> <td><code>Notification <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#show()" title="en/JavaScript code modules/PopupNotifications.jsm#show()">show</a>(browser, id, message, anchorID, mainAction, secondaryActions, options);</code></td> </tr> </tbody>
</table>
<h2>Methods</h2>
<h3>isPanelOpen()</h3>
<p>Reports whether or not the notification panel is currently visible.</p>
<pre>boolean isPanelOpen();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p><code>true</code> if the notification panel is currently visible; otherwise <code>false</code>.</p>
<h2>locationChange()</h2>
<p>The consumer can cell 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.</p>
<div class="note"><strong>Note:</strong> You shouldn't need to call this; it's done automatically.</div>
<pre>boolean locationChange();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p><code>true</code> if the notification persisted across the change; otherwise <code>false</code>.</p>
<h2>remove()</h2>
<p>Removes the specified notification.</p>
<pre>remove(
  Notification notification
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>notification</code></dt> <dd>The <code>Notification</code> object representing the notification to remove.</dd>
</dl>
<h3>show()</h3>
<p>Adds a new popup notification, displaying it to the user.</p>
<pre>Notification show(
  browser,
  id,
  message,
  anchorID,
  mainAction,
  secondaryActions,
  options
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>browser</code></dt> <dd>The XUL {{ XULElem("browser") }} element with which the notification is associated. This must not be <code>null</code>; you can, however, simply specify <code>gBrowser.selectedBrowser</code> to associate it with the current tab.</dd> <dt><code>id</code></dt> <dd>A unique ID string for the type of notification being displayed. For example, Geolocation related notifications have the ID "geolocation". Only one notification for each ID can be visible at a time; if one with the specified ID already exists, it will be replaced with the newer notification.</dd> <dt><code>message</code></dt> <dd>A string to display in the notification panel.</dd> <dt><code>anchorID</code></dt> <dd>The ID of the element that should serve as the anchor for the notification popup (that is, the element the arrow on the popup should point to). If you specify <code>null</code>, the notification will be anchored to the icon box at the start of the URL bar.</dd> <dt><code>mainAction</code></dt> <dd>A JavaScript object literal containing fields that define the button to draw in the notification panel. See <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#Notification_actions" title="en/JavaScript code modules/PopupNotifications.jsm#Notification actions">Notification actions</a> below for details.</dd> <dt><code>secondaryActions</code></dt> <dd>An array of notification action objects; these are used to populate the drop-down menu on the notification panel's button.</dd> <dt><code>options</code></dt> <dd>A JavaScript object containing optional properties for the notification. See <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#Notification_options" title="en/JavaScript code modules/PopupNotifications.jsm#Notification options">Notification options</a> below for details.</dd>
</dl>
<h6>Return value</h6>
<p>Returns the <code>Notification</code> object corresponding to the added notification.</p>
<h2>Notification actions</h2>
<p>Notification action objects describe the user interface for actions associated with the notification. The <strong>main action</strong> is used to describe the button presented in the notification panel, while <strong>secondary actions</strong> are displayed in the drop-down menu associated with the button.</p>
<p>A notification action object must contain the following properties:</p>
<dl> <dt><code>label</code></dt> <dd>A text label describing the action.</dd> <dt><code>accessKey</code></dt> <dd>A string indicating the keystroke that will trigger the action.</dd> <dt><code>callback</code></dt> <dd>A JavaScript function to be invoked when the action is selected by the user.</dd>
</dl>
<h2>Notification options</h2>
<p>The notification options object lets you further customize the notification panel. Any combination of the following properties may be provided:</p>
<dl> <dt><code>persistence</code></dt> <dd>An integer value indicating the number of page loads for which the notification will persist; once this many page loads have occurred, the notification may dismiss automatically.</dd> <dt><code>timeout</code></dt> <dd>A minimum number of milliseconds the notification will be displayed; it will not automatically dismiss before this amount of time has elapsed. The user may manually dismiss the notification, however.</dd> <dt><code>persistWhileVisible</code></dt> <dd>A Boolean value indicating whether or not the notification should persist across location changes. If <code>true</code>, the notification will remain visible even if the browser navigates to a different location.</dd> <dt><code>dismissed</code></dt> <dd>A Boolean value indicating whether or not the notification should be added as a <strong>dismissed notification</strong>. Dismissed notifications can be activated by clicking on their anchor. This lets you create a notification that will appear when the user clicks the anchor.</dd> <dt><code>eventCallback</code></dt> <dd>A JavaScript function to be invoked when the notification changes state. The callback's first parameter is a string identifying the state change that occurred. See <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#Notification_events" title="en/JavaScript code modules/PopupNotifications.jsm#Notification events">Notification events</a> below.</dd> <dt><code>neverShow</code></dt> <dd>A Boolean value that, if <code>true</code>, prevents the popup from ever being displayed. This can be used to simply display the anchor icon as a notification.</dd>
</dl>
<h2>Notification events</h2>
<p>If you specify an event callback using the <code>options</code> parameter when calling <code>show()</code>, 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:</p>
<dl> <dt>"dismissed"</dt> <dd>The notification has been dismissed by the user (for example, by clicking away or by switching tabs). This is different from "removed", in that the notification can be redisplayed.</dd> <dt>"removed"</dt> <dd>The notification has been removed, either by the user taking action on the notification or by the browser being navigated to a new location.</dd> <dt>"shown"</dt> <dd>The notification has become visible. This can be fired multiple times as notifications are dismissed and redisplayed.</dd>
</dl>
Revert to this revision