MenuButtons

Menu Buttons

Menus may be attached to buttons in several ways. Both the button and the toolbar button elements support two special types used for creating menu buttons.

• A button or toolbarbutton with a type attribute set to 'menu' creates a button that will open a menu when pressed. An arrow appears on the button next to the label or image indicating to the user that a menu is present.
• A button or toolbarbutton with a type attribute set to 'menu-button' creates a button that can be pressed normally. However a segment of the button displays an arrow which, when pressed, opens a menu.

In either case, a menupopup element should be placed as a direct child of the button.

The 'menu' button

The 'menu' type of button is used when pressing the button alone should just open the menu and not execute a command directly. This works similarly to the menu tag, and would be used to present a set of commands to execute. To create a button of this type, set the type attribute of the button to 'menu'.

For instance, in the following example, pressing the 'View' button will open a menu which allows the user to select from a set of radio menuitems. Presumably, when one is selected, the application view would be changed accordingly. When using the keyboard, pressing the Down key will open the menu while the button is focused.

<button type="menu" label="View">
  <menupopup>
    <menuitem label="Icons" type="radio" name="view"/>
    <menuitem label="List" type="radio" name="view"/>
    <menuitem label="Details" type="radio" name="view"/>
  </menupopup>
</button>

Note that when the menu is closed, the button doesn't indicate which view is selected. If you do want this indication, you should use a menulist instead.

The same technique can be used for toolbarbuttons as well as buttons. In the example below a toolbarbutton with an image has a menu associated with it.

<toolbarbutton type="menu" image="cookies.png">
  <menupopup>
    <menuitem label="Block Cookies" type="checkbox"/>
    <menuitem label="Clear Cookies"/>
  </menupopup>
</toolbarbutton>

The 'menu-button' button

The 'menu-button' type of button is used when you want to attach a menu to a button but want to have a default action carried out when the button is pressed by itself. This is accomplished by dividing the button into two parts, one with the label and image to carry out the default command and the second to show the menu. To create a button of this type, set the type attribute of the button to 'menu-button'.

<toolbarbutton type="menu-button" label="Save" oncommand="alert('Save');">
  <menupopup>
    <menuitem label="Save This Document"/>
    <menuitem label="Save All" oncommand="alert('Save All'); event.stopPropagation();"/>
  </menupopup>
</toolbarbutton>

Here, the 'Save' button has a type of 'menu-button', so a small arrow button will appear which will open the menu when pressed. Pressing the label part of the button will invoke the command event on the button, so the 'Save' alert will appear. However, we can associate a different command with the items on the submenu.

When the command is fired, it bubbles up through the chain of elements to the top of the document. When the first item on the menu ('Save This Document') is activated, it will also display the 'Save' alert as the command event bubbles up to the button. In this situation, this menuitem performs the same operation as pressing the regular part of the button. The second menu item ('Save All') has a command event of its own that displays a different alert with the text 'Save All'. The stopPropagation method is used to stop the bubbling effect so that the command event on the button does not get called as well.

The effect is a button that performs one command with a menu for other commands. As with this example, the 'menu-button' type of button is usually used when the menu provides more specific options pertaining to the operation. We might want to extend this example to insert a list of the unsaved documents to the Save button menu so that each could be saved individually.

You might want to set the first item in the example above as the default button, so it indicates to the user that the command is carried out when the main button is pressed. This can be done by setting the default attribute on the item to true.

<menuitem label="Save This Document" default="true"/>

See Indicating_the_Default_Item for more information about the default attribute.

As with the 'menu' type, the 'menu-button' type may be applied to either the button or the toolbarbutton element.