pivot.wtk
Class TreeView

java.lang.Object
  extended by pivot.wtk.Component
      extended by pivot.wtk.TreeView
All Implemented Interfaces:
ConstrainedVisual, Visual

public class TreeView
extends Component

Class that displays a hierarchical data structure, allowing a user to select one or more paths.

Author:
tvolkert

Nested Class Summary
static class TreeView.NodeCheckState
          Enumeration defining node check states.
static interface TreeView.NodeEditor
          Tree view node editor interface.
static interface TreeView.NodeRenderer
          Tree view node renderer interface.
static class TreeView.PathComparator
          A comparator that sorts paths by the order in which they would visually appear in a fully expanded tree, otherwise known as their "row order".
static class TreeView.SelectMode
          Enumeration defining supported selection modes.
static interface TreeView.Skin
          Tree view skin interface.
 
Nested classes/interfaces inherited from class pivot.wtk.Component
Component.Attributes, Component.ComponentDictionary, Component.DecoratorSequence, Component.StyleDictionary
 
Constructor Summary
TreeView()
          Creates a new TreeView with empty tree data.
TreeView(List<?> treeData)
          Creates a new TreeView with the specified tree data.
 
Method Summary
 void addSelectedPath(Sequence<java.lang.Integer> path)
           
 void clearSelection()
           
 void collapseBranch(Sequence<java.lang.Integer> path)
          Collapses the branch at the specified path.
 void expandBranch(Sequence<java.lang.Integer> path)
          Expands the branch at the specified path.
 Sequence<Sequence<java.lang.Integer>> getCheckedPaths()
          Gets the sequence of node paths that are checked.
 boolean getCheckmarksEnabled()
           
 Sequence<Sequence<java.lang.Integer>> getDisabledPaths()
           
 Sequence<java.lang.Integer> getFirstSelectedPath()
          Returns the first selected path, as it would appear in a fully expanded tree.
 Sequence<java.lang.Integer> getLastSelectedPath()
          Returns the last selected path, as it would appear in a fully expanded tree.
 Sequence<java.lang.Integer> getNodeAt(int y)
          Gets the path to the node found at the specified y-coordinate (relative to the tree view).
 Bounds getNodeBounds(Sequence<java.lang.Integer> path)
          Gets the bounds of the node at the specified path relative to the tree view.
 TreeView.NodeCheckState getNodeCheckState(Sequence<java.lang.Integer> path)
          Returns the checkmark state of the node at the specified path.
 TreeView.NodeEditor getNodeEditor()
          Returns the editor used to edit nodes in this tree.
 int getNodeIndent(int depth)
          Gets the pixel indent of nodes at the specified depth.
 TreeView.NodeRenderer getNodeRenderer()
          Gets the tree view's node renderer, which is responsible for the appearance of the node data.
 java.lang.Object getSelectedNode()
           
 Sequence<java.lang.Integer> getSelectedPath()
           
 Sequence<Sequence<java.lang.Integer>> getSelectedPaths()
           
 TreeView.SelectMode getSelectMode()
          Returns the current selection mode.
 boolean getShowMixedCheckmarkState()
          Tells whether or not the mixed check state will be reported by this tree view.
 List<?> getTreeData()
          Returns the tree view's data model.
 ListenerList<TreeViewBranchListener> getTreeViewBranchListeners()
          Gets the TreeViewBranchListeners.
 ListenerList<TreeViewListener> getTreeViewListeners()
          Gets the TreeViewListeners.
 ListenerList<TreeViewNodeListener> getTreeViewNodeListeners()
          Gets the TreeViewNodeListeners.
 ListenerList<TreeViewNodeStateListener> getTreeViewNodeStateListeners()
          Gets the TreeViewNodeStateListeners.
 ListenerList<TreeViewSelectionListener> getTreeViewSelectionListeners()
          Gets the TreeViewSelectionListeners.
 boolean isBranchExpanded(Sequence<java.lang.Integer> path)
          Tells whether or not the specified branch is expanded.
 boolean isNodeChecked(Sequence<java.lang.Integer> path)
          Tells whether or not the node at the specified path is checked.
 boolean isNodeDisabled(Sequence<java.lang.Integer> path)
          Returns the disabled state of a given node.
 boolean isNodeSelected(Sequence<java.lang.Integer> path)
           
 void removeSelectedPath(Sequence<java.lang.Integer> path)
           
 void setBranchExpanded(Sequence<java.lang.Integer> path, boolean expanded)
          Sets the expansion state of the specified branch.
 void setCheckmarksEnabled(boolean checkmarksEnabled)
          Enables or disables checkmarks.
 void setNodeChecked(Sequence<java.lang.Integer> path, boolean checked)
          Sets the check state of the node at the specified path.
 void setNodeDisabled(Sequence<java.lang.Integer> path, boolean disabled)
          Sets the disabled state of a node.
 void setNodeEditor(TreeView.NodeEditor nodeEditor)
          Sets the editor used to edit nodes in this tree.
 void setNodeRenderer(TreeView.NodeRenderer nodeRenderer)
          Sets the tree view's node renderer, which is responsible for the appearance of the node data.
 void setSelectedPath(Sequence<java.lang.Integer> path)
           
 void setSelectedPaths(Sequence<Sequence<java.lang.Integer>> selectedPaths)
           
 void setSelectMode(java.lang.String selectMode)
          Sets the selection mode.
 void setSelectMode(TreeView.SelectMode selectMode)
          Sets the selection mode.
 void setShowMixedCheckmarkState(boolean showMixedCheckmarkState)
          Sets whether or not the "mixed" check state will be reported by this tree view.
protected  void setSkin(Skin skin)
          Sets the skin, replacing any previous skin.
 void setTreeData(List<?> treeData)
          Sets the tree data.
 
Methods inherited from class pivot.wtk.Component
clearFocus, clearFocus, finalize, getAttributes, getBounds, getComponentClassListeners, getComponentDataListeners, getComponentDecoratorListeners, getComponentDragDropListeners, getComponentKeyListeners, getComponentLayoutListeners, getComponentListeners, getComponentMouseButtonListeners, getComponentMouseListeners, getComponentMouseWheelListeners, getComponents, getComponentStateListeners, getCursor, getDecoratedBounds, getDecorators, getDisplay, getDragSource, getDropTarget, getFocusedComponent, getHandle, getHeight, getLocation, getParent, getPreferredHeight, getPreferredHeight, getPreferredSize, getPreferredWidth, getPreferredWidth, getSize, getSkin, getStyles, getTooltipText, getUserData, getVisibleArea, getVisibleArea, getVisibleArea, getWidth, getWindow, getX, getY, installSkin, invalidate, isBlocked, isDisplayable, isEnabled, isFocusable, isFocused, isMouseOver, isPreferredHeightSet, isPreferredSizeSet, isPreferredWidthSet, isShowing, isValid, isVisible, keyPressed, keyReleased, keyTyped, load, mapPointFromAncestor, mapPointToAncestor, mouseClick, mouseDown, mouseMove, mouseOut, mouseOver, mouseUp, mouseWheel, paint, repaint, repaint, repaint, repaint, repaint, repaint, requestFocus, requestFocus, scrollAreaToVisible, scrollAreaToVisible, setAttributes, setCursor, setCursor, setDisplayable, setDragSource, setDropTarget, setEnabled, setFocused, setLocation, setLocation, setParent, setPreferredHeight, setPreferredSize, setPreferredSize, setPreferredWidth, setSize, setSize, setStyles, setStyles, setStyles, setTooltipText, setUserData, setVisible, store, toString, transferFocus, validate
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TreeView

public TreeView()
Creates a new TreeView with empty tree data.


TreeView

public TreeView(List<?> treeData)
Creates a new TreeView with the specified tree data.

Parameters:
treeData - Default data set to be used with the tree. This list represents the root set of items displayed by the tree and will never itself be painted. Sub-items that also implement the List interface are considered branches; other items are considered leaves.
See Also:
setTreeData(List)
Method Detail

setSkin

protected void setSkin(Skin skin)
Sets the skin, replacing any previous skin. This ensures that the skin being set implements the TreeView.Skin interface.

Overrides:
setSkin in class Component
Parameters:
skin - The new skin.

getTreeData

public List<?> getTreeData()
Returns the tree view's data model. This list represents the root set of items displayed by the tree and will never itself be painted. Sub-items that also implement the List interface are considered branches; other items are considered leaves.

For instance, a tree view that displays a single root branch would be backed by list with one child (also a list).

Returns:
The tree view's data model.

setTreeData

public void setTreeData(List<?> treeData)
Sets the tree data. Note that it is the responsibility of the caller to ensure that the current tree node renderer is capable of displaying the contents of the tree structure. By default, an instance of TreeViewNodeRenderer is used.

When the tree data is changed, the state of all nodes (expansion, selection, disabled, and checked) will be cleared since the nodes themselves are being replaced. Note that corresponding events will not be fired, since these actions are implied by the treeDataChanged event.

Parameters:
treeData - The data to be presented by the tree.

getNodeRenderer

public TreeView.NodeRenderer getNodeRenderer()
Gets the tree view's node renderer, which is responsible for the appearance of the node data. As such, note that there is an implied coordination between the node renderer and the data model. The default node renderer used is an instance of TreeViewNodeRenderer.

Returns:
The current node renderer.
See Also:
TreeViewNodeRenderer

setNodeRenderer

public void setNodeRenderer(TreeView.NodeRenderer nodeRenderer)
Sets the tree view's node renderer, which is responsible for the appearance of the node data.

Parameters:
nodeRenderer - The new node renderer.

getNodeEditor

public TreeView.NodeEditor getNodeEditor()
Returns the editor used to edit nodes in this tree.

Returns:
The node editor, or null if no editor is installed.

setNodeEditor

public void setNodeEditor(TreeView.NodeEditor nodeEditor)
Sets the editor used to edit nodes in this tree.

Parameters:
nodeEditor - The node editor for the tree.

getSelectMode

public TreeView.SelectMode getSelectMode()
Returns the current selection mode.

Returns:
The current selection mode.

setSelectMode

public void setSelectMode(TreeView.SelectMode selectMode)
Sets the selection mode. Clears the selection if the mode has changed. Note that if the selection is cleared, selection listeners will not be notified, as the clearing of the selection is implied by the selectModeChanged event.

Parameters:
selectMode - The new selection mode.
See Also:
TreeViewListener, TreeViewSelectionListener

setSelectMode

public final void setSelectMode(java.lang.String selectMode)
Sets the selection mode.

Parameters:
selectMode - The new selection mode.
See Also:
setSelectMode(SelectMode)

getSelectedPaths

public Sequence<Sequence<java.lang.Integer>> getSelectedPaths()

setSelectedPaths

public void setSelectedPaths(Sequence<Sequence<java.lang.Integer>> selectedPaths)
Throws:
java.lang.IllegalStateException - If selection has been disabled (select mode NONE).

getFirstSelectedPath

public Sequence<java.lang.Integer> getFirstSelectedPath()
Returns the first selected path, as it would appear in a fully expanded tree.

Returns:
The first selected path, or null if nothing is selected.

getLastSelectedPath

public Sequence<java.lang.Integer> getLastSelectedPath()
Returns the last selected path, as it would appear in a fully expanded tree.

Returns:
The last selected path, or null if nothing is selected.

getSelectedPath

public Sequence<java.lang.Integer> getSelectedPath()
Returns:
The selected path, or null if nothing is selected.
Throws:
java.lang.IllegalStateException - If the tree view is not in single-select mode.

setSelectedPath

public void setSelectedPath(Sequence<java.lang.Integer> path)

getSelectedNode

public java.lang.Object getSelectedNode()
Returns:
The selected object, or null if nothing is selected. Note that technically, the selected path could be backed by a null data value. If the caller wishes to distinguish between these cases, they can use getSelectedPath() instead.

addSelectedPath

public void addSelectedPath(Sequence<java.lang.Integer> path)
Throws:
java.lang.IllegalStateException - If multi-select is not enabled.

removeSelectedPath

public void removeSelectedPath(Sequence<java.lang.Integer> path)
Throws:
java.lang.IllegalStateException - If multi-select is not enabled.

clearSelection

public void clearSelection()

isNodeSelected

public boolean isNodeSelected(Sequence<java.lang.Integer> path)

isNodeDisabled

public boolean isNodeDisabled(Sequence<java.lang.Integer> path)
Returns the disabled state of a given node.

Parameters:
path - The path to the node whose disabled state is to be tested
Returns:
true if the node is disabled; false, otherwise

setNodeDisabled

public void setNodeDisabled(Sequence<java.lang.Integer> path,
                            boolean disabled)
Sets the disabled state of a node. A disabled node is not interactive to the user. Note, however, that disabled nodes may still be expanded, selected, and checked programatically. Disabling a node does not disable its children.

Parameters:
path - The path to the node.
disabled - true to disable the node; false to enable it.

getDisabledPaths

public Sequence<Sequence<java.lang.Integer>> getDisabledPaths()

getCheckmarksEnabled

public boolean getCheckmarksEnabled()

setCheckmarksEnabled

public void setCheckmarksEnabled(boolean checkmarksEnabled)
Enables or disables checkmarks. If checkmarks are being disabled, all checked nodes will be automatically unchecked. Note that the corresponding event will not be fired, since the clearing of existing checkmarks is implied by the checkmarksEnabledChanged event.

Parameters:
checkmarksEnabled - true to enable checkmarks; false to disable them.

getShowMixedCheckmarkState

public boolean getShowMixedCheckmarkState()
Tells whether or not the mixed check state will be reported by this tree view. This state is a derived state meaning "the node is not checked, but one or more of its descendants are." When this state is configured to not be shown, such nodes will simply be reported as unchecked.

Returns:
true if the tree view will report so-called mixed nodes as mixed; false if it will report them as unchecked.
See Also:
TreeView.NodeCheckState.MIXED

setShowMixedCheckmarkState

public void setShowMixedCheckmarkState(boolean showMixedCheckmarkState)
Sets whether or not the "mixed" check state will be reported by this tree view. This state is a derived state meaning "the node is not checked, but one or more of its descendants are." When this state is configured to not be shown, such nodes will simply be reported as unchecked.

Changing this flag may result in some nodes changing their reported check state. Note that the corresponding nodeCheckStateChanged events will not be fired, since the possibility of such a change in check state is implied by the showMixedCheckmarkStateChanged event.

Parameters:
showMixedCheckmarkState - true to show the derived mixed state; false to report so-called "mixed" nodes as unchecked.
See Also:
TreeView.NodeCheckState.MIXED

isNodeChecked

public boolean isNodeChecked(Sequence<java.lang.Integer> path)
Tells whether or not the node at the specified path is checked. If checkmarks are not enabled, this is guaranteed to be false. So called mixed nodes will always be reported as unchecked in this method.

Parameters:
path - The path to the node.
Returns:
true if the node is explicitly checked; false otherwise.
See Also:
getCheckmarksEnabled()

getNodeCheckState

public TreeView.NodeCheckState getNodeCheckState(Sequence<java.lang.Integer> path)
Returns the checkmark state of the node at the specified path. If checkmarks are not enabled, this is guaranteed to be UNCHECKED.

Note that the MIXED check state (meaning "the node is not checked, but one or more of its descendants are") is only reported when the tree view is configured as such. Otherwise, such nodes will be reported as UNCHECKED.

Parameters:
path - The path to the node.
Returns:
The checkmark state of the specified node.
See Also:
getCheckmarksEnabled(), setShowMixedCheckmarkState(boolean)

setNodeChecked

public void setNodeChecked(Sequence<java.lang.Integer> path,
                           boolean checked)
Sets the check state of the node at the specified path. If the node already has the specified check state, nothing happens.

Note that it is impossible to set the check state of a node to MIXED. This is because the mixed check state is a derived state meaning "the node is not checked, but one or more of its descendants are."

Parameters:
path - The path to the node.
checked - true to check the node; false to uncheck it.
Throws:
java.lang.IllegalStateException - If checkmarks are not enabled (see getCheckmarksEnabled()).
See Also:
TreeView.NodeCheckState.MIXED

getCheckedPaths

public Sequence<Sequence<java.lang.Integer>> getCheckedPaths()
Gets the sequence of node paths that are checked. If checkmarks are not enabled (see getCheckmarksEnabled()), this is guaranteed to return an empty sequence.

Note that if the tree view is configured to show mixed checkmark states (see getShowMixedCheckmarkState()), this will still only return the nodes that are fully checked.

Returns:
The paths to the checked nodes in the tree, guaranteed to be non-null.

setBranchExpanded

public void setBranchExpanded(Sequence<java.lang.Integer> path,
                              boolean expanded)
Sets the expansion state of the specified branch. If the branch already has the specified expansion state, nothing happens.

Parameters:
path - The path to the branch node.
expanded - true to expand the branch; false to collapse it.

isBranchExpanded

public boolean isBranchExpanded(Sequence<java.lang.Integer> path)
Tells whether or not the specified branch is expanded.

Parameters:
path - The path to the branch node.
Returns:
true if the branch is expanded; false otherwise.

expandBranch

public final void expandBranch(Sequence<java.lang.Integer> path)
Expands the branch at the specified path. If the branch is already expanded, nothing happens.

Parameters:
path - The path to the branch node.

collapseBranch

public final void collapseBranch(Sequence<java.lang.Integer> path)
Collapses the branch at the specified path. If the branch is already collapsed, nothing happens.

Parameters:
path - The path to the branch node.

getNodeAt

public Sequence<java.lang.Integer> getNodeAt(int y)
Gets the path to the node found at the specified y-coordinate (relative to the tree view).

Parameters:
y - The y-coordinate in pixels.
Returns:
The path to the node, or null if there is no node being painted at the specified y-coordinate.

getNodeBounds

public Bounds getNodeBounds(Sequence<java.lang.Integer> path)
Gets the bounds of the node at the specified path relative to the tree view. Note that all nodes are left aligned with the tree; to get the pixel value of a node's indent, use getNodeIndent(int).

Parameters:
path - The path to the node.
Returns:
The bounds, or null if the node is not currently visible.

getNodeIndent

public int getNodeIndent(int depth)
Gets the pixel indent of nodes at the specified depth. Depth is measured in generations away from the tree view's "root" node, which is represented by the tree data.

Parameters:
depth - The depth, where the first child of the root has depth 1, the child of that branch has depth 2, etc.
Returns:
The indent in pixels.

getTreeViewListeners

public ListenerList<TreeViewListener> getTreeViewListeners()
Gets the TreeViewListeners. Developers interested in these events can register for notification on these events by adding themselves to the listener list.

Returns:
The tree view listeners.

getTreeViewBranchListeners

public ListenerList<TreeViewBranchListener> getTreeViewBranchListeners()
Gets the TreeViewBranchListeners. Developers interested in these events can register for notification on these events by adding themselves to the listener list.

Returns:
The tree view branch listeners.

getTreeViewNodeListeners

public ListenerList<TreeViewNodeListener> getTreeViewNodeListeners()
Gets the TreeViewNodeListeners. Developers interested in these events can register for notification on these events by adding themselves to the listener list.

Returns:
The tree view node listeners.

getTreeViewNodeStateListeners

public ListenerList<TreeViewNodeStateListener> getTreeViewNodeStateListeners()
Gets the TreeViewNodeStateListeners. Developers interested in these events can register for notification on these events by adding themselves to the listener list.

Returns:
The tree view node state listeners.

getTreeViewSelectionListeners

public ListenerList<TreeViewSelectionListener> getTreeViewSelectionListeners()
Gets the TreeViewSelectionListeners. Developers interested in these events can register for notification on these events by adding themselves to the listener list.

Returns:
The tree view selection listeners.