buoy.widget
Class BTree

java.lang.Object
  buoy.event.EventSource
      buoy.widget.Widget
          buoy.widget.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:

• ValueChangedEvent
• SelectionChangedEvent

Author:

Peter Eastman

Constructor Summary

BTree()
Create a BTree whose model is a DefaultTreeModel.

BTree(javax.swing.tree.TreeModel model)
Create a BTree whose contents are determined by a TreeModel.

BTree(javax.swing.tree.TreeNode root)
Create a BTree whose model is a DefaultTreeModel.

Method Summary

javax.swing.tree.TreePath	addNode(javax.swing.tree.TreePath parent, javax.swing.tree.MutableTreeNode node) Add a new node to the tree.
javax.swing.tree.TreePath	addNode(javax.swing.tree.TreePath parent, javax.swing.tree.MutableTreeNode node, int index) Add a new node to the tree.
void	clearSelection() Deselect all nodes in the tree.
void	editNode(javax.swing.tree.TreePath path) Programmatically begin editing a specified node, if editing is allowed.
javax.swing.tree.TreePath	findNode(java.awt.Point pos) Given a Point which represents a pixel location, find which node the Point lies on.
javax.swing.tree.TreeCellRenderer	getCellRenderer() Get the TreeCellRenderer which draws the individual nodes in the tree.
javax.swing.tree.TreePath	getChildNode(javax.swing.tree.TreePath path, int index) Given the path to a node, return the path to one of its children.
int	getChildNodeCount(javax.swing.tree.TreePath path) Given the path to a node, return the number of children it has.
javax.swing.JTree	getComponent() Get the java.awt.Component corresponding to this Widget.
javax.swing.tree.TreeModel	getModel() Get the TreeModel which controls the contents of this BTree.
javax.swing.tree.TreePath	getParentNode(javax.swing.tree.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.
javax.swing.tree.TreePath	getRootNode() Get the path to the root node.
javax.swing.tree.TreePath	getSelectedNode() Get the path to the first selected node.
javax.swing.tree.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(javax.swing.tree.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(javax.swing.tree.TreePath path) Determine whether a node is currently expanded.
boolean	isNodeSelected(javax.swing.tree.TreePath path) Determine whether a particular node is selected.
boolean	isNodeVisible(javax.swing.tree.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(javax.swing.tree.TreePath path) Make a node visible by expanding all of its parent nodes.
void	removeNode(javax.swing.tree.TreePath path) Remove a node from the tree.
void	scrollToNode(javax.swing.tree.TreePath path) Scroll the BTree's parent BScrollPane to ensure that a particular node is visible.
void	setCellRenderer(javax.swing.tree.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(javax.swing.tree.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(javax.swing.tree.TreePath path, boolean expanded) Set whether a node is currently expanded.
void	setNodeSelected(javax.swing.tree.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, 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, removeEventLink

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BTree

public BTree()

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

BTree

public BTree(javax.swing.tree.TreeNode root)

Create a BTree whose model is a DefaultTreeModel.

Parameters:

root - the root node of the tree

BTree

public BTree(javax.swing.tree.TreeModel model)

Create a BTree whose contents are determined by a TreeModel.

Method Detail

getComponent

public javax.swing.JTree getComponent()

Description copied from class: Widget

Get the java.awt.Component corresponding to this Widget.

Overrides:

getComponent in class Widget

getModel

public javax.swing.tree.TreeModel getModel()

Get the TreeModel which controls the contents of this BTree.

setModel

public void setModel(javax.swing.tree.TreeModel model)

Set the TreeModel which controls the contents of this BTree.

getRootNode

public javax.swing.tree.TreePath getRootNode()

Get the path to the root node. If the tree contains no nodes, this returns null.

getChildNodeCount

public int getChildNodeCount(javax.swing.tree.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

getChildNode

public javax.swing.tree.TreePath getChildNode(javax.swing.tree.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

getParentNode

public javax.swing.tree.TreePath getParentNode(javax.swing.tree.TreePath path)

Given the path to a node, return the path to its parent node.

Parameters:

path - the path whose parent should be returned

isLeafNode

public boolean isLeafNode(javax.swing.tree.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

addNode

public javax.swing.tree.TreePath addNode(javax.swing.tree.TreePath parent,
                                         javax.swing.tree.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 javax.swing.tree.TreePath addNode(javax.swing.tree.TreePath parent,
                                         javax.swing.tree.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

removeNode

public void removeNode(javax.swing.tree.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

isSelectionEnabled

public boolean isSelectionEnabled()

Determine whether this tree allows nodes to be selected.

setSelectionEnabled

public void setSelectionEnabled(boolean enabled)

Set whether this tree should allow nodes to be selected.

isMultipleSelectionEnabled

public boolean isMultipleSelectionEnabled()

Determine whether this tree allows multiple objects to be selected at the same time.

setMultipleSelectionEnabled

public void setMultipleSelectionEnabled(boolean multiple)

Set whether this tree should allow multiple objects to be selected at the same time.

getSelectionCount

public int getSelectionCount()

Get the number of nodes which are currently selected.

getSelectedNode

public javax.swing.tree.TreePath getSelectedNode()

Get the path to the first selected node.

getSelectedNodes

public javax.swing.tree.TreePath[] getSelectedNodes()

Get an array containing the paths to all selected nodes.

isNodeSelected

public boolean isNodeSelected(javax.swing.tree.TreePath path)

Determine whether a particular node is selected.

Parameters:

path - the path to the node

setNodeSelected

public void setNodeSelected(javax.swing.tree.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

clearSelection

public void clearSelection()

Deselect all nodes in the tree.

isEditable

public boolean isEditable()

Determine whether the user is allowed to edit nodes in this tree.

setEditable

public void setEditable(boolean editable)

Set whether the user is allowed to edit nodes in this tree.

editNode

public void editNode(javax.swing.tree.TreePath path)

Programmatically begin editing a specified node, if editing is allowed.

Parameters:

path - the path to the node

findNode

public javax.swing.tree.TreePath findNode(java.awt.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

isNodeExpanded

public boolean isNodeExpanded(javax.swing.tree.TreePath path)

Determine whether a node is currently expanded.

Parameters:

path - the path to the node

setNodeExpanded

public void setNodeExpanded(javax.swing.tree.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

isNodeVisible

public boolean isNodeVisible(javax.swing.tree.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

makeNodeVisible

public void makeNodeVisible(javax.swing.tree.TreePath path)

Make a node visible by expanding all of its parent nodes.

Parameters:

path - the path to the node

scrollToNode

public void scrollToNode(javax.swing.tree.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

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.

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.

getPreferredVisibleRows

public int getPreferredVisibleRows()

Get the preferred number of rows which should be visible without using a scrollbar.

setPreferredVisibleRows

public void setPreferredVisibleRows(int rows)

Set the preferred number of rows which should be visible without using a scrollbar.

getCellRenderer

public javax.swing.tree.TreeCellRenderer getCellRenderer()

Get the TreeCellRenderer which draws the individual nodes in the tree.

setCellRenderer

public void setCellRenderer(javax.swing.tree.TreeCellRenderer renderer)

Set the TreeCellRenderer which draws the individual nodes in the tree.