1 /*
   2  * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.swing.tree;
  27 
  28 import javax.swing.event.*;
  29 import java.beans.PropertyChangeListener;
  30 
  31 /**
  32   * This interface represents the current state of the selection for
  33   * the tree component.
  34   * For information and examples of using tree selection models,
  35   * see <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/tree.html">How to Use Trees</a>
  36   * in <em>The Java Tutorial.</em>
  37   *
  38   * <p>
  39   * The state of the tree selection is characterized by
  40   * a set of TreePaths, and optionally a set of integers. The mapping
  41   * from TreePath to integer is done by way of an instance of RowMapper.
  42   * It is not necessary for a TreeSelectionModel to have a RowMapper to
  43   * correctly operate, but without a RowMapper {@code getSelectionRows}
  44   * will return null.
  45   *
  46   * <p>
  47   *
  48   * A TreeSelectionModel can be configured to allow only one
  49   * path ({@code SINGLE_TREE_SELECTION}) a number of
  50   * contiguous paths ({@code CONTIGUOUS_TREE_SELECTION}) or a number of
  51   * discontiguous paths ({@code DISCONTIGUOUS_TREE_SELECTION}).
  52   * A {@code RowMapper} is used to determine if TreePaths are
  53   * contiguous.
  54   * In the absence of a RowMapper {@code CONTIGUOUS_TREE_SELECTION} and
  55   * {@code DISCONTIGUOUS_TREE_SELECTION} behave the same, that is they
  56   * allow any number of paths to be contained in the TreeSelectionModel.
  57   *
  58   * <p>
  59   *
  60   * For a selection model of {@code CONTIGUOUS_TREE_SELECTION} any
  61   * time the paths are changed ({@code setSelectionPath},
  62   * {@code addSelectionPath} ...) the TreePaths are again checked to
  63   * make they are contiguous. A check of the TreePaths can also be forced
  64   * by invoking {@code resetRowSelection}. How a set of discontiguous
  65   * TreePaths is mapped to a contiguous set is left to implementors of
  66   * this interface to enforce a particular policy.
  67   *
  68   * <p>
  69   *
  70   * Implementations should combine duplicate TreePaths that are
  71   * added to the selection. For example, the following code
  72   * <pre>
  73   *   TreePath[] paths = new TreePath[] { treePath, treePath };
  74   *   treeSelectionModel.setSelectionPaths(paths);
  75   * </pre>
  76   * should result in only one path being selected:
  77   * {@code treePath}, and
  78   * not two copies of {@code treePath}.
  79   *
  80   * <p>
  81   *
  82   * The lead TreePath is the last path that was added (or set). The lead
  83   * row is then the row that corresponds to the TreePath as determined
  84   * from the RowMapper.
  85   *
  86   * @author Scott Violet
  87   */
  88 
  89 public interface TreeSelectionModel
  90 {
  91     /** Selection can only contain one path at a time. */
  92     public static final int               SINGLE_TREE_SELECTION = 1;
  93 
  94     /** Selection can only be contiguous. This will only be enforced if
  95      * a RowMapper instance is provided. That is, if no RowMapper is set
  96      * this behaves the same as DISCONTIGUOUS_TREE_SELECTION. */
  97     public static final int               CONTIGUOUS_TREE_SELECTION = 2;
  98 
  99     /** Selection can contain any number of items that are not necessarily
 100      * contiguous. */
 101     public static final int               DISCONTIGUOUS_TREE_SELECTION = 4;
 102 
 103     /**
 104      * Sets the selection model, which must be one of SINGLE_TREE_SELECTION,
 105      * CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.
 106      * <p>
 107      * This may change the selection if the current selection is not valid
 108      * for the new mode. For example, if three TreePaths are
 109      * selected when the mode is changed to {@code SINGLE_TREE_SELECTION},
 110      * only one TreePath will remain selected. It is up to the particular
 111      * implementation to decide what TreePath remains selected.
 112      *
 113      * @param   mode    selection mode to be set
 114      */
 115     void setSelectionMode(int mode);
 116 
 117     /**
 118      * Returns the current selection mode, one of
 119      * {@code SINGLE_TREE_SELECTION},
 120      * {@code CONTIGUOUS_TREE_SELECTION} or
 121      * {@code DISCONTIGUOUS_TREE_SELECTION}.
 122      *
 123      * @return          the current selection mode
 124      */
 125     int getSelectionMode();
 126 
 127     /**
 128       * Sets the selection to path. If this represents a change, then
 129       * the TreeSelectionListeners are notified. If {@code path} is
 130       * null, this has the same effect as invoking {@code clearSelection}.
 131       *
 132       * @param  path    new path to select
 133       */
 134     void setSelectionPath(TreePath path);
 135 
 136     /**
 137       * Sets the selection to path. If this represents a change, then
 138       * the TreeSelectionListeners are notified. If {@code paths} is
 139       * null, this has the same effect as invoking {@code clearSelection}.
 140       *
 141       * @param  paths   new selection
 142       */
 143     void setSelectionPaths(TreePath[] paths);
 144 
 145     /**
 146       * Adds path to the current selection. If path is not currently
 147       * in the selection the TreeSelectionListeners are notified. This has
 148       * no effect if {@code path} is null.
 149       *
 150       * @param  path    the new path to add to the current selection
 151       */
 152     void addSelectionPath(TreePath path);
 153 
 154     /**
 155       * Adds paths to the current selection.  If any of the paths in
 156       * paths are not currently in the selection the TreeSelectionListeners
 157       * are notified. This has
 158       * no effect if {@code paths} is null.
 159       *
 160       * @param  paths   the new paths to add to the current selection
 161       */
 162     void addSelectionPaths(TreePath[] paths);
 163 
 164     /**
 165       * Removes path from the selection. If path is in the selection
 166       * The TreeSelectionListeners are notified. This has no effect if
 167       * {@code path} is null.
 168       *
 169       * @param  path    the path to remove from the selection
 170       */
 171     void removeSelectionPath(TreePath path);
 172 
 173     /**
 174       * Removes paths from the selection.  If any of the paths in
 175       * {@code paths}
 176       * are in the selection, the TreeSelectionListeners are notified.
 177       * This method has no effect if {@code paths} is null.
 178       *
 179       * @param  paths   the path to remove from the selection
 180       */
 181     void removeSelectionPaths(TreePath[] paths);
 182 
 183     /**
 184       * Returns the first path in the selection. How first is defined is
 185       * up to implementors, and may not necessarily be the TreePath with
 186       * the smallest integer value as determined from the
 187       * {@code RowMapper}.
 188       *
 189       * @return         the first path in the selection
 190       */
 191     TreePath getSelectionPath();
 192 
 193     /**
 194       * Returns the paths in the selection. This will return null (or an
 195       * empty array) if nothing is currently selected.
 196       *
 197       * @return         the paths in the selection
 198       */
 199     TreePath[] getSelectionPaths();
 200 
 201     /**
 202      * Returns the number of paths that are selected.
 203      *
 204      * @return          the number of paths that are selected
 205      */
 206     int getSelectionCount();
 207 
 208     /**
 209       * Returns true if the path, {@code path}, is in the current
 210       * selection.
 211       *
 212       * @param  path    the path to be loked for
 213       * @return         whether the {@code path} is in the current selection
 214       */
 215     boolean isPathSelected(TreePath path);
 216 
 217     /**
 218       * Returns true if the selection is currently empty.
 219       *
 220       * @return         whether the selection is currently empty
 221       */
 222     boolean isSelectionEmpty();
 223 
 224     /**
 225       * Empties the current selection.  If this represents a change in the
 226       * current selection, the selection listeners are notified.
 227       */
 228     void clearSelection();
 229 
 230     /**
 231      * Sets the RowMapper instance. This instance is used to determine
 232      * the row for a particular TreePath.
 233      *
 234      * @param   newMapper   RowMapper to be set
 235      */
 236     void setRowMapper(RowMapper newMapper);
 237 
 238     /**
 239      * Returns the RowMapper instance that is able to map a TreePath to a
 240      * row.
 241      *
 242      * @return          the RowMapper instance that is able to map a TreePath
 243      *                  to a row
 244      */
 245     RowMapper getRowMapper();
 246 
 247     /**
 248       * Returns all of the currently selected rows. This will return
 249       * null (or an empty array) if there are no selected TreePaths or
 250       * a RowMapper has not been set.
 251       *
 252       * @return         all of the currently selected rows
 253       */
 254     int[] getSelectionRows();
 255 
 256     /**
 257      * Returns the smallest value obtained from the RowMapper for the
 258      * current set of selected TreePaths. If nothing is selected,
 259      * or there is no RowMapper, this will return -1.
 260      *
 261      * @return          the smallest value obtained from the RowMapper
 262      *                  for the current set of selected TreePaths
 263       */
 264     int getMinSelectionRow();
 265 
 266     /**
 267      * Returns the largest value obtained from the RowMapper for the
 268      * current set of selected TreePaths. If nothing is selected,
 269      * or there is no RowMapper, this will return -1.
 270      *
 271      * @return          the largest value obtained from the RowMapper
 272      *                  for the current set of selected TreePaths
 273       */
 274     int getMaxSelectionRow();
 275 
 276     /**
 277       * Returns true if the row identified by {@code row} is selected.
 278       *
 279       * @param  row     row to check
 280       * @return         whether the row is selected
 281       */
 282     boolean isRowSelected(int row);
 283 
 284     /**
 285      * Updates this object's mapping from TreePaths to rows. This should
 286      * be invoked when the mapping from TreePaths to integers has changed
 287      * (for example, a node has been expanded).
 288      * <p>
 289      * You do not normally have to call this; JTree and its associated
 290      * listeners will invoke this for you. If you are implementing your own
 291      * view class, then you will have to invoke this.
 292      */
 293     void resetRowSelection();
 294 
 295     /**
 296      * Returns the lead selection index. That is the last index that was
 297      * added.
 298      *
 299      * @return          the lead selection index
 300      */
 301     int getLeadSelectionRow();
 302 
 303     /**
 304      * Returns the last path that was added. This may differ from the
 305      * leadSelectionPath property maintained by the JTree.
 306      *
 307      * @return          the last path that was added
 308      */
 309     TreePath getLeadSelectionPath();
 310 
 311     /**
 312      * Adds a PropertyChangeListener to the listener list.
 313      * The listener is registered for all properties.
 314      * <p>
 315      * A PropertyChangeEvent will get fired when the selection mode
 316      * changes.
 317      *
 318      * @param   listener    the PropertyChangeListener to be added
 319      */
 320     void addPropertyChangeListener(PropertyChangeListener listener);
 321 
 322     /**
 323      * Removes a PropertyChangeListener from the listener list.
 324      * This removes a PropertyChangeListener that was registered
 325      * for all properties.
 326      *
 327      * @param   listener    the PropertyChangeListener to be removed
 328      */
 329     void removePropertyChangeListener(PropertyChangeListener listener);
 330 
 331     /**
 332       * Adds x to the list of listeners that are notified each time the
 333       * set of selected TreePaths changes.
 334       *
 335       * @param  x       the new listener to be added
 336       */
 337     void addTreeSelectionListener(TreeSelectionListener x);
 338 
 339     /**
 340       * Removes x from the list of listeners that are notified each time
 341       * the set of selected TreePaths changes.
 342       *
 343       * @param  x       the listener to remove
 344       */
 345     void removeTreeSelectionListener(TreeSelectionListener x);
 346 }