How to Write a Tree-Will-Expand Listener

How to Write a Tree-Will-Expand Listener

As explained in How to Write a Tree Expansion Listener (page 710), you can use a tree-will-expand listener to prevent a tree node from expanding or collapsing. To be notified just after an expansion or collapse occurs, you should use a tree expansion listener instead.

TreeExpandEventDemo2 , shown in Figure 14, adds a tree-will-expand listener to the TreeExpandEventDemo example. The new code demonstrates the ability of tree-will-expand listeners to veto node expansions and collapses: It asks for confirmation each time you try to expand a node.

Figure 14. The TreeExpandEventDemo2 application.

Try This:

1. 

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

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

2. Click the graphic to the left of the Potrero Hill node. This tells the tree you want to expand the node. A dialog appears asking you if you really want to expand the node.

3. Click "Expand" or dismiss the dialog. Messages in the text area tell you that both a tree-will-expand event and a tree-expanded event have occurred. At the end of each message is the path to the expanded node.

4. Try to expand another node, but this time press the Cancel Expansion button in the dialog. The node does not expand. Messages in the text area tell you that a tree-will-expand event occurred, and that you cancelled a tree expansion.

5. Collapse the Potrero Hill node. The node collapses without a dialog appearing because the event handler's treeWillCollapse method lets the collapse occur uncontested.

The following snippet shows the code that this program adds to TreeExpandEventDemo . The bold line prevents the tree expansion from happening. You can find all the demo's source code in TreeExpandEventDemo2.java .

 public class TreeExpandEventDemo2 ... {     ...     class DemoArea ... implements ... TreeWillExpandListener {         ...         public DemoArea() {             ...             tree.addTreeWillExpandListener(this);             ...         }         ...         //Required by TreeWillExpandListener interface.         public void treeWillExpand(TreeExpansionEvent e)                     throws ExpandVetoException {             saySomething("Tree-will-expand event detected", e);  //...show a dialog...  if (/* user said to cancel the expansion */) {                 //Cancel expansion.                 saySomething("Tree expansion cancelled", e);  throw new ExpandVetoException(e);  }         }         //Required by TreeWillExpandListener interface.         public void treeWillCollapse(TreeExpansionEvent e) {             saySomething("Tree-will-collapse event detected", e);         }         ...     } } 

The Tree-Will-Expand Listener API

Table 41 lists the methods in the TreeWillExpandListener interface. Note that this interface has no adapter class. Also refer to the TreeWillExpandListener API documentation online at: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/event/TreeWillExpandListener.html.

Table 41. The TreeWillExpandListener Interface

Method	Purpose
treeWillCollapse(TreeExpansionEvent)	Called just before a tree node collapses. To prevent the collapse from occurring, your implementation of this method should throw a ExpandVetoException event.
treeWillExpand(TreeExpansionEvent)	Called just before a tree node expands. To prevent the expansion from occurring, your implementation of this method should throw a ExpandVetoException event.

See Table 36, "The TreeExpansionEvent API," on page 712 for information about the TreeExpansionEvent argument for the preceding methods.

Examples That Use Tree-Will-Expand Listeners

The following examples use tree-will-expand listeners.

Example	Where Described	Notes
TreeExpandEventDemo2	This section	Displays a confirmation dialog whenever a tree expansion event occurs.