[Table of Contents] [Previous: Introduction to a XUL Document] [Next: Toolbars and Toolboxes]

Feature Owner:
Chris Saari (Mac Menus)
David Hyatt (XP Menus)

A XUL document can contain exactly one menu bar, specified using the menubar tag. As one might expect, this tag specifies the contents of the menu bar. This menu bar is either placed inside the window (on Windows and GTK) or is used as the menu bar when the window specified by the XUL file is the active window (on the Mac).

If the XUL document is not opened as a top-level window (see Windows and Dialogs), then the menubar tag is ignored.

The menubar tag contains menu tags as children. Each menu child represents one top-level menu on the menu bar.

<menubar> <menu value="File"/> <menu value="Edit"/> <menu value="View"/> <menu value="Help"/> </menubar>

The value attribute on the menus is the display name that is used for the menus. Menus contain a menupopup tag that represents the popup view for a menu. This popup can contain menus or menu items as children, the distinction being that menus always have children, and menu items never have children. Menu items are represented using the menuitem tag, and their display names are also set using the value attribute.

Separators are represented using the menuseparator tag. This tag contains no children.

<menu value="File"/> <menupopup> <menuitem value="New..."/> <menuitem value="Close"/> <menuseparator/> <menuitem value="Save"/> <menuitem value="Save As..."/> <menuseparator/> <menuitem value="Exit"/> </menupopup> </menu>

Menus can also have shortcut keys and accelerators defined. The shortcut key is a single letter that can be used (on some platforms) to quickly access the menu in combination with another key (e.g., ALT). The attribute for specifying this key is accesskey.

Accelerators are key combinations that represent the same command that would be invoked if the menu item were selected. There is a single attribute key whose value represents the ID of a key element in the key binding set. (See Key Binding for details.) You can also just specify the accelerator text directly using the acceltext attribute.

<menu value="File" accesskey="f"/> <menuitem value="New..." accesskey="n" key="newKey"/> <menuitem value="Close" accesskey="c" key="closeKey"/> <separator/> <menuitem value="Save" accesskey="s" key="saveKey"/> <menuitem value="Save As..." accesskey="a" key="saveAsKey"/> <separator/> <menuitem value="Exit" accesskey="x" key="exitKey"/> </menu>

Menus can be enabled or disabled. The disabled attribute, if set to true, indicates that the menu item is disabled. The setAttribute and unsetAttribute AOM methods can be used on the menu or menu item element to set and clear this attribute. Doing so will cause the menu or menu item to enable/disable.

[NOT YET IMPLEMENTED] Menus can also be checked (or unchecked). The checked attribute, if set to true, indicates that the menu item is checked. As with the disabled attribute, the AOM APIs can be used to check or uncheck the menu by setting or unsetting this attribute.

The command event is executed whenever a menu item is invoked. This event can be added through script (via the addEventListener AOM API) or an oncommand attribute can be placed on the menuitem tag.

Command event listeners can also be placed on menus and menu bars. Command events that occur on menu items, if not handled by the items, will bubble up to their parent menus, to the menu bar, and then up into the document.

<menu value="File" accesskey="f"/> <menuitem value="New..." accesskey="n" key="newKey" command="new()"/> <menuitem value="Close" accesskey="c" key="closeKey" command="window.close()"/> <separator/> <menuitem value="Save" accesskey="s" key="saveKey" command="saveFile()"/> <menuitem value="Save As..." accesskey="a" key="saveAsKey" command="saveFileAs()"/> <separator/> <menuitem value="Exit" accesskey="x" key="exitKey" command="closeAllWindows()"/> </menu>

On platforms other than the Macintosh, menus and menu items may contain arbitrary HTML/XUL. If HTML/XUL is placed inside a menu item or menu, it will be used as the menu's look (rather than the display text and accelerator text used by default if no HTML/XUL children are specified). Be aware if you choose to do this that the Macintosh cannot display these tags. Always have a value attribute and an oncommand attribute on menu items to ensure interoperability with the Mac.