XUL:panel

From MDC

This article covers features introduced in Firefox 3

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

A panel is a popup window that may contain any type of content. It does not have any window decorations. When open, it floats above the window and may extend outside the border of the main window. Typically, it will be attached to an element using the popup attribute so that when the element is clicked with the left mouse button, the panel will be displayed. A panel may also be open via a script using the openPopup method.

The panel will be closed when the user clicks outside the panel or when the panel's hidePopup method is called.

Attributes: ignorekeys, left, noautofocus, noautohide, onpopuphidden, onpopuphiding, onpopupshowing, onpopupshown, position, top

Properties: accessibleType, popupBoxObject, popup, state

Methods: hidePopup, moveTo, openPopup, openPopupAtScreen, sizeTo

[edit] Examples

The following example shows how a panel may be attached to a label.

<panel id="thepanel">
  <hbox align="start">
    <image src="warning.png"/>
    <vbox>
      <description value="You have 6 new messages."/>
      <hbox>
        <button label="Read Mail"/>
        <button label="New Message"/>
      </hbox>
    </vbox>
  </hbox>
</panel>
<description value="6 New Messages" popup="thepanel"/>

[edit] 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

ignorekeys: Type: boolean; If false, the default value, the Escape key may be used to close the panel. If true, the Escape key cannot be used to close the panel.

left: Type: integer; Overrides the horizontal position of the popup specified by the showPopup method.

noautofocus: Type: boolean; If false, the default value, the currently focused element will be unfocused whenever the popup is opened or closed. If true, the focus is not adjusted.

noautohide: Type: boolean; If false, the default value, the panel will be hidden when the user clicks outside the panel or switches focus to another application. If true, the panel will only be closed when the hidePopup method is called.

onpopuphidden: Type: script code; This event is sent to a popup after it has been hidden.

onpopuphiding: Type: script code; This event is sent to a popup when it is about to be hidden.

onpopupshowing: Type: script code; This event is sent to a popup just before it is opened. This handler is usually used to dynamically set the contents when the user requests to display it. Returning false from this event handler prevents the popup from appearing.

onpopupshown: Type: script code; This is event is sent to a popup after it has been opened, much like the onload event is sent to a window when it is opened.

position: Type: one of the values below; The position attribute determines where the popup appears relative to the element the user clicked to invoke the popup. This allows you to place the popup on one side of a button.

after_start: The popup appears underneath the element with the popup's upper-left corner aligned with the lower-left corner of the element. The left edges of the element and the popup are aligned. This is typically used for drop-down menus.
after_end: The popup appears underneath the element with the popup's upper-right corner aligned with the lower-right corner of the element. The right edges of the element and the popup are aligned.
before_start: The popup appears above the element with the popup's lower-left corner aligned with the upper-left corner of the element. The left edges of the element and the popup are aligned.
before_end: The popup appears above the element with the popup's lower-right corner aligned with the upper-right corner of the element. The right edges of the element and the popup are aligned.
end_after: The popup appears to the right of the element with the popup's lower-left corner aligned with the lower-right corner of the element. The bottom edges of the element and the popup are aligned.
end_before: The popup appears to the right of the element with the popup's upper-left corner aligned with the upper-right corner of the element. The top edges of the element and the popup are aligned.
start_after: The popup appears to the left of the element with the popup's lower-right corner aligned with the lower-left corner of the element. The bottom edges of the element and the popup are aligned.
start_before: The popup appears to the left of the element with the popup's upper-right corner aligned with the upper-left corner of the element. The top edges of the element and the popup are aligned.
overlap: The popup appears over top of the element with the upper-left corners aligned.
at_pointer: The popup appears at the same position as the mouse pointer.
after_pointer: The popup appears at the same horizontal position as the mouse pointer, but vertically, it is placed just below the element.

top: Type: integer; Overrides the vertical position of the popup specified by the showPopup method.

[edit] Properties

Inherited from XUL element
align, allowEvents, boxObject, builder, className, collapsed, contextMenu, controllers, currentItem, database, datasources, dir, flex, height, hidden, id, left, listBoxObject, maxHeight, maxWidth, menu, minHeight, minWidth, observes, ordinal, orient, pack, persist, ref, resource, statusText, style, tooltip, tooltipText, top, value, width

Inherited from DOM element
attributes, childNodes, cloneNode, firstChild, lastChild, localName, namespaceURI, nextSibling, nodeName, nodeType, nodeValue, ownerDocument, parentNode, prefix, previousSibling, tagName

accessibleType: Type: integer; A value indicating the type of accessibility object for the element.

popupBoxObject: Type: nsIPopupBoxObject; This read-only property holds the nsIPopupBoxObject that implements the popup. You wouldn't normally need to use this property as all of its functions are available via the popup itself.

position: Type: string; Gets and sets the value of the position attribute.

state New in Firefox 3: Type: string; This read only property indicates whether the popup is open or not. Four values are possible:

closed: The popup is closed and not visible.
open: The popup is open and visible on screen.
showing: A request has been made to open the popup, but it has not yet been shown. This state will occur during the popupshowing event.
hiding: The popup is about to be hidden. This state will occur during the popuphiding event.

[edit] Methods

Inherited from XUL element
blur, click, doCommand, focus, getElementsByAttribute

Inherited from DOM element
addEventListener, appendChild, dispatchEvent, getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, hasAttribute, hasAttributeNS, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeAttribute, removeAttributeNode, removeAttributeNS, removeChild, removeEventListener, replaceChild, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS

hidePopup(): Return type: no return value; Closes the popup immediately.

moveTo( x, y ): Return type: no return value; Moves the popup to a new location.

openPopup( anchor , position , x , y , isContextMenu, attributesOverride ) New in Firefox 3: Return type: no return value

Open the popup relative to a specified node at a specific location.

The popup may be either anchored to another node or opened freely. To anchor a popup to a node, supply an anchor node and set the position to a string indicating the manner in which the popup should be anchored.

Possible values for position are: before_start, before_end, after_start, after_end, start_before, start_after, end_before, end_after, overlap, after_pointer

The anchor node does not need to be in the same document as the popup.

If the attributesOverride argument is true, the position attribute on the popup node overrides the position value argument. If attributesOverride is false, the attribute is only used if the position argument is empty.

For an anchored popup, the x and y arguments may be used to offset the popup from its anchored position by some number, measured in CSS pixels.

Unanchored popups may be created by supplying null as the anchor node. An unanchored popup appears at the position specified by x and y, relative to the viewport of the document containing the popup node. In case, the position and attributesOverride arguments are ignored.

The isContextMenu argument should be true for context menus and false for all other types of popups. It affects menu item highlighting; that is, while a context menu is open, menus opened earlier do not highlight or execute their items.

openPopupAtScreen( x, y, isContextMenu ) New in Firefox 3: Return type: no return value

Open the popup at a specific screen position specified by x and y. This position may be adjusted if it would cause the popup to be off of the screen. The x and y coordinates are measured in CSS pixels.