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</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 */ setSelectionMode(int mode)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 */ getSelectionMode()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 */ setSelectionPath(TreePath path)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 */ setSelectionPaths(TreePath[] paths)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 */ addSelectionPath(TreePath path)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 */ addSelectionPaths(TreePath[] paths)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 */ removeSelectionPath(TreePath path)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 */ removeSelectionPaths(TreePath[] paths)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 */ getSelectionPath()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 */ getSelectionPaths()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 */ getSelectionCount()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 */ isPathSelected(TreePath path)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 */ isSelectionEmpty()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 */ clearSelection()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 */ setRowMapper(RowMapper newMapper)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 */ getRowMapper()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 */ getSelectionRows()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 */ getMinSelectionRow()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 */ getMaxSelectionRow()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 */ isRowSelected(int row)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 */ resetRowSelection()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 */ getLeadSelectionRow()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 */ getLeadSelectionPath()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 */ addPropertyChangeListener(PropertyChangeListener listener)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 */ removePropertyChangeListener(PropertyChangeListener listener)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 */ addTreeSelectionListener(TreeSelectionListener x)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 */ removeTreeSelectionListener(TreeSelectionListener x)345 void removeTreeSelectionListener(TreeSelectionListener x); 346 } 347