ToolBar User Experience Documentation

Author: Jan Rojcek

1. Introduction

This document is the user experience specification for the JavaFX Toolbar control.

2. Toolbar Overview

A Toolbar is a container control that makes the most commonly used controls easily accessible. Toolbar typically contains controls that represent actions (e.g. buttons, menu buttons), options (e.g. choice buttons, toggle buttons), information (e.g. labels), or user inputs (e.g. text fields). For visual separation of controls, toolbar may contain separator or spacer control.

Figure 1 Toolbar on desktop, mobile and TV platform

3. Toolbar: Desktop

3.1 Desktop - Introduction

Toolbar on desktop platform is located below a window title bar. It is a shortcut to commonly used actions and features that are also available in the main menu. Users usually use a pointing device to access controls in the toolbar. For applications where toolbar is the primary access to actions (no main menu, or menu hidden by default) and for accessibility reasons, toolbar controls can also be accessed with keyboard.

Toolbar is a container control and primary user interaction occurs with the controls inside the toolbar. The individual controls including separator and spacer are described in separate UE specs. Toolbar itself handles:

• layout of controls
• access to toolbar controls if there is not enough room to show them all inside toolbar
• customization of toolbars with drag and drop, or keyboard
• keyboard access to toolbar controls (2D and linear focus traversal)
• options to show controls with small, big icons, and whether to show labels or not. Note: This may not be a "built-in" behavior and may require developers using toolbar to implement it. Toolbar just needs to permit it.

Figure 2 Toolbar placement on desktop platform

3.2 Desktop - Detailed Behaviors

Layout

Toolbar on desktop platform can be horizontal or vertical.

Toolbar arranges controls in single or multiple rows (or columns) with defined spacing between controls. Controls can either have fixed or flexible width (height). Flexible width controls (e.g. text field, spacer) take up the whole available width of toolbar. If there are more flexible-width controls inside a toolbar, they evenly divide the available toolbar width while taking into account the minimum width of each flexible-width control. Thus a flexible-width control with larger minimum width should get more from the available toolbar width.

Figure 3 Toolbar layout

Figure 4 Multiple-row Toolbar layout

Figure 5 Vertical Toolbar layout

Shortened toolbar

Toolbars should be designed in a way that all controls inside toolbar are visible and thus easily accessible. If the user shortens a toolbar by making the application window smaller up to the point where some controls do not fit in, the toolbar moves the not-fitting controls into an additional popup toolbar accessible through a popup toolbar button. The user needs to click the popup button to open the popup toolbar. It closes when the user clicks the popup button again or clicks anywhere outside of the popup. For keyboard access, see keyboard support.

Note that toolbar items do not wrap in case of a multiple row toolbar. The popup toolbar button shows in each row where items do not fit in.

Figure 6 Shortened toolbar with additional popup toolbar

Table 1 Toolbar popup button pointer gestures

Icons, labels and tooltips

Toolbar control can contain any other control and it is up to developers to provide toolbar content that works well for end users. The following paragraph describes common toolbar behavior on desktop platform regarding icons, labels and tooltips that may be expected from developers and end users.

Note: The following may not be a "built-in" behavior and may require developers using the toolbar control to implement it. Toolbar just needs to permit it.

Typical toolbar in a desktop application uses small icons (usually 24x24) without labels for standard toolbar controls (e.g. buttons, toggle buttons). Developers have an option to use large icons (typically 32x32) and also show labels next to the toolbar controls. Toolbar and/or developer tools need to make it easy to achieve common layout as shown in figures below. If a developer wants to make customization available, the default toolbar customization needs to permit the developer to show options that would let end users change icon size and show or hide labels.

As individual toolbar items may not be labeled, they should have tooltips. It is up to the developer to provide them for individual toolbar controls.

Customization

If developer permits it, the user can customize content and appearance of toolbar. To customize toolbar, the user opens a customization panel from a toolbar contextual menu. See Table 4 for contextual menu items. The customization panel permits the user to add new items from the panel into the toolbar with drag and drop. When the panel is open, the user can also drag and drop items inside a toolbar to rearrange them or drag them out of toolbar to remove them. If customization panel is not open, drag and drop gestures inside toolbar are not permitted.

The customization panel can be also open from application main menu. It is up to the developer to insert a Customize Toolbar item into application menu.

If a developer provides it, the user can modify icon size, show or hide labels, or remove items using the toolbar contextual menu or using the customization panel. It is up to the developer to insert appropriate customization menu items into the toolbar and controls into the customization panel.

If a toolbar supports multiple rows, developer should be permitted to add a special Add Row button into the customization panel. If the user clicks the button, it adds an empty toolbar row into the toolbar. The user can then add items into the row. When the user removes all items from a toolbar row and closes the customization panel, the empty toolbar row disappears.

If a toolbar contains items with varying height and the user removes the highest item from the toolbar, it automatically readjusts its size to fit the highest remaining item in the toolbar. Similarly, if the user adds a higher item into the toolbar, the toolbar adjusts its height to fit it.

Figure 7 Toolbar customization

Table 2 Pointer gestures on toolbar items

Table 3 Optional items in the Show choice button (the choice button is provided by developer)

Table 4 Toolbar contextual menu items (the optional items are provided by developer)

States

Table 5 Toolbar states

3.3 Desktop - Keyboard Support

The user can access toolbar items with the keyboard. As controls in the toolbar usually do not consume navigation keys (buttons, toggle buttons), it is feasible to implement 2D traversal for simplified navigation in the toolbar. The tab traversal works as usual and it is required if a control that consumes navigation keys in the toolbar gets focus (e.g. text field). In such case Tab key is the only way to move focus forward.

If toolbar is shortened and the popup toolbar button gets focus, it automatically shows the additional popup toolbar. The user can then use the down arrow or Tab key to move focus to the additional toolbar items.

Figure 8 Toolbar popup accessed with keyboard

In customization mode, the user can rearrange items by copy-pasting. If an item is copied, it is marked with a special dotted line visual indication and the focus indicator moves in between items in the toolbar to allow pasting a copied toolbar control between existing toolbar controls. If the user pastes the copied toolbar item, the toolbar items rearrange. See figure below for an example. To cancel copying, the user needs to press the ESC key. The focus indicator then switches to a regular mode where it marks toolbar items instead of space in between

Figure 9 Toolbar customization with keyboard

Table 6 Toolbar keyboard support

Please note that on Mac OS X, Ctrl+F5 should move focus to the window toolbar.

3.4 Desktop - Attributes

Table 7 Toolbar attributes on desktop platform

4. Toolbar: Touch

4.1 Touch - Introduction

On Touch platform, toolbars appear at the top, bottom or both locations of mobile screen. If the application is in landscape mode, the toolbars are placed along the long edges of mobile screen.

Figure 10 Toolbar placement on Touch platform in portrait and landscape mode.

4.2 Touch - Detailed Behaviors

Toolbar arranges controls in a single or multiple rows with defined spacing between controls. Controls can either have fixed or flexible width. Flexible width controls (e.g. text field, spacer) take up the whole available width of toolbar. If there are more flexible-width controls inside a toolbar, they evenly divide the available toolbar width while taking into account the minimum width of each flexible-width control. Thus a flexible-width control with larger minimum width should get more from the available toolbar width. See the desktop platform description for illustration.

4.3 Mobile Touch - Attributes

Table 8 Toolbar attributes on mobile touch

5. Toolbar: 2D Traversal

5.1 2D Traversal - Introduction

See Touch description.

5.2 2D Traversal - Detailed Behaviors

See Touch description.

5.3 2D Traversal - Keyboard Support

Table 9 Toolbar keyboard support on Mobile 2D traversal platform

5.4 2D Traversal - Attributes

Table 10 Toolbar attributes on mobile touch