Popup Guide

Popups and Menus

There are various types of popups and menus that may be created. A popup is a menu or floating window without a title bar, borders or other window decorations that may extend outside of the edge of the main window.

Popup Types

XUL provides a number of different types of elements which may be used to create popup menus or other types of popup widgets, which vary based on the manner in which they are attached to an element and the manner in which they are opened. A brief overview of each type is listed here; more details for each type can be found by following the corresponding links. A popup is not created as a separate window or file, instead it is included inside another window or dialog.

In this guide, the term 'popup' refers to all types of popups, whereas the term 'menu' refers to a specific type of popup. Specifically, the first two types in the list below are menus.

Menus

A menu is used when you wish to have a series of commands that can be activated by the user, but don't want to use the extra space for a button for each command. A menu is normally hidden, and when activated, a popup appears containing the list of commands. The user may select a command and the menu disappears again.

A menu is created using the menupopup element. It displays items in a list, can display submenus, and provides keyboard navigation between the items. A menu should only contain menu related elements.

Context Menus

A context menu is like a regular menu except that the commands it contains apply to what the user had clicked on to open the context menu. Often, depending on what was clicked on, certain commands may be hidden if not applicable to that element.

Panels

A panel can contain any type of content. It is useful when you wish to display some controls temporarily over the existing UI. For example, a popup search field could be used to allow searching and will disappear when a search term has been entered.

A panel is created using the panel element.

Floating Panels

A floating popup is a type of panel with a titlebar and acts like an auxiliary window. Usually it would contain tools related to the main window, or an inspector which displays properties of a selected element.

Tooltips

When the mouse is positioned over a UI control, a tooltip provides a small box with descriptive help about that control. When the mouse is moved away from the control, the tooltip automatically disappears.

A tooltip can be created by setting the tooltiptext attribute on an element or by using the tooltip element.

Working with Popups

The following additional information is available about manipulating menus and popups.

Opening a Menu or Popup

Most menus and popups are opened automatically when they are associated with an element. To open a popup using script use the openPopup method or the openPopupAtScreen method. For detailed information about how to open a popup see Opening a Popup or Opening a Menu.

Closing a Menu or Popup

For information about closing a popup, see Closing a Popup or Closing a Menu.

How Popups are Placed

To read about how the position of a popup on screen is determined, and how to align popups to other elements, see Positioning Popups.

Determining if a Popup is Open

To determine if a popup or menu is open, see Determining if a Popup is Open.

Moving a Popup

Popups may be moved using the moveTo method. See Moving a Popup.

Resizing a Popup

The size of a popup may be adjusted using the sizeTo method. See Resizing a Popup.

Attaching Menus to a Button

To learn about how to open a menu when a button is pressed, see Menu Buttons.

Features of Items on a Menu

To learn about the various features of items on a menu, see Features of the menuitem Element

Modifying the Items on a Menu

To append, insert and remove elements from a menu, see Modifying a Menu.

Events when Popups are Opened or Closed

The popupshowing and popupshown events are fired when a menu or popup is opened. The popuphiding and The popuphidden events are fired when a menu or popup is closed. For information about these events, see Popup Events.

Handling Keys Within Popups

For information about how keys are handled within menus and panels, see Handling Keys Within Popups.

Platform Specific Menu Considerations

See Special Per-Platform Menu Considerations for some notes about handling menus on certain platforms, for instance creating the Application menu on a Macintosh.

Using Popups in Extensions

Extensions may add additional menuitems either to a menu on the menu bar or to the context menu. In addition, an extension may add an entirely new menu. For example, an extension might wish to add a new command on the Tools menu to open a dialog specific to the extension. Another common task is to create an extension which adds an item to the browser's context menu. See Using Menus and Popups in Extensions for details.