The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: Creating a GUI with JFC/Swing
Lesson: Writing Event Listeners

## How to Write a Tree-Will-Expand Listener

> As explained in How to Write a Tree Expansion Listener, 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.

> The following applet adds a tree-will-expand listener to the `TreeExpandEventDemo` example discussed in How to Write a Tree Expansion Listener. 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.

> This is a picture of the applet's GUI. To run the applet, click the picture. The applet will appear in a new browser window.

> > Try this:
> > 1. Click the graphic to the left of the Potrero Hill node. This tells the tree that you want to expand the node.
> >    A dialog will appear asking you whether you really want to expand the node.
> > 2. 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.
> > 3. 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.
> > 4. 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 applet's source code in `TreeExpandEventDemo.2java`.

> >     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 Event API

> The `TreeWillExpandListener` interface contains two methods:
> `void 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.
> `void 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 The Tree Expansion Event API for information about the `TreeExpansionEvent` argument for the preceding methods.

### Examples that Use Tree-Will-Expand Listeners

> `TreeExpandEventDemo2`, featured in this section, is our only example that uses a tree-will-expand listener.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form