This class
#installs support for a single hierarchical column within
a standard
JTable that is backed by an
AdvancedTableModel. The
AdvancedTableModel, in turn
must be backed by the same
TreeList which is given as a parameter to
#install.
Typical usage of
TreeTableSupport resembles this:
// create an EventList of data
EventList myEventList = ...
// create a TreeList which uses a TreeFormat object to infer a hierarchy for each element in myEventList
TreeList treeList = new TreeList(myEventList, new MyTreeFormat());
// create a JTable that displays the contents of treeList in a tabular format
AdvancedTableModel myTableModel = GlazedListsSwing.eventTableModel(treeList, new MyTableFormat());
JTable myTable = new JTable(myTableModel);
// make the 3rd table column a hierarchical column to create a TreeTable
TreeTableSupport.install(myTable, treeList, 2);
In order to achieve all of the treetable behaviours, the following occurs
when
#install is called:
- a
TreeTableCellRenderer will be installed on the hierarchical
TableColumn. It wraps any
TableCellRenderer previously
installed on the
TableColumn, or if none was present, a
DefaultTableCellRenderer. The delegate renderer can be changed at any
time using
#setDelegateRenderer.
- a
TreeTableCellEditor will be installed on the hierarchical
TableColumn. It wraps any
TableCellEditor previously
installed on the
TableColumn, or if none was present, a
DefaultCellEditor. The delegate editor can be changed at any
time using
#setDelegateEditor.
- the UI Delegate's MouseListener will be decorated with extra
functionality that detects clicks overtop of the expand/collapse icon
and reacts accordingly by expanding/collapsing the hierarchy. In these
cases the normal mechanism for handling clicks over the table is
circumvented and thus cell edits and/or row selection changes are not
honoured.
Customizing TreeTableSupport
After installing the basic TreeTableSupport, its specific behaviour can
be refined by setting properties on the instance of TreeTableSupport
returned by the
#install method. Below are descriptions of some of
the available customizations.
Left & Right Arrow Keys
Within a treetable there is ambiguity about the functions performed by
the left and right arrow keys. Tables normally use them to advance cell
focus to the left or right while trees commonly use them to expand or
collapse hierarchies. What behaviour is desirable for any given treetable?
By default, TreeTableSupport assumes the table-style behaviour but that
can be adjusted to the tree-style behaviour calling
#setArrowKeyExpansionEnabled with an argument of true.
Generally speaking, tree-style behaviour is preferrable when the treetable
is readonly.
Space Key
As a default, TreeTableSupport enables the space key to toggle expand/collapse
of the table hierachy of the currently selected node. This behaviour can be adjusted
by calling
#setSpaceKeyExpansionEnabled(boolean) with an argument of false
.
In this case, the space key will not be used to control expand and collapse
of the table hierachy.
Displaying Expander Buttons
TreeList draws a distinction between three unique situations
regarding the display of the expander button for a given tree node, N: