menupopup

A container used to display the contents of a popup menu. When a menupopup is open, it floats above the window and may extend outside the window border. There are several ways in which a menupopup may be used:

1. It may be placed inside a menu, menulist, toolbarbutton, or a button with the type attribute set to "menu" to create a popup that will open when the menu or button is pressed.
2. It may be attached to any element using the popup attribute. When the element is clicked with the left mouse button, the menupopup will be displayed.
3. It may be attached to any element using the context attribute. When a context menu is opened, the menupopup will be displayed. A context menu may be opened by right-clicking the element, or by pressing the menu key on the keyboard.

More information is available in the XUL tutorial.

Attributes

ignorekeys, left, onpopuphidden, onpopuphiding, onpopupshowing, onpopupshown, position, top

Properties

accessibleType, popupBoxObject, popup, state

Methods

hidePopup, moveTo, openPopup, openPopupAtScreen, showPopup, sizeTo

Examples

The following example shows how a menupopup may be attached to a menulist.

<menulist>
  <menupopup>
    <menuitem label="Mozilla" value="https://mozilla.org"/>
    <menuitem label="Slashdot" value="https://slashdot.org"/>
    <menuitem label="Sourceforge" value="https://sf.net"/>
    <menuitem label="Freshmeat" value="https://freshmeat.net"/>
  </menupopup>
</menulist>

The following example shows how a menupopup can be used a context menu for an element. When the label is right-clicked, the menu will be displayed.

<menupopup id="clipmenu">
  <menuitem label="Cut"/>
  <menuitem label="Copy"/>
  <menuitem label="Paste"/>
</menupopup>
<label value="Right click for popup" context="clipmenu"/>

Attributes

Properties

Methods

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 defined by screen coordinates (and not client coordinates).

If both x and y have the value -1 the call will realign the popup with its anchor node.

openPopup( anchor , position , x , y , isContextMenu, attributesOverride, triggerEvent )

Return type: no return value

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

anchor

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. The anchor node does not need to be in the same document as the popup. Unanchored popups may be created by supplying null as the anchor node. The direction in which the popup is oriented depends on the direction of the anchor.

position

Possible values for position are: before_start, before_end, after_start, after_end, start_before, start_after, end_before, end_after, overlap, and after_pointer. Check Positioning of the Popup Guide for a precise description of the effect of the different values.

x, y

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. An unanchored popup appears at the position specified by x and y, relative to the viewport of the document containing the popup node. In this case, the position and attributesOverride arguments are ignored.

isContextMenu

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.

attributesOverride

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.

triggerEvent

The event that triggered the popup (such as a mouse click, if the user clicked something to open the popup).

openPopupAtScreen( x, y, isContextMenu )

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.

showPopup( element, x, y, popupType, anchor, align ) Deprecated since Gecko 1.9

Return type: no return value
Deprecated in favor of openPopup and openPopupAtScreen

Opens a popup element. There are two ways of specifying where the popup appears, either at a specific screen position, or relative to some element in the window. If either x or y are set to values, the popup will appear at the screen coordinate (x,y). If x and y are -1, the popup will be positioned relative to the element specified as the first argument. This is what you might do to show a popup below a button, for example. In this latter case, the anchor and align arguments may be used to further control where the popup appears relative to the element. The anchor argument corresponds to the popupanchor attribute on the element. The align argument corresponds to the popupalign attribute on the element. The anchor and align arguments are ignored if either x or y are not -1.

To have a popup appear relative to another element yet still offset by some number of pixels, determine the actual screen position of the element using the boxObject.screenX and boxObject.screenY properties of the element, and use those as the x and y arguments offset by the desired values.

The popupType should be either the string popup, context, or tooltip. Each type of popup is intended to be displayed only temporarily; they are not expected to be displayed permanently. Only one popup may be displayed at a time.

sizeTo( width, height )

Return type: no return value

Changes the current size of the popup to the new width and height.

Related

Elements

menu, menubar, menuitem, menulist, menuseparator

Interfaces

nsIAccessibleProvider, nsIDOMXULPopupElement