TableView User Experience Documentation

Author: Jan Rojcek

1. Introduction

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

2. Overview

TableView is a control used for displaying and editing a list of items (rows) with multiple properties (columns). It is a complex control with many features suiting different data presentation and editing use cases. Typical example on desktop platform is a list of email and a list of TV programs on TV platform.

Please note that for Presidio release, we will implement DB-style table only. Other table styles, such as spreadsheet or properties-style table, are not part of this release. Because of that, features like cell or row spanning, grouped cells, or a selection in which all items that belongs to a rectangle formed by range's start and end points should be selected are not supported.

Figure 1 Table overview

Table 1.1 Desktop Table features overview

3. Desktop: Detailed Behaviors

Column header

Header is the topmost table row showing names of columns. It is always visible as it does not scroll with content. It is a place where the user performs table column customization including column resizing, column rearrangement, column hiding/showing and sorting. Header can span multiple columns, if it shows grouped columns with the name of the group above individual column names.

Figure 2 Column header overview

See detailed sections below describing sorting, and rearranging with resizing (not implemented in Presidio release). Column hiding and showing behaves like a regular menu button with check box menu items. See menu spec for details.

Cell

Cells display table content as labels, icons, check boxes or other standard controls. Custom cells are also supported. Cells support horizontal and vertical alignment, automatic sizing when cell width or height automatically fits content size, and multi-row and multi-column cells when a cell spans multiple columns or rows. Cell formatters display standard textual values in predefined style, in some cases corresponding to localization settings of native platform (e.g. date, time, numbers).

Figure 3 Cell overview

In addition to displaying values or information, cells can also be selected, edited or they can represent actions. Cell space is usually limited, therefore multiple clicks are sometimes necessary to differentiate between selection or editing. Possible pointing device click behavior after clicking into an unselected cell:

• First click selects the clicked cell (or row, column). Second click edits the cell with the associated cell editor.
• First click edits the clicked cell with the associated cell editor. No change in selection.
• First click invokes the cell action represented with a hyperlink, icon, button or check box. No change in selection.
• Mixed mode when the behavior depends on the cell content being clicked. E.g. if a drop down arrow is clicked it edits the cell; if a hyperlink is clicked it invokes an action; if a label is clicked it selects the cell.

Selection

TableView supports the following selection modes: single-row; multi-cell, and multi-row selection. The multi-selection modes are supported with typical Ctrl-Click when controlled with a pointing device.

Figure 4 Selection overview

In multi-selection modes, one selected item (cell, row or column) is marked as a selection lead. It indicates the beginning of range selection when making range selection with pointing device (Shift-Click). For keyboard control, the selection lead is the focused item controlled with arrow keys.

The following table assumes the first click initiates selection change. It describes behavior for cell selection. The same behavior applies to row and column selection.

Table 2 Pointing device selection behavior

Note: If a cell is selected on a single click you enter the cell editing mode. If it is not selected and you double click on it, the cell becomes selected and you immediately enter the cell editing mode. You should also be able to double click on already selected cell and enter the cell editing mode.

Cell editor

If a cell is editable, it permits the user modify cell value using a standard JavaFX control which may be different than the control used for viewing the value. For example a table cell may show a value as a label, but after clicking it it turns into a choice box with popup list open. This is necessary to keep the table appearance clean for viewing and avoid all the necessary visual clutter that would be present if every cell in the same column displayed values as a closed choice box. Cell editors are usually text boxes, choice boxes or check boxes. Custom editors are also supported.

Figure 5 Cell editor overview

If the same control is used for viewing and editing (e.g. check boxes or radio buttons) then cell editors are visible directly and it is not necessary to select the cell before using the editor. If a different control is used for viewing and editing, developers should have the following options:

• Do not indicate the editor. This is typically used for textual values with text box editor as such editing model is well known. The text box editor appears after second click into a selected item.
• Show the whole or part of the editor after selecting the corresponding cell. This give the user visual indication the cell is editable on second click.
• Show the whole or part of the editor (e.g. a drop down button) on pointer-hover. It permits the user to invoke editor directly after clicking the editor (or part of it).

When a cell is being edited, clicking outside of the edited cell commits the value and removes the cell editor. If there was an error with committing the value, the developer needs to handle it for example by showing an error message and keeping keyboard focus in the edited cell in editing mode.

Figure 6 Click to edit behavior (4 possible alternatives; note that the pink dot represents the left mouse click)

Please note that pictures above show the behavior of the cell editor for text boxes, and choice boxes only. Other controls, e.g. check boxes or radio buttons, have the cell editor visible directly so it is not necessary to select the cell before using the cell editor.

Normal - shows a cell in its normal state
Rollover - shows appearance of a cell when the mouse cursor appears over it
Selected - shows appearance of a cell which the user clicked on or hit Space on (after navigating to the cell using the keyboard)
Edited - shows the cell editor in action

Cell action

Some cells are actionable, which means they permit the user invoke actions rather than edit values inline. Hyper links, icons or buttons may be used inside cells for that purpose. Similarly to cell editors, cell actions may work in mixed mode where the user needs to click exactly on the cell action (e.g. hyperlink) and clicking elsewhere inside the cell initiates cell selection.

Empty table

If a table is empty, it permits developer to show a label or other content cross the whole table area. This is useful to explain why the table is empty.

Figure 7 Empty table

Sorting

Table permits the user to sort columns by clicking the table header and it visually indicates which column the table is sorted by. It also supports multi-column sorting. The user clicks on a secondary (or tertiary, etc.) sorting column while holding the Shift key down. All columns then show visual sorting indication.

Please note, that there should be an option for developers to be able to disable sorting of a column or a row.

Figure 8 Sorting overview

Table 3 Pointing device sorting behavior

Resizing

Table content width may be unrelated to table width, or it may be constrained to fit table width. Resizing of the whole table and table columns behaves differently in both modes.

When the user resizes the whole table width in the unconstrained mode, the table just shows or hides horizontal scroll bar as needed with no effect on column size. In constrained mode (fit to table width), it increases or decreases column widths proportionally.

When the user resizes an individual column in the unconstrained mode, the table automatically adjusts the position of columns on the right hand size to the resized column and keeps their width untouched. See the following figure.

Figure 9 Column resizing unconstrained

When the user resizes a column width in the constrained mode, the table automatically adjusts the width of the right hand side columns. When the user increases a column width, the table decreases the width of the rightmost column until it reaches its minimum width. Then it decreases the width of the second rightmost column until it reaches minimum width and so on. When all right hand side columns reach minimum size, the user cannot increase the size of resized column any more.

When the user decreases a column width, the rightmost column increases its width until it reaches its preferred width. The preferred width is a width set by the developer or later changed by the user. When it reaches preferred width, the second rightmost column increases its width until it reaches its preferred width and so on. If the user keeps decreasing width of the column and all right hand side columns already reached their preferred size, the rightmost column increases its width even more than the preferred width to keep the constraint and fill in the table width. See the following figure.

Figure 9.1 Column resizing constrained to fit table width

Filtering and searching

Filtering is an advance feature permitting the user to define clear criteria for permanent display of column content. It is up to the developer to specify whether there are filters for no columns, individual columns, or all columns.

Searching is a lightweight filtering for short-lived narrowing of table content. It means that searching works across whole table.

Figure 10 Filtering overview

Figure 11 Searching overview

Note: In Presidio, we'll be supporting table-wide filtering (aka searching), but not filtering on specific columns (at least, not in the sense that we'll be offering any kind of 'filter bar' as shown in figure 11). Table-wide filtering will have no UI - the developer will be responsible for creating the UI as necessary.

Pagination

On desktop platform, scrolling is a common way how to show more table rows than can fit into available table size. Sometimes when table data cannot load at once it may be desirable to show it paginated controlled by Next/Previous Page actions in the table toolbar.

Figure 12 Pagination overview

Note: The UI for this feature is not part of Presidio release.

4. Desktop: Keyboard Support

Table 5 Desktop Keyboard support