notificationbox

« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

The notificationbox element is used to display notifications above an element. Typically the element will be a browser, but any element may be used. The notification element is used for each notification, and will be created automatically for each item. Each notification will slide in and out as needed. This element is used, for example, to implement the yellow information bar in various Firefox windows.

notificationbox2.png

The notification box is a vertical box which may have children. The notifications appear at the top of the box. The notifications may be placed at the bottom by setting the dir attribute to reverse.

Finding the current notification box

Within a Firefox extension, you can retrieve the current notification box for a specific tab by calling the global function getNotificationBox():

notifyBox = chromeWin.getNotificationBox(notifyWindow)
notifyBox = getNotificationBox(notifyWindow) // applies to current context's window object

Here, chromeWin is the XUL window (usually just window), and notifyWindow is the web content window for the tab you want to find the notification box for.

Also it is possible to call function with the same name (they are different) of global object gBrowser:

notifyBox = gBrowser.getNotificationBox()

Examples

<notificationbox flex="1">
  <browser src="http://www.mozilla.org"/>
</notificationbox>

There is a more complex code available in the Code Snippets area. 

 

 

Properties
currentNotification, allNotifications, notificationsHidden

 

Methods
appendNotification, getNotificationWithValue, removeAllNotifications, removeCurrentNotification, removeNotification, removeTransientNotifications,

Attributes

Inherited from XUL element
align, allowevents, allownegativeassertions, class, coalesceduplicatearcs, collapsed, container, containment, context, contextmenu, datasources, dir, empty, equalsize, flags, flex, height, hidden, id, insertafter, insertbefore, left, maxheight, maxwidth, menu, minheight, minwidth, mousethrough, observes, ordinal, orient, pack, persist, popup, position, preference-editable, querytype, ref, removeelement, sortDirection, sortResource, sortResource2, statustext, style, template, tooltip, tooltiptext, top, uri, wait-cursor, width

Properties

currentNotification
Type: notification element
The currently displayed notification element or null. This property is read-only.
allNotifications
Type: nodeList
NodeList of all notifications. This property is read-only.
notificationsHidden
Type: boolean
Indicating whether the notification area should be hidden.

Events

AlertActive
Type: Event
Fired when a notification element is shown.
AlertClose New in Mobile 2
Type: Event
Fired when a notification element is closed.

Methods

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature(), getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData
appendNotification( label , value , image , priority , buttons, eventCallback )
Return type: element
Create a new notification and display it. If another notification is already present with a higher priority, the new notification will be added behind it.
  • label - label to appear on the notification. This should be either a string, or, from Gecko 37 onwards, you can pass a DocumentFragment with rich content as well. Keep in mind that this is all XUL so using HTML elements for styling might still need additional CSS in order to work as you might expect.
  • value - value used to identify the notification
  • image - URL of image to appear on the notification. If "" then an icon appropriate for the priority level is used.
  • priority - notification priority; see Priority Levels.
  • buttons - array of button descriptions to appear on the notification.
  • eventCallback Optional - a JavaScript function to call to notify you of interesting things that happen with the notification box. See Notification box events.
Priority Levels (defined as properties of notificationbox) :
  • PRIORITY_INFO_LOW
  • PRIORITY_INFO_MEDIUM
  • PRIORITY_INFO_HIGH
  • PRIORITY_WARNING_LOW
  • PRIORITY_WARNING_MEDIUM
  • PRIORITY_WARNING_HIGH
  • PRIORITY_CRITICAL_LOW
  • PRIORITY_CRITICAL_MEDIUM
  • PRIORITY_CRITICAL_HIGH
  • PRIORITY_CRITICAL_BLOCK
Buttons :
The buttons argument is an array of button descriptions. Each description is an object with the following properties:
  • accessKey - the accesskey to appear on the button
  • callback - function to be called when the button is activated. This function is passed three arguments:
    • the <notification> the button is associated with
    • the button description as passed to appendNotification.
    • the element which was the target of the button press event.
    • If the return value from this function is not True, then the notification is closed. The notification is also not closed if an error is thrown.
  • label - the label to appear on the button
  • popup - the id of a popup for the button. If null, the button is not a button popup (e.g. a menu). The type property must also be set to "menu", or "menu-button".
  • isDefault - if True, this is the default button. There can be only one default button. If no button has this set, the first button in the array is the default.
  • type - a string. Valid values are "menu-button" and "menu" which must be set if the button is to provide a popup via the popup property.

 

getNotificationWithValue( value )
Return type: notification element
Retrieve the notification with a particular value. The value is specified when adding the notification with appendNotification. If no matching value is found, returns null.
removeAllNotifications( immediate )
Return type: no return value
Remove all notifications. If immediate is true, the messages are removed immediately. If immediate is false, the notifications are removed using a slide transition.
removeCurrentNotification()
Return type: no return value
Remove the current notification.
removeNotification( item )
Return type: element
Remove a notification, displaying the next one if the removed item is the current one.
removeTransientNotifications( )
Return type: no return value
Remove only those notifications that have a persistence value of zero, and decrements by one the persistence value of those that have a non-zero value.

Elements
notification

Document Tags and Contributors

Tags: 
 Contributors to this page: Sheppy, Wjjohnst, Oeekker, zencd, Mook, Enn, Gerv, Marsf, 2bass, MarkFinkle, Ptak82
 Last updated by: Sheppy,