XUL:Popups
Popups and Menus
Menupopups
The <menupopup> element is used for creating popup menus. Popup menus may contain menu-related elements such as <menu>, <menuitem> and <menuseparator>. The <menupopup> element creates a popup which provides special behaviour such that items on the menu highlight, open and close as necessary when they are hovered over. Keyboard navigation between items is provided. The cursor keys navigate between items and other characters may be used for accesskey navigation. In addition, when the mouse is clicked outside the popup, the entire chain of menus and submenus that are currently open is closed.
There are two ways of use a menupopup, either a popup associated with a menu, or a standalone popup. The former should be a child of a <menu>, or an element with a resolved tag of menu. The latter is usually used for context menus and is attached to an element via either the popup or contextmenu attributes.
<menupopup position="position" left="left" top="top"/>
Possible values are listed below.
- ignorekeys
- set to true to disable keyboard navigation on the menu. The default is false.
- left
- the horizontal screen position of the menupopup. Should rarely be used.
- popupalign
- (deprecated) the edge of the popup to anchor to the parent menu. Use position instead.
- popupanchor
- (deprecated) the edge of the parent menu to anchor to. Use position instead.
- position
- the alignment of the menupopup in relation to its parent menu.
- top
- the vertical screen position of the menupopup. Should rarely be used.
The descriptions below are for a locale where the UI is displayed left to right and top to bottom. In this case, before is the top, after is the bottom, start is the left and end is the right. For right to left locales, start is the right and end is the left.
Possible values for the position attribute are:
- before_start
- the popup appears above the anchor, aligned on the left.
- before_end
- the popup appears above the anchor, aligned on the right.
- after_start
- the popup appears below the anchor, aligned on the left.
- after_end
- the popup appears below the anchor, aligned on the right.
- start_before
- the popup appears to the left of the anchor, aligned on the top.
- start_after
- the popup appears to the left of the anchor, aligned on the bottom.
- end_before
- the popup appears to the right of the anchor, aligned on the top.
- end_after
- the popup appears to the right of the anchor, aligned on the bottom.
- overlap
- the popup overlaps the anchor, with the topleft corners of both the anchor and popup aligned
- after_pointer
- the popup appears with the top aligned with the bottom of the anchor, with the topleft corner of the popup at the horizontal position of the mouse pointer
The default value is overlap.
Panels
Tooltips
The usual way of using a tooltip is to use the tooltiptext attribute on an element. For example:
<button label="Save" tooltiptext="Save all changes"/>
This will create a popup tooltip using the default tooltip appearance. For a custom tooltip, the tooltip attribute may be used instead. It should be set to the id of a <tooltip> element within the same document.
<tooltip id="custom-tooltip"> <label="Save all changes"/> <tooltip> <button label="Save" tooltip="custom-tooltip"/>
Tooltips always appear just next to the mouse pointer.
New Popup API
/** * 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 * * If the aAttributesOverride argument is true, the popupanchor, popupalign * and position attributes on the popup node override the position value * argument. If aAttributesOverride is false, the attributes are only used * if the values passed to this method are 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 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. * * @param anchorElement the node to anchor the popup to, may be null * @param position manner is which to anchor the popup to node * @param x horizontal offset * @param y vertical offset * @param isContextMenu true for context menus, false for other popups * @param attributesOverride true if popup node attributes override position */ void openPopup(in nsIDOMElement anchorElement, in AString position, in long x, in long y, in boolean isContextMenu, in boolean attributesOverride); /** * 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. * * @param x horizontal screen position * @param y vertical screen position * @param isContextMenu true for context menus, false for other popups */ void openPopupAtScreen(in long x, in long y, in isContextMenu); /** * Hide the popup if it is open. */ void hidePopup();