com.sas.swing.visuals
Class NodeView

com.sas.swing.visuals.NodeView

All Implemented Interfaces:

com.sas.beans.PropertyChangeSource, com.sas.models.NodeIconInterface, com.sas.models.NodeInterface, com.sas.models.SimpleNodeInterface, CommandsInterface, java.beans.PropertyChangeListener, java.util.EventListener

public class NodeView
implements CommandsInterface, com.sas.models.NodeIconInterface, java.beans.PropertyChangeListener, com.sas.beans.PropertyChangeSource

A NodeView object represents a single node in a TreeView object. It is constructed from a NodeInterface object that is provided from a data source to the TreeView. In addition to the information provided by NodeInterface, NodeView provides viewer and hierarchical specific information such as selected and expanded states, a reference to its parent and its depth in the hierarchy. Additionally it provides convenience methods for expanding ancestors and for finding siblings.

Source NodeInterface

NodeView provides read only access to the NodeInterface provided by the data source. However, if the implementation of the underlying NodeInterface allows updates to the properties that it provides, it can be retrieved from NodeView and then cast to the appropriate type for the update.

NOTE: Do not confuse a NodeView with its underlying NodeInterface object. It is easy to confuse NodeView with its underlying NodeInterface object since they both implement NodeInterface. Confusion can especially arise in calling the child retrieval methods since they return objects of type SimpleNodeInterface. For example, calling getNodeChild on a NodeView will return an object of type SimpleNodeInterface. The actual type of the object returned is NodeView and should be cast to a NodeView to be treated as such. The following code demonstrates how to get the underlying NodeInterface of a child node at index 3:

 SimpleNodeInterface node = parentNode.getNodeChild(3);  // get child 3
 NodeView nodeV = (NodeView)node; // node is actually a NodeView so cast it
 NodeInterface underlyingNode = nodeV.getNode(); // now get the NodeInterface
 

In the code example above, if the implementation of the underlying NodeInterface object was updatable, we could have cast it to the appropriate type and then performed the update.

Icons

A NodeView can provide 4 different icons based on its state: default, selected, expanded and expanded-selected. In the absence of a value for one of these icons, one of the other icons may be used. The inheritance hierarchy is as follows:

• selected inherits from default
• expanded inherits from default
• expanded-selected inherits from expanded

If any icons are provided, typically only the default icon is specified.

Styles

See Styles section in TreeView documentation.

In Place Editing

NodeView allows a source NodeInterface to have its displayed text edited in place under certain conditions. A node can be edited if the source NodeInterface implements MutableNodeInterface and if the NodeView has a NodeStyle.EDITABLE style value of true. In place editing can be initiated in two ways: via the "Rename" popup menu item on the TreeView or by calling setEditing(true) on the NodeView. The text value that is edited (nodeText vs expandedNodeText) is controlled by the value of the NodeStyle.EXPANDED_TEXT_DISPLAYED style value.

Validation can be performed on the text entered through in place editing. This is done by setting a validator on the TreeView. If a new text value is marked invalid by a validator, then an error handler can be set on either the TreeView or on the node's style to handle the error.

See Also:

MutableNodeInterface, NodeInterface, SimpleNodeInterface, NodeStyle, TreeView

Field Summary

static java.lang.String	NODE_EDITING_ERROR Constant used to identify errors that occur when NodeView is in edit mode.
static java.lang.String	RB_KEY

Constructor Summary

protected

NodeView(TreeView treeView, com.sas.models.NodeInterface node) Constructs a NodeView object.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener)
int	countNodeChildren(int maximumChildCount) Counts the children of the current node.
com.sas.util.Command[]	getCommands() Returns a list of commands that can be executed on the current node.
com.sas.visuals.IconInterface	getDefaultIcon() Returns the default icon for the current node.
com.sas.collection.PropertyBagInterface	getDefaultNodeStyle() Returns the set of style properties that serve as the defaults for this node and for all of its descendants.
int	getDepth() Returns the depth of the current node in the tree.
com.sas.visuals.IconInterface	getExpandedIcon() Returns the expanded icon for the current node.
com.sas.visuals.IconInterface	getExpandedSelectedIcon() Returns the expandedSelected icon for the current node.
int	getIndex(NodeView childNode, int startIndex) Returns the index in the child list of the specified node.
NodeView	getNextSibling() Returns the sibling node immediately following the current node.
com.sas.models.NodeInterface	getNode() Returns the NodeInterface object for the current node.
com.sas.models.SimpleNodeInterface	getNodeChild(int index) Returns the child node at the specified 0-based index.
int	getNodeChildCount() Returns the number of children.
com.sas.models.SimpleNodeInterface[]	getNodeChildren(int startIndex, int count) Returns a range of child nodes.
java.lang.String	getNodeExpandedText() Returns the expanded text for the current node.
com.sas.collection.PropertyBagInterface	getNodeStyle() Returns the set of style properties that serve as formatting and rendering defaults and hints for this node.
java.lang.String	getNodeText() Returns the text for the current node.
java.lang.String	getNodeType() Returns the type of the current node.
NodeView	getParent() Returns the parent of the current node.
NodeView	getPreviousSibling() Returns the sibling node immediately preceding the current node.
com.sas.visuals.IconInterface	getSelectedIcon() Returns the selected icon for the current node.
NodeState	getSingleState() Returns the state of the current NodeView object.
NodeState	getState() Returns the state of the current NodeView object and all descendants.
int	getVisibleNodeCount() Returns the visible node count for the current node.
boolean	isEditing() Indicates whether the current node is being edited in place or not.
boolean	isExpanded() Indicates whether the current node is expanded.
boolean	isLeafNode() Indicates if the current NodeView is a leaf (has no children).
boolean	isSelected() Indicates whether the current node is selected.
boolean	isVisible() Returns true if the node is visible and false if it is hidden.
protected void	notifyPropertyChange(java.beans.PropertyChangeEvent event) Send a PropertyChangeEvent event to all the PropertyChangeListener objects in the listener list.
void	onAction() Called whenever a node is double-clicked in the viewer.
void	onSelect() Called whenever a node is selected in the viewer.
void	propertyChange(java.beans.PropertyChangeEvent event) Handles PropertyChangeEvents received by the current node.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Remove a listener for the java.beans.PropertyChangeEvent event.
void	repopulate() Directs the current node to refresh its child list from its underlying NodeInterface object.
void	setDefaultNodeStyle(com.sas.collection.PropertyBagInterface newValue) Sets the set of style properties that serve as the defaults for this node and for all of its descendants.
void	setEditing(boolean newValue) Directs the current node to enter or exit editing mode.
void	setExpanded(boolean newValue) Controls whether the current node is expanded or collapsed.
void	setNodeStyle(com.sas.collection.PropertyBagInterface newValue) Sets the set of style properties that serve as formatting and rendering defaults and hints for this node.
void	setSelected(boolean newValue) Controls whether the current node is selected.
void	setState(NodeState state) Restores the state of the current NodeView object from the specified NodeState object.
void	setVisible() Convience method to expand all ancestors.
protected boolean	supportsCommandsInterface() Indicates whether the underlying NodeInterface implements com.sas.util.CommandsInterface.
java.lang.String	toString() Returns the displayed text for the current node.
void	updateVisibleNodeCount() Directs the current node to update its visible node count.

Field Detail

RB_KEY

public static final java.lang.String RB_KEY

See Also:

Constant Field Values

NODE_EDITING_ERROR

public static final java.lang.String NODE_EDITING_ERROR

Constant used to identify errors that occur when NodeView is in edit mode. This error currently occurs whenever invalid text is entered interactively and an exception occurs when calling setNodeText or setNodeExpandedText on the underlying NodeInterface.

See Also:

Constant Field Values

Constructor Detail

NodeView

protected NodeView(TreeView treeView,
                   com.sas.models.NodeInterface node)

Constructs a NodeView object.

Parameters:

treeView - associated TreeView object

node - source node

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Specified by:

addPropertyChangeListener in interface com.sas.beans.PropertyChangeSource

See Also:

PropertyChangeSource.addPropertyChangeListener(java.beans.PropertyChangeListener)

countNodeChildren

public int countNodeChildren(int maximumChildCount)

Counts the children of the current node. countNodeChildren differs from getNodeChildCount when the number of children is unknown, i.e. when getNodeChildCount returns -1. If your implementation of getNodeChildCount never returns -1, then simply define countNodeChildren as a return of getNodeChildCount, otherwise read-on.

countNodeChildren is an instruction to determine the number of children even though that number is not readily known. To limit the potential overhead of this determination, the maximum number of children to read may be specified.

Specified by:

countNodeChildren in interface com.sas.models.SimpleNodeInterface

Parameters:

maxCount - Maximum number of children to read, or 0 to read indefinitely. Implementations where the number of children is always known should ignore this parameter. In cases where the total number of children is unknown, but the number known so far is greater than maxCount should return the larger known number. Thus maxCount is only used as a limiting factor when the implementation has to actually do computation (e.g. fetch observations).

Returns:

The number of children known to be available.

getCommands

public com.sas.util.Command[] getCommands()

Returns a list of commands that can be executed on the current node. If the underlying NodeInterface does not implement CommandsInterface, null will be returned.

Specified by:

getCommands in interface CommandsInterface

Returns:

the list of commands supported by the current node

getDefaultIcon

public com.sas.visuals.IconInterface getDefaultIcon()

Returns the default icon for the current node. The default icon is used for unexpanded, unselected states. If no other icons are set, then it will serve for all states. If there is no default icon set, null is returned. The default value is null.

Specified by:

getDefaultIcon in interface com.sas.models.NodeIconInterface

Returns:

the default icon, otherwise null

getDefaultNodeStyle

public com.sas.collection.PropertyBagInterface getDefaultNodeStyle()

Returns the set of style properties that serve as the defaults for this node and for all of its descendants.

Returns:

the value of the defaultNodeStyle property

See Also:

setDefaultNodeStyle(com.sas.collection.PropertyBagInterface), getNodeStyle(), setNodeStyle(com.sas.collection.PropertyBagInterface)

getDepth

public int getDepth()

Returns the depth of the current node in the tree. A node at the root level will return a depth of 0.

Returns:

the depth of the current node

getExpandedIcon

public com.sas.visuals.IconInterface getExpandedIcon()

Returns the expanded icon for the current node. The expanded icon is used whenever a node is expanded but not selected. If a node is a leaf node then expanded icon is not used. If there is no expanded icon set, the result of getDefaultIcon is returned.

Specified by:

getExpandedIcon in interface com.sas.models.NodeIconInterface

Returns:

the expanded icon, otherwise the result of getDefaultIcon

See Also:

getDefaultIcon()

getExpandedSelectedIcon

public com.sas.visuals.IconInterface getExpandedSelectedIcon()

Returns the expandedSelected icon for the current node. The expandedSelected icon is used whenever a node is expanded and selected simultaneously. If a node is a leaf node then expanded icon is not used. If expandedSelected icon is not set, the result of getExpandedIcon is returned.

Specified by:

getExpandedSelectedIcon in interface com.sas.models.NodeIconInterface

Returns:

the expandedSelected icon, otherwise the result of getExpandedIcon

See Also:

getExpandedIcon()

getIndex

public int getIndex(NodeView childNode,
                    int startIndex)

Returns the index in the child list of the specified node.

Parameters:

childNode - child node to find the index of

startIndex - the position where the search should start

Returns:

the 0-based index of the specifed node

getNextSibling

public NodeView getNextSibling()

Returns the sibling node immediately following the current node. If the current node is the last child (or the only child) of its parent, null is returned.

Returns:

the next node in the child list for the parent of the current node or null if there is no next node

getNode

public com.sas.models.NodeInterface getNode()

Returns the NodeInterface object for the current node. This is the NodeInterface object that was provided by the data source and used to create the current NodeView object.

Returns:

the NodeInterface object from the data source

getNodeChild

public com.sas.models.SimpleNodeInterface getNodeChild(int index)

Returns the child node at the specified 0-based index. If the child count is unknown and the current NodeView does not have a child at the specified index, null will be returned.

NOTE: Although a SimpleNodeInterface object is returned the actual object type is NodeView. This object should not be confused with the NodeInterface object that was used to create it.

Specified by:

getNodeChild in interface com.sas.models.SimpleNodeInterface

Parameters:

index - the 0-based index of the child to get

Returns:

the child NodeView object (as type SimpleNodeInterface) at the index.

getNodeChildCount

public int getNodeChildCount()

Returns the number of children. A return value of -1 indicates that the child count is unknown.

Specified by:

getNodeChildCount in interface com.sas.models.SimpleNodeInterface

Returns:

the number of children if known, otherwise -1

getNodeChildren

public com.sas.models.SimpleNodeInterface[] getNodeChildren(int startIndex,
                                                            int count)

Returns a range of child nodes. The number of nodes specified by count are returned starting at startIndex. If the child count is unknown and there are no children in the requested range, an array of length 0 will be returned.

NOTE: Although an array of SimpleNodeInterface objects is returned, the actual object types are NodeView. These objects should not be confused with the NodeInterface objects that were used to create them.

Specified by:

getNodeChildren in interface com.sas.models.SimpleNodeInterface

Parameters:

startIndex - 0-based index which identifies the start of the range

count - the amount of children to get

Returns:

an array of children NodeView objects (as type SimpleNodeInterface) for the specified range

getNodeExpandedText

public java.lang.String getNodeExpandedText()

Returns the expanded text for the current node. The expanded text is used to provide a more descriptive text string for a node.

Specified by:

getNodeExpandedText in interface com.sas.models.NodeInterface

Returns:

the value of the nodeExpandedText property

getNodeStyle

public com.sas.collection.PropertyBagInterface getNodeStyle()

Returns the set of style properties that serve as formatting and rendering defaults and hints for this node. There are no style properties by default.

Returns:

the value of the nodeStyle property

See Also:

setNodeStyle(com.sas.collection.PropertyBagInterface), getDefaultNodeStyle(), setDefaultNodeStyle(com.sas.collection.PropertyBagInterface)

getNodeText

public java.lang.String getNodeText()

Returns the text for the current node.

Specified by:

getNodeText in interface com.sas.models.NodeInterface

Returns:

the text for the current node.

getNodeType

public java.lang.String getNodeType()

Returns the type of the current node. The type is a text string which allows the user of a node hierarchy to add more information to nodes. For example nodes in a file system viewer could use "file" or "directory" as the type to distinguish between nodes representing files and directories.

Specified by:

getNodeType in interface com.sas.models.NodeInterface

Returns:

the type of the currect node

getParent

public NodeView getParent()

Returns the parent of the current node. If the current node is a root node, null is returned.

Returns:

the parent of the currect node

getPreviousSibling

public NodeView getPreviousSibling()

Returns the sibling node immediately preceding the current node. If the current node is the first child (or the only child) of its parent, null is returned.

Returns:

the previous node in the child list for the parent of the current node or null if there is no previous node

getSelectedIcon

public com.sas.visuals.IconInterface getSelectedIcon()

Returns the selected icon for the current node. The selected icon is used whenever a node is selected and not expanded. If there is not a selected icon set, the result of getDefaultIcon is returned.

Specified by:

getSelectedIcon in interface com.sas.models.NodeIconInterface

Returns:

the selected icon, otherwise the result of getDefaultIcon

See Also:

getDefaultIcon()

getSingleState

public NodeState getSingleState()

Returns the state of the current NodeView object. That state is returned as a NodeState object. The NodeState object will contain values for the selected and expanded properties. If the states of descendants are also wanted, then getState should be called instead.

Returns:

the state of the current NodeView object

See Also:

getState()

getState

public NodeState getState()

Returns the state of the current NodeView object and all descendants. The state is returned as a NodeState object. The NodeState object will contain values for the selected and expanded properties as well as a collection of the states of each child (if children exist). If the state of only the current NodeView object is wanted, then getSingleState should be called instead.

Returns:

the state of the current NodeView object

See Also:

getSingleState()

getVisibleNodeCount

public int getVisibleNodeCount()

Returns the visible node count for the current node. The visible node count is the number of nodes below (and including) the current node in the hierarchy that would be displayed if there were unlimited drawing space. Each node has at least a visible node count of 1, unless the child count is unknown. In this case a node has a visible node count of -1.

Returns:

the visible node count for the current node

isEditing

public boolean isEditing()

Indicates whether the current node is being edited in place or not.

Returns:

true if the current node is being edited, false otherwise

See Also:

setEditing(boolean)

isExpanded

public boolean isExpanded()

Indicates whether the current node is expanded.

Returns:

true if the current node is expanded, otherwise false

See Also:

setExpanded(boolean)

isLeafNode

public boolean isLeafNode()

Indicates if the current NodeView is a leaf (has no children).

Specified by:

isLeafNode in interface com.sas.models.SimpleNodeInterface

Returns:

true if the current node is a leaf, otherwise false

isSelected

public boolean isSelected()

Indicates whether the current node is selected.

Returns:

true if the current node is selected, otherwise false

See Also:

setSelected(boolean)

isVisible

public boolean isVisible()

Returns true if the node is visible and false if it is hidden. This method looks in the node style property bags for the presence of the NodeStyle.VISIBLE property being set. If the NodeStyle.VISIBLE property is not set, true is returned.

Returns:

true if the node is visible, otherwise false

See Also:

NodeStyle

onAction

public void onAction()

Called whenever a node is double-clicked in the viewer.

onSelect

public void onSelect()

Called whenever a node is selected in the viewer.

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent event)

Handles PropertyChangeEvents received by the current node.

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

Parameters:

event - the PropertyChangeEvent to handle

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Remove a listener for the java.beans.PropertyChangeEvent event. Nothing happens if the listener is not in the list of listeners for this event.

Specified by:

removePropertyChangeListener in interface com.sas.beans.PropertyChangeSource

Parameters:

listener - an object which handles PropertyChangeEvent events

See Also:

PropertyChangeSource.removePropertyChangeListener(java.beans.PropertyChangeListener)

repopulate

public void repopulate()

Directs the current node to refresh its child list from its underlying NodeInterface object.

setDefaultNodeStyle

public void setDefaultNodeStyle(com.sas.collection.PropertyBagInterface newValue)

Sets the set of style properties that serve as the defaults for this node and for all of its descendants.

Parameters:

newValue - the new value for the defaultNodeStyle property

See Also:

getDefaultNodeStyle(), getNodeStyle(), setNodeStyle(com.sas.collection.PropertyBagInterface)

setEditing

public void setEditing(boolean newValue)

Directs the current node to enter or exit editing mode. Editing mode is when the text of the node can be edited in place.

Parameters:

newValue - true if the current node is to be edited, false otherwise

See Also:

isEditing()

setExpanded

public void setExpanded(boolean newValue)

Controls whether the current node is expanded or collapsed.

Parameters:

newValue - expands the current node if true, collapses it if false

See Also:

isExpanded()

setNodeStyle

public void setNodeStyle(com.sas.collection.PropertyBagInterface newValue)

Sets the set of style properties that serve as formatting and rendering defaults and hints for this node. There are no style properties by default.

Parameters:

newValue - the new value for the nodeStyle property

See Also:

getNodeStyle(), getDefaultNodeStyle(), setDefaultNodeStyle(com.sas.collection.PropertyBagInterface)

setSelected

public void setSelected(boolean newValue)

Controls whether the current node is selected.

Parameters:

newValue - selects the current node if true, deselects it if false

See Also:

isSelected()

setState

public void setState(NodeState state)

Restores the state of the current NodeView object from the specified NodeState object. If the specified NodeState object contains NodeState objects for the children of the current node, then they will also be restored.

Parameters:

state - the state to restore to the current NodeView object

setVisible

public void setVisible()

Convience method to expand all ancestors. The current node is not necessarily displayed after this call. Visible simply indicates that a node would be drawn if the TreeView which contains this node possessed unlimited drawing space.

toString

public java.lang.String toString()

Returns the displayed text for the current node.

Overrides:

toString in class java.lang.Object

Returns:

the displayed text for the current node.

updateVisibleNodeCount

public void updateVisibleNodeCount()

Directs the current node to update its visible node count. This is also used to signal each ancestor to update its visible node counts

notifyPropertyChange

protected void notifyPropertyChange(java.beans.PropertyChangeEvent event)

Send a PropertyChangeEvent event to all the PropertyChangeListener objects in the listener list. The listener list is copied first, so the event is sent only to each item which is in the list at the time of this copy, even if adds or removes are performed after the send has started.

Parameters:

event - the event to send

supportsCommandsInterface

protected boolean supportsCommandsInterface()

Indicates whether the underlying NodeInterface implements com.sas.util.CommandsInterface.

Returns:

true if CommandsInterface is supported, otherwise false

See Also:

CommandsInterface