Package org.apache.pivot.wtk

Class TreeView

    • 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)
        Set the new selected nodes in the tree.
        Parameters:
        selectedPaths - The new set of paths to the selected nodes.
        Returns:
        The new set of selected paths (with duplicates eliminated).
        Throws:
        java.lang.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)
        Set the single selected path.
        Parameters:
        path - The new path to select.

      • 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 boolean addSelectedPath​(Sequence.Tree.Path path)
        Adds a path to the selection.
        Parameters:
        path - The path to the node to be added to the selection.
        Returns:
        true if the path was added to the selection; false, otherwise.
        Throws:
        java.lang.IllegalStateException - If multi-select is not enabled.

      • removeSelectedPath

        public boolean removeSelectedPath​(Sequence.Tree.Path path)
        Removes a path from the selection.
        Parameters:
        path - Path to the node to be removed from the selection.
        Returns:
        true if the path was removed from the selection; false, otherwise.
        Throws:
        java.lang.IllegalStateException - If multi-select is not enabled.

      • getTreeDataKey

        public java.lang.String getTreeDataKey()

      • setTreeDataKey

        public void setTreeDataKey​(java.lang.String treeDataKey)

      • clear

        public void clear()
        Description copied from class: Component
        Clears any bound values in the component. This functionality must be provided by the subclass; the base implementation is a no-op.
        Overrides:
        clear in class Component

      • clearSelection

        public void clearSelection()
        Clears the selection.

      • isNodeSelected

        public boolean isNodeSelected​(Sequence.Tree.Path path)
        Parameters:
        path - Path to the node to check.
        Returns:
        Whether or not the node at the given path is part of the current selection.

      • 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()
        Returns:
        Whether or not the checkmarks on each node are enabled.

      • 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:
        java.lang.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.

        The listeners are polled first to give them a chance to veto the operation for any reason. If the vote passes, then the state is changed.

        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.

      • expandToBranch

        public final void expandToBranch​(Sequence.Tree.Path path)
        Expand "to" the given branch, which means opening up all the parents so that this branch is exposed.
        Parameters:
        path - The path to the branch to expose.

      • 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.