MenuButton and SplitMenuButton User Experience Documentation

Author: Jindrich Dinga

1. Introduction

This document is the user experience specification for the JavaFX MenuButton and SplitMenuButton UI controls.

2. Overview

MenuButton

The MenuButton is a control that offers a list of choices to the user. It can contain an icon, label, or both, and an arrow.

figure 1 - MenuButton states

Please note that the whole area of the button is click-able.

SplitMenuButton

The SplitMenuButton is a control that consists from two buttons: 1. main button and 2. pop-up menu button. It allows users to change the function of the main button by selecting items from the pop-up menu. The most recently selected item becomes the main button item.

figure 2 - SplitMenuButton states

The SplitMenuButton works as follows:

the main button contains an action/function
the user clicks on the small button that shows the pop-up menu
- the user selects new action/function
the new action/function replaces the previous action/function
- new action/function IS NOT performed
the user clicks the main button
- new action/function IS performed

Please note, that it should be possible to modify behavior of this button so actions that the user selects from the pop-up menu do not change the default action that is available on the main button.

The SplitMenuButton supports only a single-level menu. Also, it can contain an icon, label, or both.

3 Keyboard Support

The following table describes how keystrokes should be processed in case a MenuButton has focus:

Keystroke	Action
Space	Opens the Pop-up menu.
Enter	Opens the Pop-up menu. When the Pop-up menu is open and focus is on a menu item, it performs its associated action.
Up Arrow	If Up Arrow icon is available on the menu button and the Pop-up menu is closed, it opens the Pop-up menu. If the Pop-up menu is open, it moves focus to the previous menu item in the Pop-up menu, wrapping from first to last.
Down Arrow	If Down Arrow icon is available on the menu button and the Pop-up menu is closed, it opens the Pop-up menu. If the Pop-up menu is opened, it moves focus to the next menu item in the Pop-up menu, wrapping from last to first.
Left Arrow	If Left Arrow icon is available on the menu button and the Pop-up menu is closed, it opens the Pop-up menu.
Right Arrow	If Right Arrow icon is available on the menu button and the Pop-up menu is closed, it opens the Pop-up menu.
Esc	Dismisses the Pop-up menu, if it is open.
Tab	Moves focus to the next focusable control.
Shift - Tab	Moves focus to the previous focusable control.

The following table describes how keystrokes should be processed in case a SplitMenuButton has focus:

Keystroke	Action
Space	Performs action that is available on the main button.
Enter	Performs action that is available on the main button. When the Pop-up menu is open and focus is on an action, it replaces action that is available on the main button with the selected action.
Up Arrow	If Up Arrow icon is available on the pop-up menu button and the Pop-up menu is closed, it opens the Pop-up menu. If the Pop-up menu is open, it moves focus to the previous menu item in the Pop-up menu, wrapping from first to last.
Down Arrow	If Down Arrow icon is available on the pop-up menu button and the Pop-up menu is closed, it opens the Pop-up menu. If the Pop-up menu is open, it moves focus to the next menu item in the Pop-up menu, wrapping from last to first.
Left Arrow	If Left Arrow icon is available on the pop-up menu button and the Pop-up menu is closed, it opens the Pop-up menu.
Right Arrow	If Right Arrow icon is available on the pop-up menu button and the Pop-up menu is closed, it opens the Pop-up menu.
Esc	Dismisses the Pop-up menu, if it is open.
Tab	Moves focus to the next focusable control.
Shift - Tab	Moves focus to the previous focusable control.