ca.odell.glazedlists.swing
Class TreeTableSupport

java.lang.Object
  ca.odell.glazedlists.swing.TreeTableSupport

public final class TreeTableSupport
extends Object

This class install(javax.swing.JTable, ca.odell.glazedlists.TreeList, int)s 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(javax.swing.JTable, ca.odell.glazedlists.TreeList, int).

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(javax.swing.JTable, ca.odell.glazedlists.TreeList, int) 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(javax.swing.table.TableCellRenderer).
• 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(javax.swing.table.TableCellEditor).
• 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(javax.swing.JTable, ca.odell.glazedlists.TreeList, int) 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(boolean) 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:

• Does node N currently have children? If it does, the expander button must be displayed.

  e.g.: A directory in a file system that contains files and/or subdirectories.

• If node N does not currently have children, is it capable of having children in the future? If it is not, then it is a true leaf node and the expander button must not be displayed.

  e.g.: A file in a file system.

• If node N currently has no children but is capable of having children in the future, should it be rendered with an expander now? Both yes and no are valid choices and thus the decision is left to the API user. The preference for this situation can be controlled using setShowExpanderForEmptyParent(boolean).
  e.g.: Empty directories in Mac OS X Finder are displayed with visible expanders while Windows Explorer does not display them.

Author:

James Lemieux

Method Summary

boolean	getArrowKeyExpansionEnabled() Returns true if the left and right arrow keys are currently used to control the tree hierarchy expansion; false if they are used to control the table's cell focus.
TableCellEditor	getDelegateEditor() Returns the editor responsible for editing the data associated with each tree node in the hierarchy column.
TableCellRenderer	getDelegateRenderer() Returns the renderer responsible for rendering the data associated with each tree node in the hierarchy column.
TreeTableCellEditor	getEditor() Returns the treeTableCellEditor used to render the hierarchy column of the tree table.
TreeTableCellRenderer	getRenderer() Returns the treeTableCellRenderer used to render the hierarchy column of the tree table.
boolean	getShowExpanderForEmptyParent() Returns true if empty tree nodes that are allowed to have children are displayed with visible expanders while they are empty; false otherwise.
boolean	getSpaceKeyExpansionEnabled() Returns true if the space key is currently used to control the table hierachy expansion, false otherwise
static TreeTableSupport	install(JTable table, TreeList treeList, int modelColumnIndex) Installs support for a hierarchical table column into the table on the column with the given hierarchyColumnModelIndex.
void	setArrowKeyExpansionEnabled(boolean arrowKeyExpansionEnabled) If arrowKeyExpansionEnabled is true then two things are changed in tandem: The left and right arrow keys will toggle the expansion state of hierarchy nodes in the tree rather than adjust cell focus in the table.
void	setDelegateEditor(TableCellEditor editor) Use the given editor as the new delegate editor of the TreeTableCellEditor which is responsible for editing the data associated with each tree node in the hierarchy column.
void	setDelegateRenderer(TableCellRenderer renderer) Use the given renderer as the new delegate renderer of the TreeTableCellRenderer which is responsible for rendering the data associated with each tree node in the hierarchy column.
void	setEditor(TreeTableCellEditor treeTableCellEditor) Use the given treeTableCellEditor when editing the hierarchy column of the tree table.
void	setRenderer(TreeTableCellRenderer treeTableCellRenderer) Use the given treeTableCellRenderer when rendering the hierarchy column of the tree table.
void	setShowExpanderForEmptyParent(boolean showExpanderForEmptyParent) Sets whether the expander is displayed for nodes that do not contain children but are allowed to contain children, and thus may accumulate children in the future.
void	setSpaceKeyExpansionEnabled(boolean spaceKeyExpansionEnabled) If spaceKeyExpansionEnabled is true, then control of the table hierachy expansion via the space key is enabled.
void	uninstall() Removes treetable support from the JTable it was installed on.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

install

public static TreeTableSupport install(JTable table,
                                       TreeList treeList,
                                       int modelColumnIndex)

Installs support for a hierarchical table column into the table on the column with the given hierarchyColumnModelIndex. The data returned by the TableModel for the hierarchical column will remain unchanged. But, the renderer and editor will be wrapped with instances of TreeTableCellRenderer and TreeTableCellEditor which take care of displaying the hierarchical information (namely the whitespace indenting and expand/collapse button).

The following must be true in order to successfully install TreeTableSupport on a JTable:

• the hierarchyColumnModelIndex must correspond to a valid view column index

Parameters:

table - the table to convert into a tree table

treeList - The TreeList capable of answering hierarchical questions for the hierachical TableColumn's renderer and editor

modelColumnIndex - the model index of the hierarchical column

Returns:

an instance of the support class providing treetable behaviour

Throws:

IllegalStateException - if this method is called from any Thread other than the Swing Event Dispatch Thread

uninstall

public void uninstall()

Removes treetable support from the JTable it was installed on. This method is useful when the TreeList of items that backs the JTable must outlive the JTable itself. Calling this method will return the hierarchical column to its original state before treetable support was installed, and it will be available for garbage collection independently of the TreeList of items.

Throws:

IllegalStateException - if this method is called from any Thread other than the Swing Event Dispatch Thread

setShowExpanderForEmptyParent

public void setShowExpanderForEmptyParent(boolean showExpanderForEmptyParent)

Sets whether the expander is displayed for nodes that do not contain children but are allowed to contain children, and thus may accumulate children in the future. If this property is true then empty nodes that may contain children in the future are displayed with a visible expander; otherwise they are displayed without the expander. A node signals that it may contain children in the future by returning true from TreeList.Format#allowsChildren(Object).

getShowExpanderForEmptyParent

public boolean getShowExpanderForEmptyParent()

Returns true if empty tree nodes that are allowed to have children are displayed with visible expanders while they are empty; false otherwise.

setArrowKeyExpansionEnabled

public void setArrowKeyExpansionEnabled(boolean arrowKeyExpansionEnabled)

If arrowKeyExpansionEnabled is true then two things are changed in tandem:

• The left and right arrow keys will toggle the expansion state of hierarchy nodes in the tree rather than adjust cell focus in the table.
• The table column model's selection model is replaced with a no-op implementation so that column selection and column lead/anchor indexes are NOT tracked. Thus, column selection is disabled and there is no cell focus adjusted when the left and right arrow keys are used.

If arrowKeyExpansionEnabled is false then the behaviour is reverted to default. That is, left and right arrow keys adjust cell focus in the table and not expansion, and the original column selection model is reinstalled.

getArrowKeyExpansionEnabled

public boolean getArrowKeyExpansionEnabled()

Returns true if the left and right arrow keys are currently used to control the tree hierarchy expansion; false if they are used to control the table's cell focus.

getSpaceKeyExpansionEnabled

public boolean getSpaceKeyExpansionEnabled()

Returns true if the space key is currently used to control the table hierachy expansion, false otherwise

setSpaceKeyExpansionEnabled

public void setSpaceKeyExpansionEnabled(boolean spaceKeyExpansionEnabled)

If spaceKeyExpansionEnabled is true, then control of the table hierachy expansion via the space key is enabled. If false, the space key will not control the table hierachie expansion.

setRenderer

public void setRenderer(TreeTableCellRenderer treeTableCellRenderer)

Use the given treeTableCellRenderer when rendering the hierarchy column of the tree table.

getRenderer

public TreeTableCellRenderer getRenderer()

Returns the treeTableCellRenderer used to render the hierarchy column of the tree table.

setDelegateRenderer

public void setDelegateRenderer(TableCellRenderer renderer)

Use the given renderer as the new delegate renderer of the TreeTableCellRenderer which is responsible for rendering the data associated with each tree node in the hierarchy column.

getDelegateRenderer

public TableCellRenderer getDelegateRenderer()

Returns the renderer responsible for rendering the data associated with each tree node in the hierarchy column.

setEditor

public void setEditor(TreeTableCellEditor treeTableCellEditor)

Use the given treeTableCellEditor when editing the hierarchy column of the tree table.

getEditor

public TreeTableCellEditor getEditor()

Returns the treeTableCellEditor used to render the hierarchy column of the tree table.

setDelegateEditor

public void setDelegateEditor(TableCellEditor editor)

Use the given editor as the new delegate editor of the TreeTableCellEditor which is responsible for editing the data associated with each tree node in the hierarchy column.

getDelegateEditor

public TableCellEditor getDelegateEditor()

Returns the editor responsible for editing the data associated with each tree node in the hierarchy column.