17.5 Tree Selections

After the tree is built and looks the way you want it to, you need to start working with selections so it does something useful. The JTree class introduced many of the selection manipulation methods already, but let's take a closer look at the model for selecting paths in a tree and the DefaultSelectionModel provided in the javax.swing.tree package. If you're comfortable with selection models, you probably won't find anything surprising here and may want to skip to Section 17.7.

Selections are based on rows or paths. It's important to realize the distinction between a "row" and a "path" for trees. A path contains the list of nodes from the root of the tree to another node. Paths exist regardless of whether or not you plan to display the tree.

Rows, however, are completely dependent on the graphical display of a tree. The easiest way to think about a row is to think of the tree as a JList object. Each item in the list is a row on the tree. That row corresponds to some particular path. As you expand and collapse folders, the number of rows associated with the tree changes. It's the RowMapper object's job to relate a row number to the correct path.

Depending on your application, you may find rows or paths more efficient. If your program deals mostly with the user object data, paths are a good choice. If you're working with the graphical interface (automatically expanding folders and the like), rows may be more useful.

17.5.1 The RowMapper Interface

Tree selections make extensive use of the RowMapper interface. (In the absence of a RowMapper, you simply cannot retrieve information on rows in the tree from classes like TreeSelectionModel. TreePath information is still available, and the tree, its model, and the selection model will all continue to work just fine.) It is a simple interface with one method:

public int[] getRowsForPaths(TreePath paths[])

The UI for your tree should implement this to return a list of row indices matching the supplied paths. If any of the paths are null or not visible, -1 should be placed in the return int array. While this may seem like an obvious task, you must account for the expanded or collapsed state of the nodes in the tree; remember that there's no such thing as a collapsed row. This is one reason why the JTree class cannot simply use a ListSelectionModel.

17.5.2 The TreeSelectionModel Interface

Now for the heart of selections. The TreeSelectionModel interface determines what a tree selection can look like.

17.5.2.1 Properties

TreeSelectionModel contains the properties listed in Table 17-11. The selection model properties deal primarily with the current selection on the tree. The notion of a "lead" selection stems from the fact that a selection can happen as a process, not only as a single event. The lead selection is the most recently added cell in the selection. It might be the only path selected, but it might also be the most recent selection out of several in a range or discontiguous group of selections. If the selection contains more than one path, the getSelectionPath( ) method returns the first selection in the path, which may or may not be the same thing as getLeadSelectionPath( ). It's also good to remember that, if it has children, selecting a "folder" node in a tree does not imply selecting all the nodes underneath it.

Having said that, the rest of the properties are fairly self-explanatory. minSelectionRow and maxSelectionRow let you get the smallest and largest selected row numbers. rowMapper holds a utility that manages the mapping between paths and row numbers. selectionPaths and selectionRows let you access the rows or paths currently selected. selectionCount tells you the number of rows selected.

Table 17-11. TreeSelectionModel properties

Property	Data type	get	is	set	Default value
leadSelectionPath	TreePath	·
leadSelectionRow	int	·
maxSelectionRow	int	·
minSelectionRow	int	·
rowMapper	RowMapper	·		·
rowSelected	boolean		·
selectionCount	int	·
selectionMode	int	·		·
selectionPath	TreePath	·		·
selectionPaths	TreePath[]	·		·
selectionRows	int[]	·
selectionEmpty	boolean		·

17.5.2.2 Constants

The value of the selectionMode property must be one of the constants listed in Table 17-12 and defined in the TreeSelectionModel interface.

Table 17-12. TreeSelectionModel constants

Constant	Type	Description
SINGLE_TREE_SELECTION	int	Allows only one path in the tree to be selected at any one time. Choosing a new path deselects the previous choice.
CONTIGUOUS_TREE_SELECTION	int	Allows several paths to be selected; they must be in a continuous block. The block ranges from the minSelectionRow to the maxSelectionRow.
DISCONTIGUOUS_TREE_SELECTION	int	Allows several paths to be selected; they can be any set of nodes, contiguous or otherwise.

17.5.2.3 Events

The TreeSelectionModel requires classes that implement the model to implement methods for registering listeners for property change events and tree selection events. TreeSelectionEvent is discussed in greater detail in Section 17.6 later in this chapter.

public void addPropertyChangeListener(PropertyChangeListener l)

public void removePropertyChangeListener(PropertyChangeListener l)

Add or remove listeners interested in receiving property change events.

public void addTreeSelectionListener(TreeSelectionListener l)

public void removeTreeSelectionListener(TreeSelectionListener l)

Add or remove listeners interested in receiving tree selection events. These methods differ from the JTree methods for adding or removing listeners, in that the event source sent to these listeners is the selection model, whereas the event source sent to the JTree selection listeners is the tree itself.

17.5.2.4 Selection methods

Many of these methods will look familiar if you read through the section on the JTree class. A tree passes along many of the selection calls to the selection model that supports it so that you can deal primarily with the tree itself.

public void addSelectionPath(TreePath path)

public void addSelectionPaths(TreePath paths[])

Augment the current selection with the supplied path or paths.

public void clearSelection( )

Clear the current selection, leaving the selection empty. If nothing is selected before calling clearSelection( ), this method should have no effect.

public boolean isPathSelected(TreePath path)

public boolean isRowSelected(int row)

Return true if the path or row specified is in the current selection.

public void removeSelectionPath(TreePath path)

public void removeSelectionPaths(TreePath paths[]))

Remove the listed path or paths from the current selection. Any selected paths not specified remain selected.

public void resetRowSelection( )

Update the set of currently selected rows. This would be done if the row mapper changes, for example.

17.5.3 The DefaultTreeSelectionModel Class

Swing provides a default implementation of the tree selection model that supports all three modes of selection. You can see this model in use in the example earlier in this chapter.

17.5.3.1 Properties

The DefaultTreeSelectionModel inherits its properties from the TreeSelectionModel interface and supplies the default values listed in Table 17-13.

Table 17-13. DefaultTreeSelectionModel properties

Property	Data type	get	is	set	Default value
leadSelectionPatho	TreePath	·			null
leadSelectionRowo	int	·			-1
maxSelectionRowo	int	·			-1
minSelectionRowo	int	·			-1
propertyChangeListeners1.4	PropertyChangeListener[]	·			Empty array
rowMappero	RowMapper	·		·	null
rowSelectedo	boolean		·		false
selectionCounto	int	·			0
selectionModeb,o	int	·		·	DISCONTIGUOUS_TREE_SELECTION
selectionPatho	TreePath	·		·	null
selectionPathso	TreePath[]	·		·	null
selectionRowso	int[]	·			null
selectionEmptyo	boolean		·		true
treeSelectionListeners1.4	TreeSelectionListener[]	·			Empty array
1.4since 1.4, bbound, ooverridden

17.5.3.2 Events

The DefaultTreeSelectionModel supports the same property change and tree selection events as the TreeSelectionModel interface:

public void addPropertyChangeListener(PropertyChangeListener l)

public void removePropertyChangeListener(PropertyChangeListener l)

Add or remove listeners interested in receiving property change events.

public void addTreeSelectionListener(TreeSelectionListener l)

public void removeTreeSelectionListener(TreeSelectionListener l)

Add or remove listeners interested in receiving tree selection events. These events come from the DefaultTreeSelectionModel rather than JTree itself.

protected void fireValueChanged(TreeSelectionEvent event)

Notify all registered TreeSelectionListener objects associated with this selection that the selection has changed.

17.5.3.3 Constant

The DefaultTreeSelectionModel contains one constant, as shown in Table 17-14.

Table 17-14. DefaultTreeSelectionModel constant

Constant	Type	Description
SELECTION_MODE_PROPERTY	String	The name of the selection mode property used in property change events

17.5.3.4 Constructor

public DefaultTreeSelectionModel( )

Create an instance of the default selection model with all properties initialized to the default values listed in Table 17-13.