This is an archived page. It's not actively maintained.


Handling Keys Within Menus

When using a menupopup element, a keyboard listener is attached to the window that will handle keypresses for the menu. This allows items within the menu to be navigated with the cursor keys. The following table lists the keys that are checked, and what the menu keyboard listener does in response:

Cursor Up/Down Move the highlight within the menu up or down, wrapping around if necessary. On Linux and the Macintosh, disabled items within the menu are skipped over when navigating with the cursor keys.
Cursor Left/Right When a menu is selected, cursor right opens the menu, while a cursor left closes a menu. In a menubar, cursor left and right will cycle between top level menus.
Home/End Move the highlight to the beginning or the end of the menu, selecting the first or last item.
Enter/Return Activate the currently highlighted item. If a menuitem is selected, this will close the menu and fire the menuitem's command event. If a menu is selected, the menu will open.
Escape Closes the menu. If a chain of submenus is open, only one level of menus is closed.
Tab/F10 Closes all menus in a chain of submenus.

When letter keys are pressed, the accesskeys within the menu are selected. If an access key is a pressed that does not correspond to an item within the menu, items that don't have access keys can be selected if the key pressed corresponds to the first letter of the label.

Other keys are ignored by the menu key listener, however, the event does not propagate to the main window. This is because the key listener is a capturing listener attached to the document.

For a panel, the only key that is handled by default is the escape key to close the panel. The other keys do not apply.

Focus in Popups

A menu does not take the keyboard focus. The menu key listener described above captures key events on the document. Thus, a key listener added to a <menupopup> will not receive any key events. Instead, you must add a capturing key listener to the document or window if you want to listen for keys pressed within a menu. Note that the last argument here is true to listen for events during the capturing phase of event propagation:

window.addEventListener("keypress", someAction, true);

However, the default listener provides all the suitable responses to keys, so there shouldn't be a need to handle keys yourself.

While a menu is open, the focus remains where it was before the menu was open. For example, focusing a textbox and opening the textbox's context menu keeps the focus within the textbox. However, the capturing listener ensures that no key events reach the textbox while the menu is open.

Unlike with a menu, when a panel is opened, the focus is removed from any element that has it. This allows the focus to be shifted to elements within the panel. For more information about focus handling within panels, see Focus in Panels.

Ignoring Keys

The ignorekeys attribute may be used to disable the key listener described above. When the ignorekeys attribute is placed on a <menupopup> or <panel> element, and its value is set to the value true, the key listener is not used.

<panel ignorekeys="true">

In this case, none of the key handling described above is performed. Instead, you will have to handle this yourself. You would not normally use this attribute for a menu, however you may wish to disable the escape key handling for a panel in this way.