com.arsdigita.bebop
Class Tree

java.lang.Object
  com.arsdigita.bebop.Completable
      com.arsdigita.bebop.SimpleComponent
          com.arsdigita.bebop.Tree

All Implemented Interfaces:

Cloneable, Component, Lockable, Resettable

public class Tree

extends SimpleComponent

implements Resettable

Used to print a tree structure. Nodes can be in expanded or collapsed state. Tree uses the getChildren() and getRoot() methods from TreeModel and traverses the iterator to get to all the nodes. This class keeps track of which nodes are expanded and collapsed and the hierarchy of nodes, and displays the tree correspondingly.

Version:

$Id: //core-platform/dev/src/com/arsdigita/bebop/Tree.java#14 $

Author:

David Lutterkort, Stanislav Freidin, Tri Tran

Nested Class Summary

static class

Tree.TreeSingleSelectionModel Deprecated. The ParameterSingleSelectionModel contains all the functionality of this class

Field Summary

protected TreeModelBuilder	m_builder
protected StringParameter	m_currentState
static String	versionId

Fields inherited from class com.arsdigita.bebop.SimpleComponent

m_attr

Fields inherited from interface com.arsdigita.bebop.Component

BEBOP_XML_NS, CLASS, ID, ON_CLICK, STYLE

Constructor Summary

Tree(TreeModel t)
Deprecated. This constructor has been deprecated in favor of Tree(TreeModelBuilder b). It is not practical to hardwire the TreeModel into the Tree, since the model may change during each request. It is possible to write the model-instantiation code in TreeModel.getRoot(PageState), but the TreeModelBuilder fits better into the pattern which has already been established by List and Table

Tree(TreeModelBuilder b)
Constructs a new Tree using the specified TreeModelBuilder.

Method Summary

void	addActionListener(ActionListener l) Adds a listener that is notified whenever a user clicks on any part of the tree, either to expand or collapse a node, or to select a node.
void	addChangeListener(ChangeListener l) Adds a change listener.
void	addTreeExpansionListener(TreeExpansionListener l) Adds a listener that is notified whenever a tree node is expanded or collpased, either by a user's click or by explicit calls to expand or collapse.
void	clearExpansionState(PageState state) Clears any tree node expansion state on the request.
void	clearSelection(PageState state) Clears the selection in the request represented by state.
void	collapse(String nodeKey, PageState data) Collapses a node in the tree and makes its children visible.
protected ChangeListener	createChangeListener() Creates the change listener used for forwarding change events fired by the selection model to change listeners registered with the tree.
void	expand(String nodeKey, PageState data) Expands a node in the tree and makes its children visible.
protected void	fireActionEvent(PageState data) Notifies listeners that some part of the tree was clicked by the user.
protected void	fireStateChanged(PageState state) Fires a change event to signal that the selected list item has changed in the request represented by state.
protected void	fireTreeCollapsed(PageState state, Object nodeKey) Notifies all registered TreeExpansionListeners that a node in the tree has been collapsed.
protected void	fireTreeExpanded(PageState state, Object nodeKey) Notifies all registered TreeExpansionListeners that a node in the tree has been expanded.
protected void	generateTree(PageState data, Element parent, TreeNode node, TreeModel tree) Builds a DOM representing the tree.
void	generateXML(PageState data, Element parent) Services the request by building a DOM tree with the nodes first and then the included page.
TreeCellRenderer	getCellRenderer() Returns the renderer currently used to render tree nodes.
TreeModelBuilder	getModelBuilder()
Object	getSelectedKey(PageState state) Gets the key for the selected node.
SingleSelectionModel	getSelectionModel() Gets the selection model, which keeps track of which node is currently selected.
TreeModel	getTreeModel() Deprecated. Use getTreeModel(PageState) instead
TreeModel	getTreeModel(PageState s) Returns the TreeModel used by the tree for the current request.
boolean	hasExpansionState(PageState state) Tells whether the tree has state on the request for tree node expansion.
boolean	isCollapsed(String nodeKey, PageState data) Determines whether the node at the specified display row is collapsed.
boolean	isSelected(PageState state) Returns true if one of the nodes is currently selected.
void	lock() Locks the Tree and prohibits further modifications.
void	register(Page p) Registers the two parameters to the page.
void	removeActionListener(ActionListener l) Removes a previously added ActionListener.
void	removeChangeListener(ChangeListener l) Removes a change listener.
void	removeTreeExpansionListener(TreeExpansionListener l) Removes a previously added TreeExpansionListener.
void	reset(PageState state) Clears the request state of the tree.
void	respond(PageState data) Notifies the Tree that a node has been selected.
void	setCellRenderer(TreeCellRenderer r) Sets the cell renderer to be used when generating output with generateXML.
void	setModelBuilder(TreeModelBuilder b)
void	setSelectedKey(PageState state, Object key) Sets the selection to the one with the specified key.
void	setSelectionModel(SingleSelectionModel m) Sets the selection model, which keeps track of which node is currently selected.
void	setTreeModel(TreeModel m) Sets the tree model used for this tree.

Methods inherited from class com.arsdigita.bebop.SimpleComponent

children, clone, exportAttributes, getAttribute, getClassAttr, getIdAttr, getKey, getMetaDataAttribute, getStyleAttr, hasAttributes, isLocked, isVisible, register, setAttribute, setClassAttr, setIdAttr, setKey, setMetaDataAttribute, setStyleAttr, setVisible

Methods inherited from class com.arsdigita.bebop.Completable

addCompletionListener, fireCompletionEvent

Methods inherited from class java.lang.Object

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

Field Detail

versionId

public static final String versionId

See Also:

Constant Field Values

m_currentState

protected StringParameter m_currentState

m_builder

protected TreeModelBuilder m_builder

Constructor Detail

Tree

public Tree(TreeModelBuilder b)

Constructs a new Tree using the specified TreeModelBuilder. The TreeModelBuilder will instantiate a TreeModel during each request.

Parameters:

b - the TreeModelBuilder

Tree

public Tree(TreeModel t)

Deprecated. This constructor has been deprecated in favor of Tree(TreeModelBuilder b). It is not practical to hardwire the TreeModel into the Tree, since the model may change during each request. It is possible to write the model-instantiation code in TreeModel.getRoot(PageState), but the TreeModelBuilder fits better into the pattern which has already been established by List and Table

Deprecated constructor that takes a default TreeModel and wraps it in a dummy TreeModelBuilder.

Parameters:

t - the TreeModel

Method Detail

register

public void register(Page p)

Registers the two parameters to the page.

Specified by:

register in interface Component

Overrides:

register in class SimpleComponent

reset

public void reset(PageState state)

Clears the request state of the tree.

Specified by:

reset in interface Resettable

Parameters:

state - the page state

getTreeModel

public final TreeModel getTreeModel()

Deprecated. Use getTreeModel(PageState) instead

Returns the tree model used for this tree.

Returns:

a TreeModel.

See Also:

setTreeModel, TreeModel

getTreeModel

public TreeModel getTreeModel(PageState s)

Returns the TreeModel used by the tree for the current request.

Parameters:

s - the page state

getModelBuilder

public final TreeModelBuilder getModelBuilder()

Returns:

the TreeModelBuilder used to build the tree model for this tree.

setModelBuilder

public void setModelBuilder(TreeModelBuilder b)

Parameters:

b - the new TreeModelBuilder for the tree

setTreeModel

public void setTreeModel(TreeModel m)

Sets the tree model used for this tree.

Returns:

a TreeModel.

See Also:

setTreeModel, TreeModel

setSelectionModel

public void setSelectionModel(SingleSelectionModel m)

Sets the selection model, which keeps track of which node is currently selected. It can be used to manipulate the selection programmatically.

Parameters:

m - the new selection model

getSelectionModel

public final SingleSelectionModel getSelectionModel()

Gets the selection model, which keeps track of which node is currently selected. It can be used to manipulate the selection programmatically.

Returns:

the model used by the tree to keep track of the selected node.

getSelectedKey

public Object getSelectedKey(PageState state)

Gets the key for the selected node. This will only be a valid key if isSelected is true.

Parameters:

state - represents the state of the current request

Returns:

the key for the selected node.

setSelectedKey

public void setSelectedKey(PageState state,
                           Object key)

Sets the selection to the one with the specified key. If key was not selected already, fires the ChangeEvent.

Parameters:

state - represents the state of the current request

key - the key for the selected node

See Also:

fireStateChanged

isSelected

public boolean isSelected(PageState state)

Returns true if one of the nodes is currently selected.

Parameters:

state - represents the state of the current request

Returns:

true if one of the nodes is selected; false otherwise.

clearSelection

public void clearSelection(PageState state)

Clears the selection in the request represented by state.

Parameters:

state - represents the state of the current request

hasExpansionState

public final boolean hasExpansionState(PageState state)

Tells whether the tree has state on the request for tree node expansion.

clearExpansionState

public final void clearExpansionState(PageState state)

Clears any tree node expansion state on the request.

createChangeListener

protected ChangeListener createChangeListener()

Creates the change listener used for forwarding change events fired by the selection model to change listeners registered with the tree. The returned change listener refires the event with the tree, rather than the selection model, as source.

Returns:

the change listener used internally by the tree.

addChangeListener

public void addChangeListener(ChangeListener l)

Adds a change listener. A change event is fired whenever the selected tree node changes during the processing of a request. The change event that listeners receive names the tree as the source.

Parameters:

l - the change listener to run when the selected item changes in a request

removeChangeListener

public void removeChangeListener(ChangeListener l)

Removes a change listener. The listener should have been previously added with addChangeListener, although no error is signalled if the change listener is not found among the tree's listeners.

Parameters:

l - the change listener to remove from the tree

fireStateChanged

protected void fireStateChanged(PageState state)

Fires a change event to signal that the selected list item has changed in the request represented by state. The source of the event is the tree.

Parameters:

state - represents the state of the current request

addActionListener

public void addActionListener(ActionListener l)

Adds a listener that is notified whenever a user clicks on any part of the tree, either to expand or collapse a node, or to select a node. The listener is run whenever respond is called.

removeActionListener

public void removeActionListener(ActionListener l)

Removes a previously added ActionListener.

See Also:

addActionListener

fireActionEvent

protected void fireActionEvent(PageState data)

Notifies listeners that some part of the tree was clicked by the user. The source of the event is the tree.

See Also:

respond

addTreeExpansionListener

public void addTreeExpansionListener(TreeExpansionListener l)

Adds a listener that is notified whenever a tree node is expanded or collpased, either by a user's click or by explicit calls to expand or collapse.

removeTreeExpansionListener

public void removeTreeExpansionListener(TreeExpansionListener l)

Removes a previously added TreeExpansionListener.

See Also:

addTreeExpansionListener

fireTreeExpanded

protected void fireTreeExpanded(PageState state,
                                Object nodeKey)

Notifies all registered TreeExpansionListeners that a node in the tree has been expanded.

fireTreeCollapsed

protected void fireTreeCollapsed(PageState state,
                                 Object nodeKey)

Notifies all registered TreeExpansionListeners that a node in the tree has been collapsed.

respond

public void respond(PageState data)
             throws javax.servlet.ServletException

Notifies the Tree that a node has been selected. Changes the currently selected tree component.

Specified by:

respond in interface Component

Overrides:

respond in class SimpleComponent

Parameters:

data - the current page state

Throws:

javax.servlet.ServletException

isCollapsed

public boolean isCollapsed(String nodeKey,
                           PageState data)

Determines whether the node at the specified display row is collapsed.

Returns:

true if the node at the specified display row is collapsed; false otherwise.

collapse

public void collapse(String nodeKey,
                     PageState data)

Collapses a node in the tree and makes its children visible.

Parameters:

nodeKey - the key that the tree model uses to identify the node

data - represents the current request

expand

public void expand(String nodeKey,
                   PageState data)

Expands a node in the tree and makes its children visible.

Parameters:

nodeKey - the key that the tree model uses to identify the node

data - represents the current request

getCellRenderer

public final TreeCellRenderer getCellRenderer()

Returns the renderer currently used to render tree nodes.

Returns:

the current tree node renderer.

setCellRenderer

public void setCellRenderer(TreeCellRenderer r)

Sets the cell renderer to be used when generating output with generateXML.

Parameters:

r - a TreeCellRenderer value

generateTree

protected void generateTree(PageState data,
                            Element parent,
                            TreeNode node,
                            TreeModel tree)

Builds a DOM representing the tree.

generateXML

public void generateXML(PageState data,
                        Element parent)

Services the request by building a DOM tree with the nodes first and then the included page.

Specified by:

generateXML in interface Component

Overrides:

generateXML in class SimpleComponent

lock

public void lock()

Locks the Tree and prohibits further modifications.

Specified by:

lock in interface Lockable

Overrides:

lock in class SimpleComponent