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
TreePath
s 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:
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.
parent
- the path to the parent node which the new node should be added tonode
- the new node to add
- 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.
parent
- the path to the parent node which the new node should be added tonode
- the new node to addindex
- the index in the parent node's list of children where the new node
should be added
- 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.
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.
pos
- the point of interest
- 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.
path
- the path to the node for which to get childrenindex
- the index of the child node to get
- 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.
path
- the path to the node for which to count the children
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.
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.
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.
path
- the path to the node
isNodeSelected
public boolean isNodeSelected(TreePath path)
Determine whether a particular node is selected.
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.
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.
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.
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.
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.
path
- the path to the nodeexpanded
- specifies whether the node should be expanded or collapsed
setNodeSelected
public void setNodeSelected(TreePath path,
boolean selected)
Set whether a particular node is selected.
path
- the path to the nodeselected
- 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.