TreeTable UE Specification
Author: Jindrich Dinga
1. Introduction
This document is the user experience specification for JavaFX TreeTable control.
JavaFX TreeTable control is a control that displays a tree in a table. Usually, the first column shows the tree and rest of columns display additional data besides the tree. Typical example of an application that may use a tree table control is a file management or e-mail client. In such application, the first column typically shows name of folders and files. The other columns show size, time stamp, etc. Users are usually allowed to re-order, sort, filter columns, search the tree table, etc.
Example of a tree table control
2. Description
JavaFX TreeTable control combines features of TreeView and TableView control. These features are as follows:
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.
Description of column header in a tree table control
See detailed sections below describing sorting, rearranging with resizing (DnD), and column hiding/showing.
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).
Description of cells in a tree table control
In addition to displaying values or information, cells can also be 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 row/cell. 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.
Tree
The most left column in JavaFX TreeTable control shows a tree.
A tree consists of nodes that can be opened and closed by interacting with a "turner" icon. The very first node in the tree is called root node and it is possible to hide it. Nodes that contain other nodes are called parents (these nodes have the "turner" icon); nodes that do not contain any other nodes are called leaf nodes (these nodes do not have the "turner" icon). Nodes can be opened by clicking on the "turner" icons or by double clicking the node name (note that if editing is enabled, double click will enter the edit mode).
In addition to the "turner" icons, nodes can also have other icons, such as
- Lazy Evaluation Icons - these icons appear either in place of the "turner" icons or after the name of the node name to indicate that information about that node is still being retrieved from the system.
- Node Icons - these icons appear to the left of the node name. Clicking on these icons selects the node. Multiple node icons should be supported. It should be possible to set tool tips for these icons.
By default a custom tree cell should provide one Icon and Node Name text. In addition, it should be possible for the application developer to add a checkbox and at least two more icons for each node.
Description of the tree in a tree table control
The tree should remember expanded nodes and reopen in its prior state. Applications may want to:
- always reopen the tree with all the nodes closed & scrolled to the top,
- always reopen the tree in another state specified by the application developer, or
- always reopen the tree in its previous state. Application developer should be able to specify one of these settings.
Selection
JavaFX TreeTable control supports the following selection modes: single row, single cell, multiple row, and multiple cell selection. In multiple selection mode, users can use SHIFT or CTRL/CMD keys to select multiple rows or cells. Please note that the cell selection is not so common, thus is disabled by default.
Single selection in a tree table controlMultiple selection in a tree table control
In the multiple selection mode, one selected row is marked as an anchor. It indicates the beginning of a range selection when making the range selection with pointing device (SHIFT Click).
A tree table control with a selection and focus should have "primary highlighting" to show selection. A tree table with a selection but without focus should show "secondary highlighting" for the selection. These states apply to root, parent, child, leaf node in both the open and closed states.
The following table describes what happens when users interact with rows/cells using a pointing device (e.g. mouse):
Target row/cell is not selected
Click | Select row/cell. Make it the anchor. |
Ctrl Click | Add row/cell to the selection. Make it the anchor. |
Shift Click | Add the range of rows/cells between the anchor and clicked row/cell to the selection. |
Double Click | Select row/cell and make it the anchor. Also, if the cell has an associated action, invoke this action (e.g. open file in filesystem table view), otherwise if it has an associated editor, switch the cell to editing. |
Press-Drag-Release | Select the range of rows/cells between the press-target row/cell and release-target row/cell. |
Ctrl-Press-Drag-Release | Add the range of rows/cells between the press-target row/cell and release-target row/cell into the selection. |
Target row/cell is selected
Click | Edit cell if an editor is associated with the clicked cell. |
Ctrl Click | Clear the clicked row/cell from the selection. Do not change the anchor. |
Shift Click | Add or remove rows/cells from the selection between anchor and clicked row/cell. Clicked row/cell stays selected. |
Double Click | If the cell has an associated action, invoke this action (e.g. open file in filesystem table view), otherwise if it has an associated editor, switch the cell to editing. |
Press-Drag-Release | Initiates drag and drop. |
Ctrl-Press-Drag-Release | Initiates drag and drop. |
Cell Editor
If a cell is editable, it permits the user to modify the 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 pop-up 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.
Overview of cell editors in a table control
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.
Click to edit behavior
In case of a tree table control when a whole row is selected and all cells are editable, cell editors appear in each cell on the selected row. Cell editor that is focused is the cell editor of the cell users clicked on. If users used F2 or other key combination to enter the edit mode, the first cell editor on the selected row is focused.
When in edit mode, users can traverse between other cell editors by using TAB key. Pressing ENTER or clicking outside of the edited row commits the changes and removes all cell editors. Pressing ESC reverts changes and removes all cell editors.
Example of a tree table control in edit mode
Cell Action
Some cells are actionable, which means they permit the user to invoke actions rather than edit values inline. Hyperlinks, 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 TreeTable
If a tree table is empty, it permits developer to show a label or other content across the whole tree table area. This is useful to explain why the tree table is empty.
Sorting
Users are allowed to sort the tree table by clicking its column headers. First click on a column header sorts data in the column in ascending order. The second click on the column header sorts data in descending order and finally the third click turns sorting of the column off.
If users hold SHIFT key while clicking column headers, data in the tree table will sort according to multiple columns. When SHIFT key is released and users click a column header, the multiple column sorting is canceled.
In both cases, single or multiple column sorting, a visual indication is displayed in column headers.
Please note that the column sorting should be 'active', in the sense that newly expanded branches will be sorted if there is a column being sorted.
Example of a single column sorted in ascending order
Example of multiple columns sorted in ascending order
Application developers are allowed to specify where the sort occurs:
- ALL DESCENDANTS (default; sort all nodes) and
- ONLY FIRST LEVEL (sort first level nodes only regardless of whether the root is actually being shown or not).
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 picture.
Column resizing (unconstrained mode)
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 picture.
Column resizing (constrained mode)
Rearrangement (DnD)
JavaFX TreeTable supports drag and drop of columns. To rearrange columns, users must drag a column header to a new position. When dropped, new position of the column is preserved.
Column rearrangement in a tree table control
Context Menus
JavaFX TreeTable control supports contextual menus that can be invoked by right click or by SHIFT+F10 key combination. Application developers are allowed to attach actions to these menus.
Example of a context menu in a tree table control
Show/Hide Column Button
JavaFX TreeTable supports the show/hide column button. If enabled, this button appears in top right corner. When clicked, a pop-up menu appears allowing users to show or hide columns in the table.
Show/Hide column button in a tree table control
Column hiding and showing behaves like a regular menu button with check box menu items.
Cell Styling Support
JavaFX TreeTable supports cell styling that allows application developers to style cells, rows, and columns as needed.
Example of a tree table control with differently styled cells, and columns
Keyboard Support
The following tables describe actions that happen after users press the following keys:
Windows
Up | Move focus & selection up by one item. Create anchor. Cancel all previous selections. |
Down | Move focus & selection down by one item. Create anchor. Cancel all previous selections. |
Left | Row: Collapse current selection (or go to the parent node) |
Right | Row: Expand current selection (or go to the first child node). |
Ctrl-Up | Move focus up by one item without changing selection. |
Ctrl-Down | Move focus down by one item without changing selection. |
Shift-Up | Expand or contract selection up by one item. Only in multi-selection modes. 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 | Expand or contract selection down by one item. Only in multi-selection modes. In single selection mode, Shift key should be ignored and only Down key should be processed. See description of Down behavior for more details. |
Space | Select focused item if it is not selected. |
Ctrl-Space | Select focused item if it is not selected. Deselect focused item if it is selected. Create anchor. |
Shift-Space | Select 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 | Move focus & selection to the first item. Create anchor. |
End | Move focus & selection to the last item. Create anchor. |
Shift-Home | Select 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 | Select 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 | Move focus to the first item. |
Ctrl-End | Move 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. |
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. |
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. 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. 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 | Select entire tree table. In multi-selection mode only. |
Esc | Cancel editing. |
Enter | Confirm editing (depends on the cell editor). |
Ctrl-Shift-Up | Expand or contract selection up by one item. Only in multi-selection modes. 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 | Expand or contract selection down by one item. Only in multi-selection modes. 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-Space | Select 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 | Select 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 | Select 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. 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. 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. |
* (numlock) | When a node is selected, expand all nodes. |
+ (numlock) | When a parent node is selected, expand the node. |
- (numlock) | When a parent node is selected, collapse the node. |
Mac OS
Up | Move focus & selection up by one item. Create anchor. Cancel all previous selections. |
Down | Move focus & selection down by one item. Create anchor. Cancel all previous selections. |
Left | Row: Collapse current selection (or go to the parent node) |
Right | Row: Expand current selection (or go to the first child node). |
Cmd-Up | Move focus up by one item without changing selection. |
Cmd-Down | Move focus down by one item without changing selection. |
Shift-Up | Expand or contract selection up by one item. Only in multi-selection modes. 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 | Expand or contract selection down by one item. Only in multi-selection modes. In single selection mode, Shift key should be ignored and only Down key should be processed. See description of Down behavior for more details. |
Space | Select focused item if it is not selected. |
Cmd-Ctrl-Space | Select focused item if it is not selected. Deselect focused item if it is selected. Create anchor. |
Shift-Space | Select 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 | Move focus & selection to the first item. Create anchor. |
End | Move focus & selection to the last item. Create anchor. |
Shift-Home | Select 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 | Select 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 | Move focus to the first item. |
Cmd-End | Move 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. |
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. |
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. 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. 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 | Select entire tree table. In multi-selection mode only. |
Esc | Cancel editing. |
Enter | Confirm editing (depends on the cell editor). |
Cmd-Shift-Up | Expand or contract selection up by one item. Only in multi-selection modes. 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 | Expand or contract selection down by one item. Only in multi-selection modes. 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-Space | Select 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 | Select 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 | Select 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. 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. 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. |
* (numlock) | When a node is selected, expand all nodes. |
+ (numlock) | When a parent node is selected, expand the node. |
- (numlock) | When a parent node is selected, collapse the node. |
Overview
Content Tools
ThemeBuilder