org.apache.pivot.wtk.TreeView Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of pivot-wtk Show documentation
Apache Pivot WTK Library
The newest version!
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to you under the Apache License,
 * Version 2.0 (the "License"); you may not use this file except in
 * compliance with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.pivot.wtk;

import java.io.Serializable;
import java.util.Comparator;

import org.apache.pivot.beans.DefaultProperty;
import org.apache.pivot.collections.ArrayList;
import org.apache.pivot.collections.List;
import org.apache.pivot.collections.ListListener;
import org.apache.pivot.collections.Sequence;
import org.apache.pivot.collections.Sequence.Tree.ImmutablePath;
import org.apache.pivot.collections.Sequence.Tree.Path;
import org.apache.pivot.collections.immutable.ImmutableList;
import org.apache.pivot.util.Filter;
import org.apache.pivot.util.ListenerList;
import org.apache.pivot.wtk.content.TreeViewNodeRenderer;

/**
 * Class that displays a hierarchical data structure, allowing a user to select
 * one or more paths.
 */
@DefaultProperty("treeData")
public class TreeView extends Component {
    /**
     * Enumeration defining supported selection modes. TreeView
     * defaults to single select mode.
     */
    public enum SelectMode {
        /**
         * Selection is disabled.
         */
        NONE,

        /**
         * A single path may be selected at a time.
         */
        SINGLE,

        /**
         * Multiple paths may be concurrently selected.
         */
        MULTI
    }

    /**
     * Enumeration defining node check states. Note that TreeView does
     * not involve itself in the propagation of checkmarks (either up or down
     * the tree). Developers who wish to propagate checkmarks may do so by
     * registering a {@link TreeViewNodeStateListener} and setting the desired
     * checkmark states manually.
     */
    public enum NodeCheckState {
        /**
         * The node is checked.
         */
        CHECKED,

        /**
         * The node is unchecked. If showMixedCheckmarkState is true,
         * this implies that all of the node's descendants are unchecked as
         * well.
         */
        UNCHECKED,

        /**
         * The node's check state is mixed, meaning that it is not checked,
         * but at least one of its descendants is checked. This state will only
         * be reported if showMixedCheckmarkState is true. Otherwise,
         * the node will be reported as {@link #UNCHECKED}.
         */
        MIXED
    }

    /**
     * {@link Renderer} interface to customize the appearance of items in a TreeView.
     */
    public interface NodeRenderer extends Renderer {
        /**
         * Prepares the renderer for layout or paint.
         *
         * @param node
         * The node value to render, or null if called to calculate
         * preferred height for skins that assume a fixed renderer height.
         *
         * @param path
         * The path to the node being rendered, or null if
         * node is null.
         *
         * @param rowIndex
         * The row index of the node being rendered, as seen in the current
         * visible nodes list, or -1 if node is null.
         *
         * @param treeView
         * The host component.
         *
         * @param expanded
         * true if the node is expanded; false otherwise.
         *
         * @param selected
         * true if the node is selected; false otherwise.
         *
         * @param checkState
         * The node's {@linkplain NodeCheckState check state}.
         *
         * @param highlighted
         * true if the node is highlighted; false otherwise.
         *
         * @param disabled
         * true if the node is disabled; false otherwise.
         */
        public void render(Object node, Path path, int rowIndex, TreeView treeView,
            boolean expanded, boolean selected, NodeCheckState checkState,
            boolean highlighted, boolean disabled);

        /**
         * Converts a tree node to a string representation.
         *
         * @param node
         *
         * @return
         * The node's string representation, or null if the node does not
         * have a string representation.
         * 
         * Note that this method may be called often during keyboard navigation, so
         * implementations should avoid unnecessary string allocations.
         */
        public String toString(Object node);
    }

    /**
     * Tree view node editor interface.
     */
    public interface NodeEditor {
        /**
         * Called to begin editing a tree node.
         *
         * @param treeView
         * @param path
         */
        public void beginEdit(TreeView treeView, Path path);

        /**
         * Terminates an edit operation.
         *
         * @param result
         * true to perform the edit; false to cancel it.
         */
        public void endEdit(boolean result);

        /**
         * Tests whether an edit is currently in progress.
         */
        public boolean isEditing();
    }

    /**
     * Tree view skin interface. Tree view skins must implement this.
     */
    public interface Skin {
        /**
         * Gets the path to the node found at the specified y-coordinate
         * (relative to the tree view).
         *
         * @param y
         * The y-coordinate in pixels.
         *
         * @return
         * The path to the node, or null if there is no node being
         * painted at the specified y-coordinate.
         */
        public Path getNodeAt(int y);

        /**
         * 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
         * {@link #getNodeIndent(int)}.
         *
         * @param path
         * The path to the node.
         *
         * @return
         * The bounds, or null if the node is not currently visible.
         */
        public Bounds getNodeBounds(Path path);

        /**
         * 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 {@link #getTreeData() tree data}.
         *
         * @param depth
         * The depth, where the first child of the root has depth 1, the child
         * of that branch has depth 2, etc.
         *
         * @return
         * The indent in pixels to the node's content.
         */
        public int getNodeIndent(int depth);

        /**
         * 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.
         *
         * @param path
         * The path to the node.
         *
         * @return
         * The row index of the node, or -1 if the node is not
         * currently visible.
         */
        public int getRowIndex(Path path);
    }

    /**
     * Tree view listener list.
     */
    private static class TreeViewListenerList extends WTKListenerList
        implements TreeViewListener {

        @Override
        public void treeDataChanged(TreeView treeView, List previousTreeData) {
            for (TreeViewListener listener : this) {
                listener.treeDataChanged(treeView, previousTreeData);
            }
        }

        @Override
        public void nodeRendererChanged(TreeView treeView,
            NodeRenderer previousNodeRenderer) {
            for (TreeViewListener listener : this) {
                listener.nodeRendererChanged(treeView, previousNodeRenderer);
            }
        }

        @Override
        public void nodeEditorChanged(TreeView treeView,
            TreeView.NodeEditor previousNodeEditor) {
            for (TreeViewListener listener : this) {
                listener.nodeEditorChanged(treeView, previousNodeEditor);
            }
        }

        @Override
        public void selectModeChanged(TreeView treeView, SelectMode previousSelectMode) {
            for (TreeViewListener listener : this) {
                listener.selectModeChanged(treeView, previousSelectMode);
            }
        }

        @Override
        public void checkmarksEnabledChanged(TreeView treeView) {
            for (TreeViewListener listener : this) {
                listener.checkmarksEnabledChanged(treeView);
            }
        }

        @Override
        public void showMixedCheckmarkStateChanged(TreeView treeView) {
            for (TreeViewListener listener : this) {
                listener.showMixedCheckmarkStateChanged(treeView);
            }
        }

        @Override
        public void disabledNodeFilterChanged(TreeView treeView,
            Filter previousDisabledNodeFilter) {
            for (TreeViewListener listener : this) {
                listener.disabledNodeFilterChanged(treeView, previousDisabledNodeFilter);
            }
        }

        @Override
        public void disabledCheckmarkFilterChanged(TreeView treeView,
            Filter previousDisabledCheckmarkFilter) {
            for (TreeViewListener listener : this) {
                listener.disabledCheckmarkFilterChanged(treeView, previousDisabledCheckmarkFilter);
            }
        }
    }

    /**
     * Tree view branch listener list.
     */
    private static class TreeViewBranchListenerList extends WTKListenerList
        implements TreeViewBranchListener {
        @Override
        public void branchExpanded(TreeView treeView, Path path) {
            for (TreeViewBranchListener listener : this) {
                listener.branchExpanded(treeView, path);
            }
        }

        @Override
        public void branchCollapsed(TreeView treeView, Path path) {
            for (TreeViewBranchListener listener : this) {
                listener.branchCollapsed(treeView, path);
            }
        }
    }

    /**
     * Tree view node listener list.
     */
    private static class TreeViewNodeListenerList extends WTKListenerList
        implements TreeViewNodeListener {
        @Override
        public void nodeInserted(TreeView treeView, Path path, int index) {
            for (TreeViewNodeListener listener : this) {
                listener.nodeInserted(treeView, path, index);
            }
        }

        @Override
        public void nodesRemoved(TreeView treeView, Path path, int index,
            int count) {
            for (TreeViewNodeListener listener : this) {
                listener.nodesRemoved(treeView, path, index, count);
            }
        }

        @Override
        public void nodeUpdated(TreeView treeView, Path path, int index) {
            for (TreeViewNodeListener listener : this) {
                listener.nodeUpdated(treeView, path, index);
            }
        }

        @Override
        public void nodesCleared(TreeView treeView, Path path) {
            for (TreeViewNodeListener listener : this) {
                listener.nodesCleared(treeView, path);
            }
        }

        @Override
        public void nodesSorted(TreeView treeView, Path path) {
            for (TreeViewNodeListener listener : this) {
                listener.nodesSorted(treeView, path);
            }
        }
    }

    /**
     * Tree view node state listener list.
     */
    private static class TreeViewNodeStateListenerList
        extends WTKListenerList
        implements TreeViewNodeStateListener {
        @Override
        public void nodeCheckStateChanged(TreeView treeView, Path path,
            TreeView.NodeCheckState previousCheckState) {
            for (TreeViewNodeStateListener listener : this) {
                listener.nodeCheckStateChanged(treeView, path, previousCheckState);
            }
        }
    }

    /**
     * Tree view selection listener list.
     */
    private static class TreeViewSelectionListenerList
        extends WTKListenerList
        implements TreeViewSelectionListener {
        @Override
        public void selectedPathAdded(TreeView treeView, Path path) {
            for (TreeViewSelectionListener listener : this) {
                listener.selectedPathAdded(treeView, path);
            }
        }

        @Override
        public void selectedPathRemoved(TreeView treeView, Path path) {
            for (TreeViewSelectionListener listener : this) {
                listener.selectedPathRemoved(treeView, path);
            }
        }

        @Override
        public void selectedPathsChanged(TreeView treeView,
            Sequence previousSelectedPaths) {
            for (TreeViewSelectionListener listener : this) {
                listener.selectedPathsChanged(treeView, previousSelectedPaths);
            }
        }

        @Override
        public void selectedNodeChanged(TreeView treeView, Object previousSelectedNode) {
            for (TreeViewSelectionListener listener : this) {
                listener.selectedNodeChanged(treeView, previousSelectedNode);
            }
        }
    }

    /**
     * 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".
     */
    public static final class PathComparator implements Comparator, Serializable {
        private static final long serialVersionUID = 1L;

        @Override
        public int compare(Path path1, Path path2) {
            int path1Length = path1.getLength();
            int path2Length = path2.getLength();

            for (int i = 0, n = Math.min(path1Length, path2Length); i < n; i++) {
                int pathElement1 = path1.get(i);
                int pathElement2 = path2.get(i);

                if (pathElement1 != pathElement2) {
                    return pathElement1 - pathElement2;
                }
            }

            return path1Length - path2Length;
        }
    }

    /**
     * Notifies the tree of nested ListListener events that occur on
     * the tree data.
     */
    private class BranchHandler extends ArrayList implements ListListener