How to Write a Tree Expansion Listener

Sometimes when using a tree, ^[33] you might need to react when a branch becomes expanded or collapsed . For example, you might need to load or save data or you might need to prevent the user from expanding a particular node.

^[33] See also How to Use Trees (page 437) in Chapter 7.

Two kinds of listeners report expansion and collapse occurrences: tree expansion listeners and tree-will-expand listeners. This section discusses the former. A tree expansion listener detects when an expansion or collapse has happened . In general, you should implement a tree expansion listener unless you might need to prevent an expansion or collapse from happening.

Tree-will-expand listeners are discussed in How to Write a Tree-Will-Expand Listener (page 718). A tree-will-expand listener detects when an expansion or collapse is about to happen. Figure 13 demonstrates a simple tree expansion listener. The text area at the bottom of the window displays a message every time a tree expansion event occurs. It's a straightforward, simple demo. To see a more interesting version that can veto expansions, see How to Write a Tree-Will-Expand Listener (page 718).

Figure 13. The TreeExpandEventDemo application.

Try This:

1. 

   Run TreeExpandEventDemo using Java Web Start or compile and run the example yourself. ^[34]

   ^[34] To run TreeExpandEventDemo using Java Web Start, click the TreeExpandEventDemo link on the RunExamples/events.html page on the CD. You can find the source files here: JavaTutorial/uiswing/events/example-1dot4/index.html#TreeExpandEventDemo .

2. Expand a node. A tree-expanded event is fired .

3. Collapse the node. A tree-collapsed event is fired.

The following code shows how the program handles expansion events. You can find all the example's source code in TreeExpandEventDemo.java .

 public class TreeExpandEventDemo ... {     ...     void saySomething(String eventDescription, TreeExpansionEvent e) {         textArea.append(eventDescription + "; "                         + "path = " + e.getPath()                         + newline);     }     class DemoArea ... implements TreeExpansionListener {         ...         public DemoArea() {             ...             tree.addTreeExpansionListener(this);             ...         }         ...         // Required by TreeExpansionListener interface.         public void treeExpanded(TreeExpansionEvent e) {             saySomething("Tree-expanded event detected", e);         }         // Required by TreeExpansionListener interface.         public void treeCollapsed(TreeExpansionEvent e) {             saySomething("Tree-collapsed event detected", e);         }     } } 

The Tree Expansion Listener API

Table 35 lists the methods in the TreeExpansionListener interface and Table 36 describes the methods in the TreeExpansionEvent class. Note that TreeExpansionListener has no adapter classes. Also refer to the TreeExpansionListener API documentation online at: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/event/TreeExpansionListener.html. The TreeExpansionEvent API documentation is online at: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/event/TreeExpansionEvent.html.

Table 35. The TreeExpansionListener Interface

Method	Purpose
treeCollapsed(TreeExpansionEvent)	Called just after a tree node collapses.
treeExpanded(TreeExpansionEvent)	Called just after a tree node expands.

Table 36. The TreeExpansionEvent API

Method	Purpose
Object getSource()	Return the object that fired the event.
TreePath getPath()	Return a TreePath object that identifies each node from the root of the tree to the collapsed/expanded node, inclusive.

Examples That Use Tree Expansion Listeners

The following examples use tree expansion listeners.

Example	Where Described	Notes
TreeExpandEventDemo	This section	Displays a message whenever a tree expansion event occurs.
TreeExpandEventDemo2	How to Write a Tree-Will-Expand Listener (page 718)	Adds a tree-will-expand listener to TreeExpandEventDemo .