< prev index next >

src/java.desktop/share/classes/javax/swing/tree/TreeSelectionModel.java

Print this page




  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</code>
  44   * will return null.
  45   *
  46   * <p>
  47   *
  48   * A TreeSelectionModel can be configured to allow only one
  49   * path (<code>SINGLE_TREE_SELECTION</code>) a number of
  50   * contiguous paths (<code>CONTIGUOUS_TREE_SELECTION</code>) or a number of
  51   * discontiguous paths (<code>DISCONTIGUOUS_TREE_SELECTION</code>).
  52   * A <code>RowMapper</code> is used to determine if TreePaths are
  53   * contiguous.
  54   * In the absence of a RowMapper <code>CONTIGUOUS_TREE_SELECTION</code> and
  55   * <code>DISCONTIGUOUS_TREE_SELECTION</code> 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</code> any
  61   * time the paths are changed (<code>setSelectionPath</code>,
  62   * <code>addSelectionPath</code> ...) 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</code>. 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</code>, and
  78   * not two copies of <code>treePath</code>.
  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</code>,
 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</code>,
 120      * <code>CONTIGUOUS_TREE_SELECTION</code> or
 121      * <code>DISCONTIGUOUS_TREE_SELECTION</code>.
 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</code> is
 130       * null, this has the same effect as invoking <code>clearSelection</code>.
 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</code> is
 139       * null, this has the same effect as invoking <code>clearSelection</code>.
 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</code> 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</code> 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</code> 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</code>
 176       * are in the selection, the TreeSelectionListeners are notified.
 177       * This method has no effect if <code>paths</code> 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</code>.
 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</code>, 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 


 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</code> 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.




  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 


 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.


< prev index next >