View Source

Author: Maya Venkatraman

1. Introduction

This is the user experience specification for the list control which allows users to do two essential things:

View a set of items
Choose one or more of the set of items

2. Overview

2.1 General Characteristics of a List Component

A list component lets users view all the choices they have and select one or more of these choices. Users may also be able to edit a list.

A set of cells that are vertically or horizontally stacked.
Users are able to select one or more that one items from the list
If the list if editable, users are able to add , detele and rename items on the list
List cells are containers that can have text, links, images and buttons

OpenJFX > ListView User Experience Documentation > ListA.png
Figure 1: Parts of a List

2.2 Selecting between a List, Choice button, radio button & table

Lists, ChoiceButtons, Radio Buttons and Tables can all be used to present the user with multiple choices and allow the user select between the offered choices. These are the criterion that application developers will use to select between these components.

When to use the list component:

The list component is the only choice when the set of choices needs to be editable.
Examples: A list of phone contacts, A list of tasks, a list of recordings or songs.
The list component is the only choice when the user needs to have the option to select more than one of the choices. List is the only component that supports multi-select.
Example : List of toppings the user needs to add to the list.
If the cells need to contain images and buttons.
[Note: ChoiceButton lists also support showing images and text].
Example: A list of contact phone numbers with a edit button in each row/cell
If we need to display images as a horizonally scrolling lists, the list component is again
the only choice.

Figure 2: How a developer decides which component to use when the application presents choices to the user. This flow diagram sets the functional scope for this and related components.

[NOTE: A table can be seen as a list with multiple columns. If data needs to be presented using more than one column use a table. ]

2.3 Behavior of the List Components

This section describes the various states and behaviors associated with the list component. The states themselves are platform independent. All lists must be able to support these behaviors and states. However each platform can have its own set of gestures that trigger any of these states. In subsequent sections we will describe how these states are arrived at on various platforms.

2.3.1 States of the List Cell

OpenJFX > ListView User Experience Documentation > ListB.png
Figure 3: States of list cell

Selected state: Users should be able to pick one or more options offered to them.
The visual appearance of the selected list items should reflect that they are the current selections
Normal state: This is the normal state of a list item. It can include light and dark banding
for readability
Edit state: In this state the user can edit text inside a cell.
Hover State : When the user is hovering on a List cell, its visual appearance should change
indicating that it has focus. Buttons and links can also be revealed in this (rollover like) state.
It should be possible to invoke a hover pop up for a list cell item.
[Note: traversing to a cell with a keyboard, in other words moving focus to the cell, should
have the same effect as hover. Viewing a hover popup should involve moving focus to a
cell via the keyboard and then using a shortcut to invoke the hover-popup (see spec.?)]

List cell contents should be clickable (in other words it should be possible for users to click on a
link inside the list cell (say) and navigate to another screen

All these apply to lists in an enabled state. Lists as a whole can also be in a disabled state.

2.3.2 Actions

Figure 4: Actions related to List Cells

The list itself can be modified by actions like adding and removing from the list
users can start or stop processes corresponding to list items by clicking on links or buttons that are inside the list cell
users can go to a details page corresponding to a list cell
users can edit the list cell text

2.3.2.1 Adding to a List

OpenJFX > ListView User Experience Documentation > AddSteps.png
Figure 5: Adding to lists

NOTE: The list component needs to support the usage where developers will use them in a manner described in the above figure. It may be a desirable to build the add functions directly into the component itself (as shown above).

2.3.2.2 Editing a list cell

If a list cell has text in it, users should be able to edit the text inline. Inline edit involves bringing focus to the text element and
indicating by a gesture (double click, tap) that the text needs to be edited. At this point, the control should essentially become a
text box in both appearance and behavior.

2.3.2.3 Default actions

List Items can have a default action tied to them. If the user clicks "Enter" (or makes an equivalent gesture to enter), this will invoke an action. If the control to this action is also displayed in the List Cell, it should receive focus first when the user navigates to that cell. It should also (probably) be the first in the list of controls if there are controls.

2.3.3 Scrolling

If the amount of information that needs to be displayed in larger than the screen space available, the list should be placed in a scroll-pane. Scrolling should be allowed in the horizontal and vertical directions as needed. Vertical scrolling, by clicking on the arrows should move the list in the appropriate direction, one row at a time. If a fraction of a row is visible, clicking on the arrow, should first result in that row scrolling into / out of view in its entirety. If the user is using the arrow keys to move focus, the focus should never be moved off the visible are of the list. When the arrow click would result in focus moving offscreen, the user gesture (arrow key press) should cause the system to display the list after scrolling one item over, and assign the newly visible item focus.

2.3.4 Selection
Users should be able to select one or more than one items on the list, using the appropriate selection mechanism for the device.

Selection Models for List Components

Lists should support three kinds of choices: single item, single range, and multiple ranges.
Single-item selection provides users with an exclusive choice.
Single-range and multiple-range selection provide users with nonexclusive choices.

The user can select items on the list. The choice persists even when the user has moved on to the next component. If the user later selects another object, this selection disappears.

Single Range of Items: Users select an item. The item gets keyboard focus and becomes the anchor point of the selection. Users extend the selection by dragging or by moving the pointer to another item and Shift-clicking.

Multiple Ranges of Items: Users select a single item and then extending the selection by Shift-clicking. To start another range, users Control-click an item. That item then gets keyboard focus and becomes the anchor point of the new range. In addition, the selection of the item is toggled--if the item was initially selected, it is deselected, and vice versa. Shift-clicking extends the new range.

SPECIAL TOPIC A: Horizontal Lists:

There are a case where the list items / cells are stacked horizontally. The only use case for this is when the list items are images or ions. List items should have a separator between them.
OpenJFX > ListView User Experience Documentation > list6.png
Figure 6: Horizontal Lists

[NOTE: It would be highly desirable at some point, to have a version of this that uses arrows on the sides rather than the scrollbar at the bottom]

SPECIAL TOPIC B: Layout and Organization

A list can have multiple simple components in it. For instance, lists can have text, images, buttons etc. By default - these simple components should be arranged horizontally, with padding and spacer as per the visual specification.
If one of the list items text strings is longer than the width of the component less the padding, the text should scroll.
If images are being used in the list, they should be of the same size.
The list component does not support vertical wrapping.
List items can be blank.
Lists can have groups with one level indentation.
Lists can have items that are group titles. These are non selectable items and will be visually distinct from selectable items.

3 Desktop - Introduction

This section ONLY describes special requirements placed on the list control by the desktop platform.

Two general notes about lists on the desktop:

On the desktop lists can appear as part of other controls on the screen (as part of a form or otherwise).
Desktop will need to support resizing of the list component.

3.1 Desktop - Detailed Behaviors

Desktop behaviors are described in the general section above.

This figure shows how each of these states is caused on a desktop platform.
OpenJFX > ListView User Experience Documentation > ListF.png
Figure 7: List Cell states in Desktop case

In addition the entire list can be in a disabled state.

Focus Traversal within the List Control

Typically there will be only one active control within a list cell. If there is more than one control
or link with in a cell, users should be able to get to the individual items by using the L-R or up-down arrow keys.
In case of a typical list, the Up and Down arrow keys are tied to moving the user through the list cells,
the Left and Right arrow keys will therefore be used for moving the user through various
If the list has a title area with a control in it, the control will need to be on the traversal path.

3.2 Desktop - Keyboard Support

3.2.1 Windows & Linux

Key	Result
Mouse button 1(Left Mouse button)	If the item was initially selected, it get deselected If the item was initially unselected, it gets selected
Mouse button 2 (right mouse button	If there is a choice button (aka popup menu) that is tied to the list, it will be presented when the user right clicks on the list items
Up	Moves focus & selection up one item. Creates anchor. All previous selections are canceled.
Down	Moves focus & selection down one item. Creates anchor. All previous selections are canceled.
Left	Moves focus & selection left one item. Creates anchor. All previous selections are canceled.
Right	Moves focus & selection right one item. Creates anchor. All previous selections are canceled.
Ctrl-Up	Moves focus up without changing selection.
Ctrl-Down	Moves focus down without changing selection.
Ctrl-Left	Moves focus left without changing selection.
Ctrl-Right	Moves focus right without changing selection.
Shift-Up	Expands or contracts selection up by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Shift-Up selects all items between anchor and the item which is right above the focused item. The item which is right above the focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Up key should be processed. See description of Up behavior for more details.
Shift-Down	Expands or contracts selection down by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Shift-Down selects all items between anchor and the item which is right below the focused item. The item which is right below the focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Down key should be processed. See description of Down behavior for more details.
Shift-Left	Expands or contracts selection left by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Shift-Left selects all items between anchor and the item which is on left of the focused item. The item which is on the left of the focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Left key should be processed. See description of Left behavior for more details.
Shift-Right	Expands or contracts selection right by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Shift-Right selects all items between anchor and the item which is on right of the focused item. The item which is on the right of the focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Right key should be processed. See description of Right behavior for more details.
Space	Selects focused item if it is not selected. Creates anchor.
Ctrl-Space	Selects focused item if it is not selected. Deselects focused item if it is selected. Creates anchor.
Shift-Space	Selects all items between anchor and focused item. Focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Space key should be processed. See description of Space behavior for more details.
F2	Edit selected item.
Home	Moves focus & selection to the first item.
End	Moves focus & selection to the last item.
Shift-Home	Selects all items between anchor and the first item. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Home key should be processed. See description of Home behavior for more details.
Shift-End	Selects all items between anchor and the last item. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only End key should be processed. See description of End behavior for more details.
Ctrl-Home	Moves focus to the first item.
Ctrl-End	Moves focus to the last item.
PageUp	Move the selection up on the first fully visible item on the current page. If the first fully visible item is selected, move the selection on the first fully visible item on the previous page. In multi-selection mode, it cancels all previous selections. Creates anchor.
PageDown	Move the selection down on the last fully visible item on the current page. If the last fully visible item is selected, move the selection on the last fully visible item on the next page. In multi-selection mode, it cancels all previous selections. Creates anchor.
Shift-PageUp	Select all items between anchor and the first fully visible item on the current page. If the first fully visible item is already included in the selection, extend the selection to the first fully visible item on the previous page. All previous selections, if applicable, are canceled. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only PageUp key should be processed. See description of PageUp behavior for more details.
Shift-PageDown	Select all items between anchor and the last fully visible item on the current page. If the last fully visible item is already included in the selection, extend the selection to the last fully visible item on the next page. All previous selections, if applicable, are canceled. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only PageDown key should be processed. See description of PageDown behavior for more details.
Ctrl-PageUp	Move focus up on the first fully visible item on the current page. If the first fully visible item is focused, move focus on the first fully visible item on the previous page.
Ctrl-PageDown	Move focus down on the last fully visible item on the current page. If the last fully visible item is focused, move focus on the last fully visible item on the next page.
Ctrl-A	Selects entire table. Focus remains on the same item. In multi-selection mode only.
Esc	Cancels editing.
Enter	Confirms editing (depends on the cell editor).
Ctrl-Shift-Up	Expands selection up by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Ctrl-Shift-Up selects all items between anchor and the item which is right above the focused item. The item which is right above the focused item is also included in the selection. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-Up should be processed. See description of Ctrl-Up behavior for more details.
Ctrl-Shift-Down	Expands selection down by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Ctrl-Shift-Down selects all items between anchor and the item which is right below the focused item. The item which is right below the focused item is also included in the selection. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-Down should be processed. See description of Ctrl-Down behavior for more details.
Ctrl-Shift-Left	Expands selection left by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Ctrl-Shift-Left selects all items between anchor and the item which is on left side of the focused item. The item which is on left side of the focused item is also included in the selection. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-Left should be processed. See description of Ctrl-Left behavior for more details.
Ctrl-Shift-Right	Expands selection right by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Ctrl-Shift-Right selects all items between anchor and the item which is on right side of the focused item. The item which is on right side of the focused item is also included in the selection. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-Right should be processed. See description of Ctrl-Right behavior for more details.
Ctrl-Shift-Space	Selects all items between anchor and focused item. Focused item is also included in the selection. Create anchor. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-Space should be processed. See description of Ctrl-Space behavior for more details.
Ctrl-Shift-Home	Selects all items between anchor and the first item. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-Home should be processed. See description of Ctrl-Home behavior for more details.
Ctrl-Shift-End	Selects all items between anchor and the last item. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-End should be processed. See description of Ctrl-End behavior for more details.
Ctrl-Shift-PageUp	Select all items between anchor and the first fully visible item on the current page. If the first fully visible item is already included in the selection, extend the selection to the first fully visible item on the previous page. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-PageUp should be processed. See description of Ctrl-PageUp behavior for more details.
Ctrl-Shift-PageDown	Select all items between anchor and the last fully visible item on the current page. If the last fully visible item is already included in the selection, extend the selection to the last fully visible item on the next page. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Ctrl-PageDown should be processed. See description of Ctrl-PageDown behavior for more details.

3.2.2 Mac

Key	Result
Mouse button 1(Left Mouse button)	If the item was initially selected, it get deselected If the item was initially unselected, it gets selected
Mouse button 2 (right mouse button	If there is a choice button (aka popup menu) that is tied to the list, it will be presented when the user right clicks on the list items
Up	Moves focus & selection up one item. Creates anchor. All previous selections are canceled.
Down	Moves focus & selection down one item. Creates anchor. All previous selections are canceled.
Left	Moves focus & selection left one item. Creates anchor. All previous selections are canceled.
Right	Moves focus & selection right one item. Creates anchor. All previous selections are canceled.
Cmd-Up	Moves focus up without changing selection.
Cmd-Down	Moves focus down without changing selection.
Cmd-Left	Moves focus left without changing selection.
Cmd-Right	Moves focus right without changing selection.
Shift-Up	Expands or contracts selection up by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Shift-Up selects all items between anchor and the item which is right above the focused item. The item which is right above the focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Up key should be processed. See description of Up behavior for more details.
Shift-Down	Expands or contracts selection down by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Shift-Down selects all items between anchor and the item which is right below the focused item. The item which is right below the focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Down key should be processed. See description of Down behavior for more details.
Shift-Left	Expands or contracts selection left by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Shift-Left selects all items between anchor and the item which is on left of the focused item. The item which is on the left of the focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Left key should be processed. See description of Left behavior for more details.
Shift-Right	Expands or contracts selection right by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Shift-Right selects all items between anchor and the item which is on right of the focused item. The item which is on the right of the focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Right key should be processed. See description of Right behavior for more details.
Space	Selects focused item if it is not selected. Creates anchor.
Cmd-Ctrl-Space	Selects focused item if it is not selected. Deselects focused item if it is selected. Creates anchor.
Shift-Space	Selects all items between anchor and focused item. Focused item is also included in the selection. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Space key should be processed. See description of Space behavior for more details.
F2	Edit selected item.
Home	Moves focus & selection to the first item.
End	Moves focus & selection to the last item.
Shift-Home	Selects all items between anchor and the first item. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Home key should be processed. See description of Home behavior for more details.
Shift-End	Selects all items between anchor and the last item. All previous selections are canceled, if applicable. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only End key should be processed. See description of End behavior for more details.
Cmd-Home	Moves focus to the first item.
Cmd-End	Moves focus to the last item.
PageUp	Move the selection up on the first fully visible item on the current page. If the first fully visible item is selected, move the selection on the first fully visible item on the previous page. In multi-selection mode, it cancels all previous selections. Creates anchor.
PageDown	Move the selection down on the last fully visible item on the current page. If the last fully visible item is selected, move the selection on the last fully visible item on the next page. In multi-selection mode, it cancels all previous selections. Creates anchor.
Shift-PageUp	Select all items between anchor and the first fully visible item on the current page. If the first fully visible item is already included in the selection, extend the selection to the first fully visible item on the previous page. All previous selections, if applicable, are canceled. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only PageUp key should be processed. See description of PageUp behavior for more details.
Shift-PageDown	Select all items between anchor and the last fully visible item on the current page. If the last fully visible item is already included in the selection, extend the selection to the last fully visible item on the next page. All previous selections, if applicable, are canceled. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only PageDown key should be processed. See description of PageDown behavior for more details.
Cmd-PageUp	Move focus up on the first fully visible item on the current page. If the first fully visible item is focused, move focus on the first fully visible item on the previous page.
Cmd-PageDown	Move focus down on the last fully visible item on the current page. If the last fully visible item is focused, move focus on the last fully visible item on the next page.
Cmd-A	Selects entire table. Focus remains on the same item. In multi-selection mode only.
Esc	Cancels editing.
Enter	Confirms editing (depends on the cell editor).
Cmd-Shift-Up	Expands selection up by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Ctrl-Shift-Up selects all items between anchor and the item which is right above the focused item. The item which is right above the focused item is also included in the selection. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-Up should be processed. See description of Cmd-Up behavior for more details.
Cmd-Shift-Down	Expands selection down by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Ctrl-Shift-Down selects all items between anchor and the item which is right below the focused item. The item which is right below the focused item is also included in the selection. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-Down should be processed. See description of Cmd-Down behavior for more details.
Cmd-Shift-Left	Expands selection left by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Ctrl-Shift-Left selects all items between anchor and the item which is on left side of the focused item. The item which is on left side of the focused item is also included in the selection. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-Left should be processed. See description of Cmd-Left behavior for more details.
Cmd-Shift-Right	Expands selection right by one item. Only in multi-selection modes. If focus is on an unselected item, pressing Ctrl-Shift-Right selects all items between anchor and the item which is on right side of the focused item. The item which is on right side of the focused item is also included in the selection. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-Right should be processed. See description of Cmd-Right behavior for more details.
Cmd-Shift-Space	Selects all items between anchor and focused item. Focused item is also included in the selection. Create anchor. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-Space should be processed. See description of Cmd-Space behavior for more details.
Cmd-Shift-Home	Selects all items between anchor and the first item. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-Home should be processed. See description of Cmd-Home behavior for more details.
Cmd-Shift-End	Selects all items between anchor and the last item. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-End should be processed. See description of Cmd-End behavior for more details.
Cmd-Shift-PageUp	Select all items between anchor and the first fully visible item on the current page. If the first fully visible item is already included in the selection, extend the selection to the first fully visible item on the previous page. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-PageUp should be processed. See description of Cmd-PageUp behavior for more details.
Cmd-Shift-PageDown	Select all items between anchor and the last fully visible item on the current page. If the last fully visible item is already included in the selection, extend the selection to the last fully visible item on the next page. Available in multi-selection mode only. In single selection mode, Shift key should be ignored and only Cmd-PageDown should be processed. See description of Cmd-PageDown behavior for more details.