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

Feature Owner: Chris Saari

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 name="File"/> <menu name="Edit"/> <menu name="View"/> <menu name="Help"/> </menubar>

The name attribute on the menus is the display name that is used for the menus. Menus 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 name attribute.

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

<menu name="File"/> <menuitem name="New..."/> <menuitem name="Close"/> <separator/> <menuitem name="Save"/> <menuitem name="Save As..."/> <separator/> <menuitem name="Exit"/> </menu>

[NOT YET IMPLEMENTED] 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 shortcut.

Accelerators are key combinations that represent the same action 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.)

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

[NOT YET IMPLEMENTED] 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.

There is only one event relevant for menu items, and that is the click event. This event can be added through script (via the addEventListener AOM API) or an onclick attribute can be placed on the menuitem tag.

Click events can also be placed on menus and menu bars. Click 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 name="File" shortcut="f"/> <menuitem name="New..." shortcut="n" key="newKey" onclick="new()"/> <menuitem name="Close" shortcut="c" key="closeKey" onclick="window.close()"/> <separator/> <menuitem name="Save" shortcut="s" key="saveKey" onclick="saveFile()"/> <menuitem name="Save As..." shortcut="a" key="saveAsKey" onclick="saveFileAs()"/> <separator/> <menuitem name="Exit" shortcut="x" key="exitKey" onclick="closeAllWindows()"/> </menu>