buoy.widget

Class BTree


public class BTree
extends Widget

A BTree is a Widget that displays a hierarchical list of objects (or "nodes"). The user can collapse or expand particular nodes to hide or show their child nodes. It optionally can allow the user to select nodes from the tree, or to edit the contents of nodes.

Whenever you want to refer to a particular node in the tree, you do so with a TreePath object. A TreePath describes the path to the specified node: its parent node, the parent's parent, and so on up to the root node of the tree. There are various methods for obtaining TreePaths to specific nodes: the root node, the currently selected node or nodes, the children of a particular node, or the parent of a particular node.

A BTree always has a single root node. If you want to create the appearance of a tree with multiple roots, you can hide the root node by calling setRootNodeShown().

BTree provides methods for modifying the tree by adding or removing nodes. These methods assume that the nodes in question implement the javax.swing.tree.MutableTreeNode interface. If you want to add other types of objects to the tree, the easiest way is to wrap them in javax.swing.tree.DefaultMutableTreeNode objects. Alternatively, you can provide your own TreeModel to represent a hierarchy of arbitrary objects.

BTree does not provide scrolling automatically. Normally, it is used inside a BScrollPane to allow the user to scroll through the tree.

If you want to detect mouse clicks on nodes independently of whether they are selected, you can do this by listening for mouse events. The following example detects whenever the user double-clicks on a leaf node:

 tree.addEventLink(MouseClickedEvent.class, new Object() {
   void processEvent(MouseClickedEvent ev)
   {
     if (ev.getClickCount() == 2)
     {
       TreePath path = tree.findNode(ev.getPoint());
       if (path != null && tree.isLeafNode(path))
         System.out.println("Double click on "+path.getLastPathComponent());
     }
   }
 });
 

The appearance of each node is controlled by a TreeCellRenderer, which by default is a javax.swing.tree.DefaultTreeCellRenderer. You can modify or replace the default renderer to customize the appearance of the tree.

A BTree is a wrapper around a JTree and its associated classes, which together form a powerful but also very complex API. BTree exposes only the most commonly used features of this API. To use other features, call getComponent() to get the underlying JTree, then manipulate it directly. For example, you can set a custom TreeCellEditor to control the user interface for editing nodes.

In addition to the event types generated by all Widgets, BTrees generate the following event types:

Author:
Peter Eastman

Constructor Summary

BTree()
Create a BTree whose model is a DefaultTreeModel.
BTree(TreeModel model)
Create a BTree whose contents are determined by a TreeModel.
BTree(TreeNode root)
Create a BTree whose model is a DefaultTreeModel.

Method Summary

TreePath
addNode(TreePath parent, MutableTreeNode node)
Add a new node to the tree.
TreePath
addNode(TreePath parent, MutableTreeNode node, int index)
Add a new node to the tree.
void
clearSelection()
Deselect all nodes in the tree.
void
editNode(TreePath path)
Programmatically begin editing a specified node, if editing is allowed.
TreePath
findNode(Point pos)
Given a Point which represents a pixel location, find which node the Point lies on.
TreeCellRenderer
getCellRenderer()
Get the TreeCellRenderer which draws the individual nodes in the tree.
TreePath
getChildNode(TreePath path, int index)
Given the path to a node, return the path to one of its children.
int
getChildNodeCount(TreePath path)
Given the path to a node, return the number of children it has.
JTree
getComponent()
Get the java.awt.Component corresponding to this Widget.
TreeModel
getModel()
Get the TreeModel which controls the contents of this BTree.
TreePath
getParentNode(TreePath path)
Given the path to a node, return the path to its parent node.
int
getPreferredVisibleRows()
Get the preferred number of rows which should be visible without using a scrollbar.
TreePath
getRootNode()
Get the path to the root node.
TreePath
getSelectedNode()
Get the path to the first selected node.
TreePath[]
getSelectedNodes()
Get an array containing the paths to all selected nodes.
int
getSelectionCount()
Get the number of nodes which are currently selected.
boolean
isEditable()
Determine whether the user is allowed to edit nodes in this tree.
boolean
isLeafNode(TreePath path)
Determine whether a particular node is a leaf node.
boolean
isMultipleSelectionEnabled()
Determine whether this tree allows multiple objects to be selected at the same time.
boolean
isNodeExpanded(TreePath path)
Determine whether a node is currently expanded.
boolean
isNodeSelected(TreePath path)
Determine whether a particular node is selected.
boolean
isNodeVisible(TreePath path)
Determine whether a node is curently visible.
boolean
isRootNodeShown()
Get whether the root node of the tree should be shown.
boolean
isSelectionEnabled()
Determine whether this tree allows nodes to be selected.
void
makeNodeVisible(TreePath path)
Make a node visible by expanding all of its parent nodes.
void
removeNode(TreePath path)
Remove a node from the tree.
void
scrollToNode(TreePath path)
Scroll the BTree's parent BScrollPane to ensure that a particular node is visible.
void
setCellRenderer(TreeCellRenderer renderer)
Set the TreeCellRenderer which draws the individual nodes in the tree.
void
setEditable(boolean editable)
Set whether the user is allowed to edit nodes in this tree.
void
setModel(TreeModel model)
Set the TreeModel which controls the contents of this BTree.
void
setMultipleSelectionEnabled(boolean multiple)
Set whether this tree should allow multiple objects to be selected at the same time.
void
setNodeExpanded(TreePath path, boolean expanded)
Set whether a node is currently expanded.
void
setNodeSelected(TreePath path, boolean selected)
Set whether a particular node is selected.
void
setPreferredVisibleRows(int rows)
Set the preferred number of rows which should be visible without using a scrollbar.
void
setRootNodeShown(boolean shown)
Set whether the root node of the tree should be shown.
void
setSelectionEnabled(boolean enabled)
Set whether this tree should allow nodes to be selected.

Methods inherited from class buoy.widget.Widget

addEventLink, dispatchEvent, getBackground, getBounds, getComponent, getCursor, getFont, getMaximumSize, getMinimumSize, getName, getParent, getPreferredSize, hasFocus, isEnabled, isFocusable, isVisible, repaint, requestFocus, setBackground, setCursor, setEnabled, setFocusable, setFont, setName, setVisible

Methods inherited from class buoy.event.EventSource

addEventLink, addEventLink, addEventLink, dispatchEvent, removeEventLink

Constructor Details

BTree

public BTree()
Create a BTree whose model is a DefaultTreeModel. It contains a single root node which is a DefaultMutableTreeNode.

BTree

public BTree(TreeModel model)
Create a BTree whose contents are determined by a TreeModel.

BTree

public BTree(TreeNode root)
Create a BTree whose model is a DefaultTreeModel.
Parameters:
root - the root node of the tree

Method Details

addNode

public TreePath addNode(TreePath parent,
                        MutableTreeNode node)
Add a new node to the tree. This method assumes that the parent node implements the javax.swing.tree.MutableTreeNode interface.
Parameters:
parent - the path to the parent node which the new node should be added to
node - the new node to add
Returns:
the path to the newly added node

addNode

public TreePath addNode(TreePath parent,
                        MutableTreeNode node,
                        int index)
Add a new node to the tree. This method assumes that the parent node implements the javax.swing.tree.MutableTreeNode interface.
Parameters:
parent - the path to the parent node which the new node should be added to
node - the new node to add
index - the index in the parent node's list of children where the new node should be added
Returns:
the path to the newly added node

clearSelection

public void clearSelection()
Deselect all nodes in the tree.

editNode

public void editNode(TreePath path)
Programmatically begin editing a specified node, if editing is allowed.
Parameters:
path - the path to the node

findNode

public TreePath findNode(Point pos)
Given a Point which represents a pixel location, find which node the Point lies on.
Parameters:
pos - the point of interest
Returns:
the path to the node, or null if the Point is not on any node

getCellRenderer

public TreeCellRenderer getCellRenderer()
Get the TreeCellRenderer which draws the individual nodes in the tree.

getChildNode

public TreePath getChildNode(TreePath path,
                             int index)
Given the path to a node, return the path to one of its children.
Parameters:
path - the path to the node for which to get children
index - the index of the child node to get
Returns:
the path to the specified child node

getChildNodeCount

public int getChildNodeCount(TreePath path)
Given the path to a node, return the number of children it has.
Parameters:
path - the path to the node for which to count the children

getComponent

public JTree getComponent()
Get the java.awt.Component corresponding to this Widget.
Overrides:
getComponent in interface Widget

getModel

public TreeModel getModel()
Get the TreeModel which controls the contents of this BTree.

getParentNode

public TreePath getParentNode(TreePath path)
Given the path to a node, return the path to its parent node.
Parameters:
path - the path whose parent should be returned

getPreferredVisibleRows

public int getPreferredVisibleRows()
Get the preferred number of rows which should be visible without using a scrollbar.

getRootNode

public TreePath getRootNode()
Get the path to the root node. If the tree contains no nodes, this returns null.

getSelectedNode

public TreePath getSelectedNode()
Get the path to the first selected node.

getSelectedNodes

public TreePath[] getSelectedNodes()
Get an array containing the paths to all selected nodes.

getSelectionCount

public int getSelectionCount()
Get the number of nodes which are currently selected.

isEditable

public boolean isEditable()
Determine whether the user is allowed to edit nodes in this tree.

isLeafNode

public boolean isLeafNode(TreePath path)
Determine whether a particular node is a leaf node. A leaf node is one which is not permitted to have children, as opposed to one which could have children but does not. For example, in a tree representing the contents of a file system, the node representing a file would be a leaf node. The node representing a folder would not be a leaf node, even if that folder happens to be empty and therefore has no children.
Parameters:
path - the path to node

isMultipleSelectionEnabled

public boolean isMultipleSelectionEnabled()
Determine whether this tree allows multiple objects to be selected at the same time.

isNodeExpanded

public boolean isNodeExpanded(TreePath path)
Determine whether a node is currently expanded.
Parameters:
path - the path to the node

isNodeSelected

public boolean isNodeSelected(TreePath path)
Determine whether a particular node is selected.
Parameters:
path - the path to the node

isNodeVisible

public boolean isNodeVisible(TreePath path)
Determine whether a node is curently visible. This means that all of its parent nodes are expanded.
Parameters:
path - the path to the node

isRootNodeShown

public boolean isRootNodeShown()
Get whether the root node of the tree should be shown. If this is false, then the children of the root node will appear to be the top level of tree. This allows you to create the illusion of a tree with multiple roots.

isSelectionEnabled

public boolean isSelectionEnabled()
Determine whether this tree allows nodes to be selected.

makeNodeVisible

public void makeNodeVisible(TreePath path)
Make a node visible by expanding all of its parent nodes.
Parameters:
path - the path to the node

removeNode

public void removeNode(TreePath path)
Remove a node from the tree. This method assumes that the node being removed implements the javax.swing.tree.MutableTreeNode interface.
Parameters:
path - the path to the node which should be removed

scrollToNode

public void scrollToNode(TreePath path)
Scroll the BTree's parent BScrollPane to ensure that a particular node is visible. If the parent is not a BScrollPane, the results of calling this method are undefined, but usually it will have no effect at all.

If the specified node is hidden because one of its parent nodes is currently collapsed, this method has no effect. Usually you will first call makeNodeVisible() before calling this method.

Parameters:
path - the path to the node

setCellRenderer

public void setCellRenderer(TreeCellRenderer renderer)
Set the TreeCellRenderer which draws the individual nodes in the tree.

setEditable

public void setEditable(boolean editable)
Set whether the user is allowed to edit nodes in this tree.

setModel

public void setModel(TreeModel model)
Set the TreeModel which controls the contents of this BTree.

setMultipleSelectionEnabled

public void setMultipleSelectionEnabled(boolean multiple)
Set whether this tree should allow multiple objects to be selected at the same time.

setNodeExpanded

public void setNodeExpanded(TreePath path,
                            boolean expanded)
Set whether a node is currently expanded.
Parameters:
path - the path to the node
expanded - specifies whether the node should be expanded or collapsed

setNodeSelected

public void setNodeSelected(TreePath path,
                            boolean selected)
Set whether a particular node is selected.
Parameters:
path - the path to the node
selected - specifies whether the node should be selected

setPreferredVisibleRows

public void setPreferredVisibleRows(int rows)
Set the preferred number of rows which should be visible without using a scrollbar.

setRootNodeShown

public void setRootNodeShown(boolean shown)
Set whether the root node of the tree should be shown. If this is false, then the children of the root node will appear to be the top level of tree. This allows you to create the illusion of a tree with multiple roots.

setSelectionEnabled

public void setSelectionEnabled(boolean enabled)
Set whether this tree should allow nodes to be selected.

Written by Peter Eastman.