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:


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



Copyright © 2009 SAS Institute Inc. All Rights Reserved.