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