1 /* 2 * Copyright (c) 1997, 2002, 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 * continguous 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 void setSelectionMode(int mode); 114 115 /** 116 * Returns the current selection mode, one of 117 * <code>SINGLE_TREE_SELECTION</code>, 118 * <code>CONTIGUOUS_TREE_SELECTION</code> or 119 * <code>DISCONTIGUOUS_TREE_SELECTION</code>. 120 */ 121 int getSelectionMode(); 122 123 /** 124 * Sets the selection to path. If this represents a change, then 125 * the TreeSelectionListeners are notified. If <code>path</code> is 126 * null, this has the same effect as invoking <code>clearSelection</code>. 127 * 128 * @param path new path to select 129 */ 130 void setSelectionPath(TreePath path); 131 132 /** 133 * Sets the selection to path. If this represents a change, then 134 * the TreeSelectionListeners are notified. If <code>paths</code> is 135 * null, this has the same effect as invoking <code>clearSelection</code>. 136 * 137 * @param paths new selection 138 */ 139 void setSelectionPaths(TreePath[] paths); 140 141 /** 142 * Adds path to the current selection. If path is not currently 143 * in the selection the TreeSelectionListeners are notified. This has 144 * no effect if <code>path</code> is null. 145 * 146 * @param path the new path to add to the current selection 147 */ 148 void addSelectionPath(TreePath path); 149 150 /** 151 * Adds paths to the current selection. If any of the paths in 152 * paths are not currently in the selection the TreeSelectionListeners 153 * are notified. This has 154 * no effect if <code>paths</code> is null. 155 * 156 * @param paths the new paths to add to the current selection 157 */ 158 void addSelectionPaths(TreePath[] paths); 159 160 /** 161 * Removes path from the selection. If path is in the selection 162 * The TreeSelectionListeners are notified. This has no effect if 163 * <code>path</code> is null. 164 * 165 * @param path the path to remove from the selection 166 */ 167 void removeSelectionPath(TreePath path); 168 169 /** 170 * Removes paths from the selection. If any of the paths in 171 * <code>paths</code> 172 * are in the selection, the TreeSelectionListeners are notified. 173 * This method has no effect if <code>paths</code> is null. 174 * 175 * @param paths the path to remove from the selection 176 */ 177 void removeSelectionPaths(TreePath[] paths); 178 179 /** 180 * Returns the first path in the selection. How first is defined is 181 * up to implementors, and may not necessarily be the TreePath with 182 * the smallest integer value as determined from the 183 * <code>RowMapper</code>. 184 */ 185 TreePath getSelectionPath(); 186 187 /** 188 * Returns the paths in the selection. This will return null (or an 189 * empty array) if nothing is currently selected. 190 */ 191 TreePath[] getSelectionPaths(); 192 193 /** 194 * Returns the number of paths that are selected. 195 */ 196 int getSelectionCount(); 197 198 /** 199 * Returns true if the path, <code>path</code>, is in the current 200 * selection. 201 */ 202 boolean isPathSelected(TreePath path); 203 204 /** 205 * Returns true if the selection is currently empty. 206 */ 207 boolean isSelectionEmpty(); 208 209 /** 210 * Empties the current selection. If this represents a change in the 211 * current selection, the selection listeners are notified. 212 */ 213 void clearSelection(); 214 215 /** 216 * Sets the RowMapper instance. This instance is used to determine 217 * the row for a particular TreePath. 218 */ 219 void setRowMapper(RowMapper newMapper); 220 221 /** 222 * Returns the RowMapper instance that is able to map a TreePath to a 223 * row. 224 */ 225 RowMapper getRowMapper(); 226 227 /** 228 * Returns all of the currently selected rows. This will return 229 * null (or an empty array) if there are no selected TreePaths or 230 * a RowMapper has not been set. 231 */ 232 int[] getSelectionRows(); 233 234 /** 235 * Returns the smallest value obtained from the RowMapper for the 236 * current set of selected TreePaths. If nothing is selected, 237 * or there is no RowMapper, this will return -1. 238 */ 239 int getMinSelectionRow(); 240 241 /** 242 * Returns the largest value obtained from the RowMapper for the 243 * current set of selected TreePaths. If nothing is selected, 244 * or there is no RowMapper, this will return -1. 245 */ 246 int getMaxSelectionRow(); 247 248 /** 249 * Returns true if the row identified by <code>row</code> is selected. 250 */ 251 boolean isRowSelected(int row); 252 253 /** 254 * Updates this object's mapping from TreePaths to rows. This should 255 * be invoked when the mapping from TreePaths to integers has changed 256 * (for example, a node has been expanded). 257 * <p> 258 * You do not normally have to call this; JTree and its associated 259 * listeners will invoke this for you. If you are implementing your own 260 * view class, then you will have to invoke this. 261 */ 262 void resetRowSelection(); 263 264 /** 265 * Returns the lead selection index. That is the last index that was 266 * added. 267 */ 268 int getLeadSelectionRow(); 269 270 /** 271 * Returns the last path that was added. This may differ from the 272 * leadSelectionPath property maintained by the JTree. 273 */ 274 TreePath getLeadSelectionPath(); 275 276 /** 277 * Adds a PropertyChangeListener to the listener list. 278 * The listener is registered for all properties. 279 * <p> 280 * A PropertyChangeEvent will get fired when the selection mode 281 * changes. 282 * 283 * @param listener the PropertyChangeListener to be added 284 */ 285 void addPropertyChangeListener(PropertyChangeListener listener); 286 287 /** 288 * Removes a PropertyChangeListener from the listener list. 289 * This removes a PropertyChangeListener that was registered 290 * for all properties. 291 * 292 * @param listener the PropertyChangeListener to be removed 293 */ 294 void removePropertyChangeListener(PropertyChangeListener listener); 295 296 /** 297 * Adds x to the list of listeners that are notified each time the 298 * set of selected TreePaths changes. 299 * 300 * @param x the new listener to be added 301 */ 302 void addTreeSelectionListener(TreeSelectionListener x); 303 304 /** 305 * Removes x from the list of listeners that are notified each time 306 * the set of selected TreePaths changes. 307 * 308 * @param x the listener to remove 309 */ 310 void removeTreeSelectionListener(TreeSelectionListener x); 311 }