NOTE:
This specification is "in progress". I'll peridocially update it to include sections with information about more details, and to reflect feedback from the community. A revision history can be found a the bottom of the document.
Feedback on this specification should be sent to the jdnc@jdnc.dev.java.net mailing list (see the mailing list subscription page and the forums which are a different presentation of the same information).
The most common use of a tree table component is to display a hierarchical list of objects. In this usage, each row represents an object, and each column represents some attribute of that object. Additionally, an object may have one or more "child" objects which are shown indented beneath the "parent" object.
Note: "object" means an object in the mind of the user (file, appointment, breakpoint, etc), not a java.lang.Object.
This document is a user interface specification for that usage of a TreeTable in JDNC (called a Hierarchical Object List in this document). It contains sections for all the behaviors and the appearance details of that usage, with sub-sections for four different looks and feels (JLF/Ocean, Windows XP, GNOME 2.x and Macintosh OS X 10.3).
Note: JDNC will not deliver a Macintosh look and feel. This is documented here to help demonstrate the breadth of features the component must be able to support, and to provide guidance to anyone that would like to provide this support.
This specification covers two categories of details. The first is information that must be provided by the component itself. The second category is information that an application developer can use to make their application more professional and to avoid "re-inventing the wheel" for these common design decisions.
Note that after the Overview section, the terms MUST, SHOULD and MAY in this document have the formal meaning found in http://rfc.net/rfc2119.html. Much of the information about what is standard on the various platforms comes from some demo applications. These are provided for GNOME/GTK+2.0, Macintosh.A list must allow 0 or 1, or multiple rows to be selected. Continuous and discontinuous sets of rows may be selected.
![]() |
![]() |
When a row is selected, the whole row must be selected.
One term will be useful to understand the rules below:
These are the rules for row selection with the keyboard and mouse. These have been derived from those in the Windows Explorer list view. Aside from being reasonably well defined and internally consistent, this is also the model used by other Swing components in the Windows look and feel.
There are written standards for Mouse and Keyboard interfaces in The Microsoft Windows User Experience book. However, the list view doesn't fully adhere to those guidelines. These links are provided just for reference.
The component must support two editing modes (detailed further below). The gestures below assume either that the cell clicked on is a non-editable cell, or the list is in select-click-to-edit mode. (this will make more sense when you read that editing section)
This table documents the location of the focus indicator. Note that the focus indicator is not always shown to the user.
On a Selected Row | On a Non-Selected Row | On Background | |
---|---|---|---|
Left Click | Selected: Clicked row (on mouseDown) Deselected: All others (on mouseUp when in selection, on mouseDown when outside) Anchor: Clicked row Focus: Clicked row | Selected: None Deselected: All (on mouseUp) Anchor: No change Focus: No change | |
Shift Left Click | Selected: Rows between anchor and clicked (inclusive) (on mouseDown) Deselected: All others (on mouseDown) Anchor: No change Focus: Clicked row | Selected: None Deselected: None Anchor: No change Focus: No change | |
Ctrl Left Click | Selected: None Deselected: Clicked row (on mouseUp) Anchor: Clicked row Focus: Clicked row | Selected: Clicked row (on mouseUp) Deselected: None Anchor: Clicked row Focus: Clicked row | |
Ctrl-Shift Left Click | Selected: If the Anchor is selected, then all rows between the anchor and the clicked row (inclusive). Otherwise, only the clicked row is selected Deselected: If the anchor is selected, then none. Otherwise, all rows between the anchor and the clicked row (exclusive). Anchor: No change Focus: Clicked row | ||
Arrow up/down | Selected: Row above/below row that had focus Deselected: All others Anchor: Row above/below row that had focus Focus: The row above/below the row that had focus | n/a | |
Shift Arrow up/down | Selected: Rows between anchor and row above/below row that had focus (inclusive) Deselected: All others Anchor: No change Focus: The row above/below the row that had focus | ||
Ctrl Arrow up/down | Selected: None Deselected: None Anchor: No change Focus: The row above/below the row that had focus | ||
Ctrl-Shift Arrow up/down | Same as Shift Arrow up/down | ||
Space | Selected: None Deselected: None Anchor: No change Focus: No change | Selected: Row with focus Deselected: None Anchor: No change Focus: No change | |
Shift Space | Selected: Rows between anchor and focused (inclusive) Deselected: All others Anchor: No change Focus: No change | ||
Ctrl Space | Selected: None Deselected: Row with focus Anchor: Row with focus Focus: No change | Selected: Row with focus Deselected: None Anchor: Row with focus Focus: No change | |
Ctrl-Shift Space | Selected: Row with focus Deselected: All others Anchor: Row with focus Focus: No change |
Other notes:
Ordinarily the component provides a keyboard focus in the individual cells. This allows the component to provide a way to manipulate the size and ordering of the columns from the keyboard in a cross-platform manner. However, the component should provide a mode where the keyboard focus spans all cells of a row, which is more consistent with the Windows style. In this case, however, it the columns must not be able to be resized or repositioned.
Appearance:
This image demonstrates a multiple selection, and the keyboard focus on the third row. Note: This is a mockup, which is based on a combination of the behavior in Windows Explorer details view, and the feedback in some of the MMC plugins (e.g. Event Viewer)
This demonstrates the same list, but with the keyboard focus moved out of the selection (this also is a mockup):
This demonstrates the same list when some other component has the focus. Unsurprisingly, the keyboard focus is not shown at all. This is also a mockup, but note that the blue-tinted icons on the left are actually what Windows does in the Explorer.
This demonstrates the keyboard focus existing in a single cell, which should be used any time there are editable cells. This is emphatically a mockup.
The JLF/Ocean behaviors should be identical to the Windows ones, above, with these exceptions:
Relevant resources are the summary of shortcuts for lists and for trees in the JLF Design Guidelines.
The rules for keyboard navigation and row selection presented here are derived from those in the System Monitor tree view (type Ctrl-Alt-Del from the GNOME environment to get it). This seems to be basically consistent in its behavior with other similar components in the envrionment (e.g. the list view in Nautilus).
There is some relevant material in the GNOME standards for keyboard accessibility.
The rules are identical to the Windows ones, listed above, with these exceptions:
NOTE: The first three illustrations are of an actual use of a component like this in GNOME. In this case, whole rows are selected, and because no individual cells are ediable, the keyboard focus spans the whole row. It's also interesting to note the notable differences in sizes of text and widgets compared to Windows.
This image demonstrates a multiple selection, and the keyboard focus on the fifth row.
This demonstrates the same list, but with the keyboard focus moved out of the selection:
This demonstrates the same list when some other component has the focus. Unsurprisingly, the keyboard focus is not shown at all.
This demonstrates the keyboard focus existing in a single cell, which should be used any time there are editable cells. Note that this behavior does not exist "natively" in GNOME, but is provided to support the cross-platform accessibility requirements for column reordering and sizing. This is a simple extrapolation from the above patterns:
The Macintosh has a significantly different set of gestures for selecting rows.
On a Selected Row | On a Non-Selected Row | On Background | |
---|---|---|---|
Left Click | Selected: Clicked row (on mouseDown) Deselected: All others (on mouseDown) Anchor: Clicked row | Selected: None Deselected: All (on mouseDown) Anchor: First row | |
Shift Left Click | Selected: Rows between the anchor and the clicked row (inclusive) (on mouseDown). Deselected: None Anchor: Clicked row | ||
Command Left Click | Selected: None Deselected: Clicked row (on mouseDown) Anchor: No change | Selected: Clicked row (on mouseDown) Deselected: None Anchor: Clicked row | |
Command-Shift Left Click | Same as Command Left Click | ||
Arrow up/down | Selected: Row above/below the first/last selected row in the list Deselected: All others Anchor: Row that received the selection | n/a | |
Shift Arrow up/down | Selected: Rows between the last/first selected row and the first/last row above/below the selected row (or, if the first/last row, then the that row) (inclusive) Deselected: none Anchor: No change | ||
Command Arrow up/down | Same as Arrow up/down | ||
Command-Shift Arrow up/down | Same as Arrow up/down |
Appearance:
This image demonstrates a multiple selection.
This demonstrates the same list when some other component has the focus.
This demonstrates the keyboard focus existing in a single cell, which should be used any time there are editable cells. This is a mockup.
An application should persist the selection in primary windows across runs of the application.
Date | Details |
---|---|
2005-May-4 | Initial revision posted to https://swingx.dev.java.net/documentation/treetable/index.html |