14 Tree/Table Components

Features of JCTreeExplorer and JCTreeTable Classes and Interfaces Properties Examples

14.1 Features of JCTreeExplorer and JCTreeTable

Swing's JTree and JTable are the two components that do more than merely display data; they attempt to manage the data as well. This becomes important when you need to organize large amounts of data and provide a view that displays a portion of it along with an indication of its relationship to the rest. Information that has a hierarchical structure, like a file system, can be displayed as tree data, while other types of data nicely fit a tabular format. There are a large number of data structures that combine tree-like and table-like properties. A file system has a hierarchical organization that begs to be represented as a tree, yet the individual directories and files have properties, such as name, size, type, and date modified, that fit nicely in a row-column organization. Obviously there is a need for a component that lets you combine the look and functionality of both a tree and a table.

JCTreeExplorer and JCTreeTable fill the need for components that have the dual characteristics of a tree and a table, and provides these functions:

Allows you to view the object as a tree, with an accompanying table. Any tree node may have tabular data associated with it.
Contains a flexible "painter" object that accommodates a Swing cell renderer or a JClass cell renderer.
Permits the construction of arbitrary data sources as treetables through its JCTreeTableModel interface. Any class can be used to supply data to the treetable, provided that it implements the JCTreeTableModel interface.
The two components have advanced column sorting functionality. Each column can have a different ordered set of columns that are to be used as secondary sort keys. When a user clicks on a column header to sort that column, any identical cells are arranged based on the sort order of the secondary key, or keys.
Cells may be edited by implementing JCCellEditor.
Folder icons can be customized by replacing the editor/renderer, or by setting a JCIconRenderer.

Since JCTreeExplorer and JCTreeTable are enhancements of Swing's JTable and JTree, it's a good idea to be familiar with those components to ease the learning curve. Need a primer on Swing's table and tree components? See the tutorial on How to Use Tables and How to Use Trees at Sun's javasoft Web site.

JCTreeExplorer presents a table for the currently selected node, while JCTreeTable shows table rows for all visible nodes. See the following figure for the different visual characteristics between the two components.

Figure 44 : Views of a JCTreeTable and a JCTreeExplorer.

JCTreeTable and JCTreeExplorer support Swing's pluggable look-and-feel. The previous figure shows the Windows look and feel, while the following two figures show the default Metal look and feel.

Figure 45 : JCTreeTable component, metal look and feel.

Figure 46 : JCTreeExplorer component, metal look and feel.

14.2 Classes and Interfaces

Interfaces for JCTreeExplorer and JCTreeTable

Interface

Description

`JCTreeIconRenderer`

In `com.klg.jclass.util.treetable,` this interface represents a class that renders a tree icon. Not a renderer in the strict definition of the word, it provides the icon to be rendered. It is not necessary to make this interface do the rendering since Icons know how to render themselves.

A default implementation of this class simply returns the plaf icon it is passed.

The purpose of this mechanism is to allow a user to override the icons being drawn in a tree without
a) having to figure out the default plaf for the icons that they do not wish to override, and
b) overriding simple data-type editors.

Its single method is `getNodeIcon`.

`JCTreeTableModel`

Model to use that combines the `TreeModel` and `TableModel` interfaces. This model allows data to be viewed as a multicolumn tree in a left-hand pane, and a table in a right-hand pane.

Note that specific implementations need to implement both `JCTreeTableModel` and `TableModel` for them to work properly.

Interface	Description
`JCTreeIconRenderer`	In `com.klg.jclass.util.treetable,` this interface represents a class that renders a tree icon. Not a renderer in the strict definition of the word, it provides the icon to be rendered. It is not necessary to make this interface do the rendering since Icons know how to render themselves. A default implementation of this class simply returns the plaf icon it is passed. The purpose of this mechanism is to allow a user to override the icons being drawn in a tree without a) having to figure out the default plaf for the icons that they do not wish to override, and b) overriding simple data-type editors. Its single method is `getNodeIcon`.
`JCTreeTableModel`	Model to use that combines the `TreeModel` and `TableModel` interfaces. This model allows data to be viewed as a multicolumn tree in a left-hand pane, and a table in a right-hand pane. Note that specific implementations need to implement both `JCTreeTableModel` and `TableModel` for them to work properly.

Here is the definition of the JCTreeTableModel interface:

public interface JCTreeTableModel {
// Returns the value of the specific node and column
public Object getValueAt(Object node, int column);
// Returns whether a particular cell is editable, given the node and column
public boolean isCellEditable(Object node, int column);
// Sets the value at a particular node and column
public void setValueAt(Object value, Object node, int column);
// The following methods map exactly onto javax.swing.table.TableModel
public void addTableModelListener(TableModelListener l);
public Class getColumnClass(int column);
public int getColumnCount();
public String getColumnName(int column);
public int getRowCount();
public Object getValueAt(int row, int column);
public boolean isCellEditable(int row, int column);
public void removeTableModelListener(TableModelListener l);
public void setValueAt(Object value, int row, int column);
// The following methods map exactly onto javax.swing.tree.TreeModel
public void addTreeModelListener(TreeModelListener l);
public Object getChild(Object parent, int index);
public int getChildCount(Object parent);
public int getIndexOfChild(Object parent, Object child);
public Object getRoot();
public boolean isLeaf(Object node);
public void removeTreeModelListener(TreeModelListener l);
public void valueForPathChanged(TreePath path, Object newValue);
}

Classes

Class

Description

`DefaultTreeTable SelectionModel`

Extends `javax.swing.tree.DefaultTreeSelectionModel` and implements `JCTreeTableSelectionModel`. Like `JCMultiSelectList`, a treetable offers different selection modes. A treetable has an associated `DefaultTreeTableSelectionModel` when it is created, but you can define your own selection model, so long as it is a subclass of `DefaultTreeSelectionModel` and implements `JCTreeTableSelectionModel`.

`TreeTableSupport`

Abstract class in `com.klg.jclass.util.treetable` that provides an implementation that handles a `TreeModel`/`TableModel` combination for use in a Table component.

Its functionality includes tracking expanded node counts, mapping and posting expansions, and selection events. It also provides a node "painter" object that can be wrapped into a Swing `CellRenderer` or a JClass `CellRenderer`.

`JCSortableTable`

A subclass of `JTable` that internally wraps any `TableModel` it is given with a `JCRowSortTableModel` and provides a `Comparator` that has an adjustable list of the column indexes that it uses for sorting. Clicking on a column header invokes the sorting behavior tied to that column; clicking again reverses the sort.

`TreeWithSortable   Children`

This class implements `JCTreeTableModel` and `JCRowSortModel`.

It constructs a `JCTreeTableModel` that wraps a given instance of a `JCTreeTableModel` and provides a sorted mapping of the children for any given leaf node. The sort order is defined by the configurable `Comparator` property.

`com.klg.jclass.   util.treetable   BranchTree`

An implementation of `TreeModel` that wraps a tree model so that it only exposes branches; that is, non-leaf nodes. This is useful for explorer-type views where the "tree view" portion only displays the branch nodes.

`DefaultTreeIcon   Renderer`

An implementation of `JCTreeIconRenderer`, its `getNodeIcon` method returns the icon to render at the right of the specified value. This simple implementation returns the plaf icon passed to it.

`JCTreeExplorer`

A subclass of `JSplitPane` that provides a tree view on the left-hand side of the split pane, and a table view on the right.

Constructor: `JCTreeExplorer(JCTreeTableModel)`

`JCTreeTable`

A subclass of `JTable` that handles listeners, rendering, editing, and painting of a component that combines tree-like and table-like properties.

Constructor: `JCTreeTable(JCTreeTableModel)`

`com.klg.jclass.   util.treetable   NodeChildrenTable`

Maps the children of a particular node in a `JCTreeTableModel` into a standard Swing `TableModel`.

Class	Description
`DefaultTreeTable SelectionModel`	Extends `javax.swing.tree.DefaultTreeSelectionModel` and implements `JCTreeTableSelectionModel`. Like `JCMultiSelectList`, a treetable offers different selection modes. A treetable has an associated `DefaultTreeTableSelectionModel` when it is created, but you can define your own selection model, so long as it is a subclass of `DefaultTreeSelectionModel` and implements `JCTreeTableSelectionModel`.
`TreeTableSupport`	Abstract class in `com.klg.jclass.util.treetable` that provides an implementation that handles a `TreeModel`/`TableModel` combination for use in a Table component. Its functionality includes tracking expanded node counts, mapping and posting expansions, and selection events. It also provides a node "painter" object that can be wrapped into a Swing `CellRenderer` or a JClass `CellRenderer`.
`JCSortableTable`	A subclass of `JTable` that internally wraps any `TableModel` it is given with a `JCRowSortTableModel` and provides a `Comparator` that has an adjustable list of the column indexes that it uses for sorting. Clicking on a column header invokes the sorting behavior tied to that column; clicking again reverses the sort.
`TreeWithSortable Children`	This class implements `JCTreeTableModel` and `JCRowSortModel`. It constructs a `JCTreeTableModel` that wraps a given instance of a `JCTreeTableModel` and provides a sorted mapping of the children for any given leaf node. The sort order is defined by the configurable `Comparator` property.
`com.klg.jclass. util.treetable BranchTree`	An implementation of `TreeModel` that wraps a tree model so that it only exposes branches; that is, non-leaf nodes. This is useful for explorer-type views where the "tree view" portion only displays the branch nodes.
`DefaultTreeIcon Renderer`	An implementation of `JCTreeIconRenderer`, its `getNodeIcon` method returns the icon to render at the right of the specified value. This simple implementation returns the plaf icon passed to it.
`JCTreeExplorer`	A subclass of `JSplitPane` that provides a tree view on the left-hand side of the split pane, and a table view on the right. Constructor: `JCTreeExplorer(JCTreeTableModel)`
`JCTreeTable`	A subclass of `JTable` that handles listeners, rendering, editing, and painting of a component that combines tree-like and table-like properties. Constructor: `JCTreeTable(JCTreeTableModel)`
`com.klg.jclass. util.treetable NodeChildrenTable`	Maps the children of a particular node in a `JCTreeTableModel` into a standard Swing `TableModel`.

Providing your own sorting mechanism

If you need to provide your own sorting algorithm, one way is to subclass JCRowComparator and pass a comparator of the new type to TreeWithSortableChildren.

14.3 Properties

For a complete list of properties, please see Properties of JCTreeExplorer and Properties of JCTreeTable in Appendix A.

Properties of JCTreeExplorer

`getTree()`

Returns the `JTree` component used.

`getTable()`

Returns the `JTable` component used.

`setKeyColumns()`

Sets which columns are to be used as primary and secondary sort keys. It takes a column number (0, 1, 2 ...) as its first parameter, and an array of column numbers as its second parameter.

Example: `setKeyColumns(0, {1, 0})` specifies that when the user clicks on the header in the first column, sorting takes place based on the second column, and identical entries in the second column are sorted based on the ordering implied by the first column. This is a useful sort key for directories, where the first column is the file or directory name, and the second column contains the object's size. Because directories have size zero, they are sorted at the top and then arranged alphabetically.

`getTree()`	Returns the `JTree` component used.
`getTable()`	Returns the `JTable` component used.
`setKeyColumns()`	Sets which columns are to be used as primary and secondary sort keys. It takes a column number (0, 1, 2 ...) as its first parameter, and an array of column numbers as its second parameter. Example: `setKeyColumns(0, {1, 0})` specifies that when the user clicks on the header in the first column, sorting takes place based on the second column, and identical entries in the second column are sorted based on the ordering implied by the first column. This is a useful sort key for directories, where the first column is the file or directory name, and the second column contains the object's size. Because directories have size zero, they are sorted at the top and then arranged alphabetically.

Properties of JCTreeTable

`treeTableModel`

The `treeTableModel` is the interface for the data.

`treeIconRenderer`

Gets or sets the icon renderer. If this property is set to null, no icon will be shown.

`rootVisible`

You can show the root node or not, depending on the setting of this Boolean property. The accessor method is called `isRootVisible`.

`showsRootHandles`

Determines whether the node handles are to be displayed.

`treeTableModel`	The `treeTableModel` is the interface for the data.
`treeIconRenderer`	Gets or sets the icon renderer. If this property is set to null, no icon will be shown.
`rootVisible`	You can show the root node or not, depending on the setting of this Boolean property. The accessor method is called `isRootVisible`.
`showsRootHandles`	Determines whether the node handles are to be displayed.

14.4 Methods

JCTreeExplorer Methods

`getSelectionPath()`

Returns the `javax.swing.tree.TreePath` of the first selected row inside the table view.

`getSelectionPaths()`

Returns the `javax.swing.tree.TreePath` of the first selected row inside the table view.

`getTable()`

Returns the `JTable` component used.

`getTree()`

Returns the `JTree` component used

`getTreeIconRenderer()`

Returns the icon renderer being used.

`setTreeIconRenderer()`

Sets the icon renderer.

`setUI()`

Sets the `javax.swing.plaf.TableUI` UI.

`getSelectionPath()`	Returns the `javax.swing.tree.TreePath` of the first selected row inside the table view.
`getSelectionPaths()`	Returns the `javax.swing.tree.TreePath` of the first selected row inside the table view.
`getTable()`	Returns the `JTable` component used.
`getTree()`	Returns the `JTree` component used
`getTreeIconRenderer()`	Returns the icon renderer being used.
`setTreeIconRenderer()`	Sets the icon renderer.
`setUI()`	Sets the `javax.swing.plaf.TableUI` UI.

JCTreeTable Methods

`addSelectionPath()`

Adds the node identified by the specified `TreePath` to the current selection.

`addSelectionPaths()`

Adds each path in the array of paths to the current selection.

`addTableHeader MouseListener()`

Adds a `MouseListener` to the table header.

`addTreeExpansion   Listener()`

Adds a listener for `TreeExpansion` events.

`addTreeWillExpand   Listener()`

Adds a listener for `TreeWillExpand` events.

`collapsePath()`

Ensures that the node identified by the specified path is collapsed and viewable.

`collapseRow()`

Ensures that the node in the specified row is collapsed.

`createSortable   TableColumn()`

Creates a `TableColumn`.

`expandPath()`

Ensures that the node identified by the specified path is expanded and viewable.

`expandRow()`

Ensures that the node in the specified row is expanded and viewable.

`getCellEditor()`

Overridden to return the appropriate data render for the first column if the treetable is in tree display mode.

`getCellRenderer()`

Overridden to return the appropriate data render for the first column if the treetable is in tree display mode.

`getClosestPath    ForLocation()`

Returns the row to the node that is closest to X,Y.

`getEditingPath()`

Returns the path to the element that is currently being edited.

`getExpandedDescendants()`

Returns an `Enumeration` of the descendants of path that are currently expanded.

`getPathForLocation()`

Returns the path for the node at the specified location.

`getPathForRow()`

Returns the path that is displayed at the table row specified.

`getRowForLocation()`

Returns the row for the specified location.

`getRowForPath()`

Returns the row that displays the node identified by the specified path.

`getRowsForPaths()`

Returns the rows for the visible specified paths.

`getScrollsOnExpand()`

Returns `true` if the tree scrolls to show previously hidden children.

`getSelectedPath()`

Returns the `TreePath` of the first selected row.

`getSelectionPath()`

Returns the path to the first selected node.

`getSelectionPaths()`

Returns the paths of all selected values.

`getShowNodeLines()`

Returns the state of `ShowNodeLines`. If true, the connecting lines that are drawn between nodes in an explorer view are shown.

`getShowsRootHandles()`

Returns `true` if handles for the root nodes are displayed.

`getTreeIconRenderer()`

Returns the icon renderer being used.

`getTreeSelectionModel()`

Returns the model for selections.

`getTreeTableModel()`

Returns the `JCTreeTableModel` that is providing the data.

`getView()`

Returns the current view.

`isPathSelected()`

Returns true if the item identified by the path is currently selected.

`isRootVisible()`

Returns true if the root node of the tree is displayed.

`isSortable()`

Is the treetable sortable? Returns the value of the `sortable` property.

`makeVisible()`

Ensures that the node identified by a path is currently viewable.

`removeTreeExpansion   Listener()`

Removes a listener for `TreeExpansion` events.

`removeTreeWillExpand   Listener()`

Removes a listener for `TreeWillExpand` events.

`setRootVisible()`

Determines whether or not the root node from the `TreeModel` is visible.

`setScrollsOnExpand()`

Determines the behavior of a node when it is expanded. If `true`, the viewport will scroll to show as many descendants as possible when the node is expanded; if `false`, the viewport will not scroll.

`setSelectionPath()`

Selects the node identified by the specified path.

`setSelectionPaths()`

Selects the specified paths.

`setShowNodeLines()`

Allows you override the plaf-specified behavior for drawing lines.

`setShowsRootHandles()`

Determines whether the node handles are to be displayed.

`setSortable()`

Sets whether the treetable is sortable.

`setSwitchPolicy()`

Sets the `switchPolicy` variable that determines whether or not to allow view switching Options are: `JCTreeTable.SWITCH_BUTTON_DONT_SHOW`,

`JCTreeTable.SWITCH_VIEW_NEVER`, `JCTreeTable.SWITCH_VIEW_TO_TABLE_ON_SORT`, `JCTreeTable.SWITCH_VIEW_ON_ICON_ONLY`.

`setTreeIconRenderer()`

Sets the icon renderer.

`setTreeTableModel()`

Sets the `TreeModel` that will provide the data.

`setTreeTable   SelectionModel()`

Sets the tree's selection model.

`setUI()`

Sets the `javax.swing.plaf.TableUI` UI.

`setView()`

Sets whether the view is for a tree or a table.

`updateUI()`

Updates the UI.

`addSelectionPath()`	Adds the node identified by the specified `TreePath` to the current selection.
`addSelectionPaths()`	Adds each path in the array of paths to the current selection.
`addTableHeader MouseListener()`	Adds a `MouseListener` to the table header.
`addTreeExpansion Listener()`	Adds a listener for `TreeExpansion` events.
`addTreeWillExpand Listener()`	Adds a listener for `TreeWillExpand` events.
`collapsePath()`	Ensures that the node identified by the specified path is collapsed and viewable.
`collapseRow()`	Ensures that the node in the specified row is collapsed.
`createSortable TableColumn()`	Creates a `TableColumn`.
`expandPath()`	Ensures that the node identified by the specified path is expanded and viewable.
`expandRow()`	Ensures that the node in the specified row is expanded and viewable.
`getCellEditor()`	Overridden to return the appropriate data render for the first column if the treetable is in tree display mode.
`getCellRenderer()`	Overridden to return the appropriate data render for the first column if the treetable is in tree display mode.
`getClosestPath ForLocation()`	Returns the row to the node that is closest to X,Y.
`getEditingPath()`	Returns the path to the element that is currently being edited.
`getExpandedDescendants()`	Returns an `Enumeration` of the descendants of path that are currently expanded.
`getPathForLocation()`	Returns the path for the node at the specified location.
`getPathForRow()`	Returns the path that is displayed at the table row specified.
`getRowForLocation()`	Returns the row for the specified location.
`getRowForPath()`	Returns the row that displays the node identified by the specified path.
`getRowsForPaths()`	Returns the rows for the visible specified paths.
`getScrollsOnExpand()`	Returns `true` if the tree scrolls to show previously hidden children.
`getSelectedPath()`	Returns the `TreePath` of the first selected row.
`getSelectionPath()`	Returns the path to the first selected node.
`getSelectionPaths()`	Returns the paths of all selected values.
`getShowNodeLines()`	Returns the state of `ShowNodeLines`. If true, the connecting lines that are drawn between nodes in an explorer view are shown.
`getShowsRootHandles()`	Returns `true` if handles for the root nodes are displayed.
`getTreeIconRenderer()`	Returns the icon renderer being used.
`getTreeSelectionModel()`	Returns the model for selections.
`getTreeTableModel()`	Returns the `JCTreeTableModel` that is providing the data.
`getView()`	Returns the current view.
`isPathSelected()`	Returns true if the item identified by the path is currently selected.
`isRootVisible()`	Returns true if the root node of the tree is displayed.
`isSortable()`	Is the treetable sortable? Returns the value of the `sortable` property.
`makeVisible()`	Ensures that the node identified by a path is currently viewable.
`removeTreeExpansion Listener()`	Removes a listener for `TreeExpansion` events.
`removeTreeWillExpand Listener()`	Removes a listener for `TreeWillExpand` events.
`setRootVisible()`	Determines whether or not the root node from the `TreeModel` is visible.
`setScrollsOnExpand()`	Determines the behavior of a node when it is expanded. If `true`, the viewport will scroll to show as many descendants as possible when the node is expanded; if `false`, the viewport will not scroll.
`setSelectionPath()`	Selects the node identified by the specified path.
`setSelectionPaths()`	Selects the specified paths.
`setShowNodeLines()`	Allows you override the plaf-specified behavior for drawing lines.
`setShowsRootHandles()`	Determines whether the node handles are to be displayed.
`setSortable()`	Sets whether the treetable is sortable.
`setSwitchPolicy()`	Sets the `switchPolicy` variable that determines whether or not to allow view switching Options are: `JCTreeTable.SWITCH_BUTTON_DONT_SHOW`, `JCTreeTable.SWITCH_VIEW_NEVER`, `JCTreeTable.SWITCH_VIEW_TO_TABLE_ON_SORT`, `JCTreeTable.SWITCH_VIEW_ON_ICON_ONLY`.
`setTreeIconRenderer()`	Sets the icon renderer.
`setTreeTableModel()`	Sets the `TreeModel` that will provide the data.
`setTreeTable SelectionModel()`	Sets the tree's selection model.
`setUI()`	Sets the `javax.swing.plaf.TableUI` UI.
`setView()`	Sets whether the view is for a tree or a table.
`updateUI()`	Updates the UI.

14.5 Examples

Implementing a custom node icon for a JCTreeTable

Your application may require that you supply your own custom node icon for the tree view. Create your own implementation of JCTreeIconRenderer, and write a method similar to the one whose signature is shown here:

public Icon getNodeIcon(TreeModel treemodel,
Object node,
Object value,
Class object_class,
boolean is_leaf,
boolean is_expanded,
Icon plaf_icon)

You may want to have two icons, one for nodes with children and one for leaf elements. In that case, use the boolean parameter is_leaf to choose which icon will be used.

The method should return the Icon you want to use. Pass your implementation of JCTreeIconRenderer to your instance of a JCTreeTable using setTreeIconRenderer(JCTreeIconRenderer renderer).

Please see TreeExplorer.java and TreeTable.java in the JCLASS_HOME\examples\elements\ directory for some examples of using both JCTreeExplorer and JCTreeTable.