1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293
/* * @(#)TreeSelectionModel.java 1.25 05/11/17 * * Copyright 2006 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ 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. * * @version 1.25 11/17/05 * @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); }