org.apache.pivot.wtk
Class TreeView

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

@DefaultProperty(value="treeData")
public class TreeView
extends Component

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


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
          Renderer interface to customize the appearance of items in a TreeView.
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 org.apache.pivot.wtk.Component
Component.DecoratorSequence, Component.StyleDictionary, Component.UserDataDictionary
 
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
 boolean addSelectedPath(Sequence.Tree.Path path)
          Adds a path to the selection.
 void clear()
          Clears any bound values in the component.
 void clearSelection()
          Clears the selection.
 void collapseAll()
          Collapses all branches in the tree view.
 void collapseBranch(Sequence.Tree.Path path)
          Collapses the branch at the specified path.
 void expandAll()
          Expands all branches in the tree view.
 void expandBranch(Sequence.Tree.Path path)
          Expands the branch at the specified path.
 Sequence<Sequence.Tree.Path> getCheckedPaths()
          Gets the sequence of node paths that are checked.
 boolean getCheckmarksEnabled()
           
 Filter<?> getDisabledCheckmarkFilter()
          Returns the disabled checkmark filter, which determines which checkboxes are interactive and which are not.
 Filter<?> getDisabledNodeFilter()
          Returns the disabled node filter, which determines the disabled state of all nodes.
 Sequence.Tree.Path getFirstSelectedPath()
          Returns the first selected path, as it would appear in a fully expanded tree.
 Sequence.Tree.Path getLastSelectedPath()
          Returns the last selected path, as it would appear in a fully expanded tree.
 Sequence.Tree.Path getNodeAt(int y)
          Gets the path to the node found at the specified y-coordinate (relative to the tree view).
 Bounds getNodeBounds(Sequence.Tree.Path path)
          Gets the bounds of the node at the specified path relative to the tree view.
 TreeView.NodeCheckState getNodeCheckState(Sequence.Tree.Path 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.
 int getRowIndex(Sequence.Tree.Path path)
          Gets the row index of the node, as seen in the current visible nodes list.
 Object getSelectedNode()
           
 Sequence.Tree.Path getSelectedPath()
          Returns the currently selected index, even when in multi-select mode.
 ImmutableList<Sequence.Tree.Path> getSelectedPaths()
          Returns the currently selected paths.
 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.
 String getTreeDataKey()
           
 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.Tree.Path path)
          Tells whether or not the specified branch is expanded.
 boolean isNodeChecked(Sequence.Tree.Path path)
          Tells whether or not the node at the specified path is checked.
 boolean isNodeDisabled(Sequence.Tree.Path path)
          Returns the disabled state of a given node.
 boolean isNodeSelected(Sequence.Tree.Path path)
           
 boolean removeSelectedPath(Sequence.Tree.Path path)
          Removes a path from the selection.
 void setBranchExpanded(Sequence.Tree.Path path, boolean expanded)
          Sets the expansion state of the specified branch.
 void setCheckmarksEnabled(boolean checkmarksEnabled)
          Enables or disables checkmarks.
 void setDisabledCheckmarkFilter(Filter<?> disabledCheckmarkFilter)
          Sets the disabled checkmark filter, which determines which checkboxes are interactive and which are not.
 void setDisabledNodeFilter(Filter<?> disabledNodeFilter)
          Sets the disabled node filter, which determines the disabled state of all nodes.
 void setNodeChecked(Sequence.Tree.Path path, boolean checked)
          Sets the check state of the node at the specified path.
 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.Tree.Path path)
           
 Sequence<Sequence.Tree.Path> setSelectedPaths(Sequence<Sequence.Tree.Path> selectedPaths)
           
 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.
 void setTreeDataKey(String treeDataKey)
           
 
Methods inherited from class org.apache.pivot.wtk.Component
clearFocus, contains, getAncestor, getAncestor, getAttribute, getAutomationID, getBaseline, getBaseline, getBounds, getComponentClassListeners, getComponentDataListeners, getComponentDecoratorListeners, getComponentKeyListeners, getComponentListeners, getComponentMouseButtonListeners, getComponentMouseListeners, getComponentMouseWheelListeners, getComponentStateListeners, getComponentStyleListeners, getComponentTooltipListeners, getCursor, getDecoratedBounds, getDecorators, getDisplay, getDragSource, getDropTarget, getFocusedComponent, getGraphics, getHeight, getHeightLimits, getLocation, getMaximumHeight, getMaximumWidth, getMenuHandler, getMinimumHeight, getMinimumWidth, getMouseLocation, getName, getNamedStyles, getParent, getPreferredHeight, getPreferredHeight, getPreferredSize, getPreferredWidth, getPreferredWidth, getSize, getSkin, getStyles, getTooltipDelay, getTooltipText, getTooltipWrapText, getTypedStyles, getUserData, getVisibleArea, getVisibleArea, getVisibleArea, getWidth, getWidthLimits, getWindow, getX, getY, indexBoundsCheck, installSkin, invalidate, isBlocked, isEnabled, isFocusable, isFocused, isMouseOver, isOpaque, isPreferredHeightSet, isPreferredSizeSet, isPreferredWidthSet, isShowing, isValid, isVisible, keyPressed, keyReleased, keyTyped, layout, load, mapPointFromAncestor, mapPointFromAncestor, mapPointToAncestor, mapPointToAncestor, mouseClick, mouseDown, mouseMove, mouseOut, mouseOver, mouseUp, mouseWheel, paint, reenterMouse, repaint, repaint, repaint, repaint, repaint, repaint, requestFocus, scrollAreaToVisible, scrollAreaToVisible, setAttribute, setAutomationID, setCursor, setDragSource, setDropTarget, setEnabled, setFocused, setHeight, setHeightLimits, setHeightLimits, setLocation, setLocation, setMaximumHeight, setMaximumWidth, setMenuHandler, setMinimumHeight, setMinimumWidth, setName, setParent, setPreferredHeight, setPreferredSize, setPreferredSize, setPreferredWidth, setSize, setSize, setStyleName, setStyleNames, setStyleNames, setStyles, setStyles, setTooltipDelay, setTooltipText, setTooltipWrapText, setVisible, setWidth, setWidthLimits, setWidthLimits, setX, setY, store, toString, transferFocus, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, 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, 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

getSelectedPaths

public ImmutableList<Sequence.Tree.Path> getSelectedPaths()
Returns the currently selected paths.

Returns:
An immutable list containing the currently selected paths. Note that the returned list is a wrapper around the actual selection, not a copy. Any changes made to the selection state will be reflected in the list, but events will not be fired.

setSelectedPaths

public Sequence<Sequence.Tree.Path> setSelectedPaths(Sequence<Sequence.Tree.Path> selectedPaths)
Throws:
IllegalStateException - If selection has been disabled (select mode NONE).

getFirstSelectedPath

public Sequence.Tree.Path 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.Tree.Path 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.Tree.Path getSelectedPath()
Returns the currently selected index, even when in multi-select mode.

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

setSelectedPath

public void setSelectedPath(Sequence.Tree.Path path)

getSelectedNode

public 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 boolean addSelectedPath(Sequence.Tree.Path path)
Adds a path to the selection.

Parameters:
path -
Returns:
true if the path was added to the selection; false, otherwise.
Throws:
IllegalStateException - If multi-select is not enabled.

removeSelectedPath

public boolean removeSelectedPath(Sequence.Tree.Path path)
Removes a path from the selection.

Parameters:
path -
Returns:
true if the path was added to the selection; false, otherwise.
Throws:
IllegalStateException - If multi-select is not enabled.

getTreeDataKey

public String getTreeDataKey()

setTreeDataKey

public void setTreeDataKey(String treeDataKey)

clear

public void clear()
Description copied from class: Component
Clears any bound values in the component.

Overrides:
clear in class Component

clearSelection

public void clearSelection()
Clears the selection.


isNodeSelected

public boolean isNodeSelected(Sequence.Tree.Path path)

isNodeDisabled

public boolean isNodeDisabled(Sequence.Tree.Path 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

getDisabledNodeFilter

public Filter<?> getDisabledNodeFilter()
Returns the disabled node filter, which determines the disabled state of all nodes. Disabled nodes are not interactive to the user. Note, however, that disabled nodes may still be expanded, selected, and checked programatically. A disabled node may have enabled children.

If the disabled node filter is set to null, all nodes are enabled.

Returns:
The disabled node filter, or null if no disabled node filter is set

setDisabledNodeFilter

public void setDisabledNodeFilter(Filter<?> disabledNodeFilter)
Sets the disabled node filter, which determines the disabled state of all nodes. Disabled nodes are not interactive to the user. Note, however, that disabled nodes may still be expanded, selected, and checked programatically. A disabled node may have enabled children.

If the disabled node filter is set to null, all nodes are enabled.

Parameters:
disabledNodeFilter - The disabled node filter, or null for no disabled node filter

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.Tree.Path 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.Tree.Path 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.Tree.Path 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:
IllegalStateException - If checkmarks are not enabled (see getCheckmarksEnabled()).
See Also:
TreeView.NodeCheckState.MIXED

getCheckedPaths

public Sequence<Sequence.Tree.Path> 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.

getDisabledCheckmarkFilter

public Filter<?> getDisabledCheckmarkFilter()
Returns the disabled checkmark filter, which determines which checkboxes are interactive and which are not. Note that this filter only affects user interaction; nodes may still be checked programatically despite their inclusion in this filter. If this filter is set to null, all checkboxes will be interactive.

Note: this filter is only relavent if checkmarksEnabled is set to true.

Returns:
The disabled checkmark filter, or null if no disabled checkmark filter is set

setDisabledCheckmarkFilter

public void setDisabledCheckmarkFilter(Filter<?> disabledCheckmarkFilter)
Sets the disabled checkmark filter, which determines which checkboxes are interactive and which are not. Note that this filter only affects user interaction; nodes may still be checked programatically despite their inclusion in this filter. If this filter is set to null, all checkboxes will be interactive.

Note: this filter is only relavent if checkmarksEnabled is set to true. enabled.

Parameters:
disabledCheckmarkFilter - The disabled checkmark filter, or null for no disabled checkmark filter

setBranchExpanded

public void setBranchExpanded(Sequence.Tree.Path 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.Tree.Path 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.Tree.Path path)
Expands the branch at the specified path. If the branch is already expanded, nothing happens.

Parameters:
path - The path to the branch node.

expandAll

public final void expandAll()
Expands all branches in the tree view.


collapseBranch

public final void collapseBranch(Sequence.Tree.Path path)
Collapses the branch at the specified path. If the branch is already collapsed, nothing happens.

Parameters:
path - The path to the branch node.

collapseAll

public final void collapseAll()
Collapses all branches in the tree view.


getNodeAt

public Sequence.Tree.Path 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.Tree.Path 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.

getRowIndex

public int getRowIndex(Sequence.Tree.Path path)
Gets the row index of the node, as seen in the current visible nodes list. Note that as branches are expanded and collapsed, the row index of any given node in the tree will change.

Parameters:
path - The path to the node.
Returns:
The row index of the node, or -1 if the node is not currently visible.

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.