The JavaTM Tutorial
Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search

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(in the Creating a User Interface trail) 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.

Click this figure to run the applet.
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(in the API reference documentation) 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(in the API reference documentation) 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(in the API reference documentation) event.
See The Tree Expansion Event API for information about the TreeExpansionEvent(in the API reference documentation) 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.

Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search