0N/A/*
2362N/A * Copyright (c) 1997, 2002, Oracle and/or its affiliates. All rights reserved.
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A *
0N/A * This code is free software; you can redistribute it and/or modify it
0N/A * under the terms of the GNU General Public License version 2 only, as
2362N/A * published by the Free Software Foundation. Oracle designates this
0N/A * particular file as subject to the "Classpath" exception as provided
2362N/A * by Oracle in the LICENSE file that accompanied this code.
0N/A *
0N/A * This code is distributed in the hope that it will be useful, but WITHOUT
0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/A * version 2 for more details (a copy is included in the LICENSE file that
0N/A * accompanied this code).
0N/A *
0N/A * You should have received a copy of the GNU General Public License version
0N/A * 2 along with this work; if not, write to the Free Software Foundation,
0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A *
2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2362N/A * or visit www.oracle.com if you need additional information or have any
2362N/A * questions.
0N/A */
0N/A
0N/Apackage javax.swing.tree;
0N/A
0N/Aimport javax.swing.event.*;
0N/Aimport java.beans.PropertyChangeListener;
0N/A
0N/A/**
0N/A * This interface represents the current state of the selection for
0N/A * the tree component.
0N/A * For information and examples of using tree selection models,
0N/A * see <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/tree.html">How to Use Trees</a>
0N/A * in <em>The Java Tutorial.</em>
0N/A *
0N/A * <p>
0N/A * The state of the tree selection is characterized by
0N/A * a set of TreePaths, and optionally a set of integers. The mapping
0N/A * from TreePath to integer is done by way of an instance of RowMapper.
0N/A * It is not necessary for a TreeSelectionModel to have a RowMapper to
0N/A * correctly operate, but without a RowMapper <code>getSelectionRows</code>
0N/A * will return null.
0N/A *
0N/A * <p>
0N/A *
0N/A * A TreeSelectionModel can be configured to allow only one
0N/A * path (<code>SINGLE_TREE_SELECTION</code>) a number of
0N/A * continguous paths (<code>CONTIGUOUS_TREE_SELECTION</code>) or a number of
0N/A * discontiguous paths (<code>DISCONTIGUOUS_TREE_SELECTION</code>).
0N/A * A <code>RowMapper</code> is used to determine if TreePaths are
0N/A * contiguous.
0N/A * In the absence of a RowMapper <code>CONTIGUOUS_TREE_SELECTION</code> and
0N/A * <code>DISCONTIGUOUS_TREE_SELECTION</code> behave the same, that is they
0N/A * allow any number of paths to be contained in the TreeSelectionModel.
0N/A *
0N/A * <p>
0N/A *
0N/A * For a selection model of <code>CONTIGUOUS_TREE_SELECTION</code> any
0N/A * time the paths are changed (<code>setSelectionPath</code>,
0N/A * <code>addSelectionPath</code> ...) the TreePaths are again checked to
0N/A * make they are contiguous. A check of the TreePaths can also be forced
0N/A * by invoking <code>resetRowSelection</code>. How a set of discontiguous
0N/A * TreePaths is mapped to a contiguous set is left to implementors of
0N/A * this interface to enforce a particular policy.
0N/A *
0N/A * <p>
0N/A *
0N/A * Implementations should combine duplicate TreePaths that are
0N/A * added to the selection. For example, the following code
0N/A * <pre>
0N/A * TreePath[] paths = new TreePath[] { treePath, treePath };
0N/A * treeSelectionModel.setSelectionPaths(paths);
0N/A * </pre>
0N/A * should result in only one path being selected:
0N/A * <code>treePath</code>, and
0N/A * not two copies of <code>treePath</code>.
0N/A *
0N/A * <p>
0N/A *
0N/A * The lead TreePath is the last path that was added (or set). The lead
0N/A * row is then the row that corresponds to the TreePath as determined
0N/A * from the RowMapper.
0N/A *
0N/A * @author Scott Violet
0N/A */
0N/A
0N/Apublic interface TreeSelectionModel
0N/A{
0N/A /** Selection can only contain one path at a time. */
0N/A public static final int SINGLE_TREE_SELECTION = 1;
0N/A
0N/A /** Selection can only be contiguous. This will only be enforced if
0N/A * a RowMapper instance is provided. That is, if no RowMapper is set
0N/A * this behaves the same as DISCONTIGUOUS_TREE_SELECTION. */
0N/A public static final int CONTIGUOUS_TREE_SELECTION = 2;
0N/A
0N/A /** Selection can contain any number of items that are not necessarily
0N/A * contiguous. */
0N/A public static final int DISCONTIGUOUS_TREE_SELECTION = 4;
0N/A
0N/A /**
0N/A * Sets the selection model, which must be one of SINGLE_TREE_SELECTION,
0N/A * CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.
0N/A * <p>
0N/A * This may change the selection if the current selection is not valid
0N/A * for the new mode. For example, if three TreePaths are
0N/A * selected when the mode is changed to <code>SINGLE_TREE_SELECTION</code>,
0N/A * only one TreePath will remain selected. It is up to the particular
0N/A * implementation to decide what TreePath remains selected.
0N/A */
0N/A void setSelectionMode(int mode);
0N/A
0N/A /**
0N/A * Returns the current selection mode, one of
0N/A * <code>SINGLE_TREE_SELECTION</code>,
0N/A * <code>CONTIGUOUS_TREE_SELECTION</code> or
0N/A * <code>DISCONTIGUOUS_TREE_SELECTION</code>.
0N/A */
0N/A int getSelectionMode();
0N/A
0N/A /**
0N/A * Sets the selection to path. If this represents a change, then
0N/A * the TreeSelectionListeners are notified. If <code>path</code> is
0N/A * null, this has the same effect as invoking <code>clearSelection</code>.
0N/A *
0N/A * @param path new path to select
0N/A */
0N/A void setSelectionPath(TreePath path);
0N/A
0N/A /**
0N/A * Sets the selection to path. If this represents a change, then
0N/A * the TreeSelectionListeners are notified. If <code>paths</code> is
0N/A * null, this has the same effect as invoking <code>clearSelection</code>.
0N/A *
0N/A * @param paths new selection
0N/A */
0N/A void setSelectionPaths(TreePath[] paths);
0N/A
0N/A /**
0N/A * Adds path to the current selection. If path is not currently
0N/A * in the selection the TreeSelectionListeners are notified. This has
0N/A * no effect if <code>path</code> is null.
0N/A *
0N/A * @param path the new path to add to the current selection
0N/A */
0N/A void addSelectionPath(TreePath path);
0N/A
0N/A /**
0N/A * Adds paths to the current selection. If any of the paths in
0N/A * paths are not currently in the selection the TreeSelectionListeners
0N/A * are notified. This has
0N/A * no effect if <code>paths</code> is null.
0N/A *
0N/A * @param paths the new paths to add to the current selection
0N/A */
0N/A void addSelectionPaths(TreePath[] paths);
0N/A
0N/A /**
0N/A * Removes path from the selection. If path is in the selection
0N/A * The TreeSelectionListeners are notified. This has no effect if
0N/A * <code>path</code> is null.
0N/A *
0N/A * @param path the path to remove from the selection
0N/A */
0N/A void removeSelectionPath(TreePath path);
0N/A
0N/A /**
0N/A * Removes paths from the selection. If any of the paths in
0N/A * <code>paths</code>
0N/A * are in the selection, the TreeSelectionListeners are notified.
0N/A * This method has no effect if <code>paths</code> is null.
0N/A *
0N/A * @param paths the path to remove from the selection
0N/A */
0N/A void removeSelectionPaths(TreePath[] paths);
0N/A
0N/A /**
0N/A * Returns the first path in the selection. How first is defined is
0N/A * up to implementors, and may not necessarily be the TreePath with
0N/A * the smallest integer value as determined from the
0N/A * <code>RowMapper</code>.
0N/A */
0N/A TreePath getSelectionPath();
0N/A
0N/A /**
0N/A * Returns the paths in the selection. This will return null (or an
0N/A * empty array) if nothing is currently selected.
0N/A */
0N/A TreePath[] getSelectionPaths();
0N/A
0N/A /**
0N/A * Returns the number of paths that are selected.
0N/A */
0N/A int getSelectionCount();
0N/A
0N/A /**
0N/A * Returns true if the path, <code>path</code>, is in the current
0N/A * selection.
0N/A */
0N/A boolean isPathSelected(TreePath path);
0N/A
0N/A /**
0N/A * Returns true if the selection is currently empty.
0N/A */
0N/A boolean isSelectionEmpty();
0N/A
0N/A /**
0N/A * Empties the current selection. If this represents a change in the
0N/A * current selection, the selection listeners are notified.
0N/A */
0N/A void clearSelection();
0N/A
0N/A /**
0N/A * Sets the RowMapper instance. This instance is used to determine
0N/A * the row for a particular TreePath.
0N/A */
0N/A void setRowMapper(RowMapper newMapper);
0N/A
0N/A /**
0N/A * Returns the RowMapper instance that is able to map a TreePath to a
0N/A * row.
0N/A */
0N/A RowMapper getRowMapper();
0N/A
0N/A /**
0N/A * Returns all of the currently selected rows. This will return
0N/A * null (or an empty array) if there are no selected TreePaths or
0N/A * a RowMapper has not been set.
0N/A */
0N/A int[] getSelectionRows();
0N/A
0N/A /**
0N/A * Returns the smallest value obtained from the RowMapper for the
0N/A * current set of selected TreePaths. If nothing is selected,
0N/A * or there is no RowMapper, this will return -1.
0N/A */
0N/A int getMinSelectionRow();
0N/A
0N/A /**
0N/A * Returns the largest value obtained from the RowMapper for the
0N/A * current set of selected TreePaths. If nothing is selected,
0N/A * or there is no RowMapper, this will return -1.
0N/A */
0N/A int getMaxSelectionRow();
0N/A
0N/A /**
0N/A * Returns true if the row identified by <code>row</code> is selected.
0N/A */
0N/A boolean isRowSelected(int row);
0N/A
0N/A /**
0N/A * Updates this object's mapping from TreePaths to rows. This should
0N/A * be invoked when the mapping from TreePaths to integers has changed
0N/A * (for example, a node has been expanded).
0N/A * <p>
0N/A * You do not normally have to call this; JTree and its associated
0N/A * listeners will invoke this for you. If you are implementing your own
0N/A * view class, then you will have to invoke this.
0N/A */
0N/A void resetRowSelection();
0N/A
0N/A /**
0N/A * Returns the lead selection index. That is the last index that was
0N/A * added.
0N/A */
0N/A int getLeadSelectionRow();
0N/A
0N/A /**
0N/A * Returns the last path that was added. This may differ from the
0N/A * leadSelectionPath property maintained by the JTree.
0N/A */
0N/A TreePath getLeadSelectionPath();
0N/A
0N/A /**
0N/A * Adds a PropertyChangeListener to the listener list.
0N/A * The listener is registered for all properties.
0N/A * <p>
0N/A * A PropertyChangeEvent will get fired when the selection mode
0N/A * changes.
0N/A *
0N/A * @param listener the PropertyChangeListener to be added
0N/A */
0N/A void addPropertyChangeListener(PropertyChangeListener listener);
0N/A
0N/A /**
0N/A * Removes a PropertyChangeListener from the listener list.
0N/A * This removes a PropertyChangeListener that was registered
0N/A * for all properties.
0N/A *
0N/A * @param listener the PropertyChangeListener to be removed
0N/A */
0N/A void removePropertyChangeListener(PropertyChangeListener listener);
0N/A
0N/A /**
0N/A * Adds x to the list of listeners that are notified each time the
0N/A * set of selected TreePaths changes.
0N/A *
0N/A * @param x the new listener to be added
0N/A */
0N/A void addTreeSelectionListener(TreeSelectionListener x);
0N/A
0N/A /**
0N/A * Removes x from the list of listeners that are notified each time
0N/A * the set of selected TreePaths changes.
0N/A *
0N/A * @param x the listener to remove
0N/A */
0N/A void removeTreeSelectionListener(TreeSelectionListener x);
0N/A}