1 /* 2 * Copyright (c) 1997, 2006, 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; 27 28 import javax.swing.event.*; 29 30 /** 31 * This interface represents the current state of the 32 * selection for any of the components that display a 33 * list of values with stable indices. The selection is 34 * modeled as a set of intervals, each interval represents 35 * a contiguous range of selected list elements. 36 * The methods for modifying the set of selected intervals 37 * all take a pair of indices, index0 and index1, that represent 38 * a closed interval, i.e. the interval includes both index0 and 39 * index1. 40 * 41 * @author Hans Muller 42 * @author Philip Milne 43 * @see DefaultListSelectionModel 44 */ 45 46 public interface ListSelectionModel 47 { 48 /** 49 * A value for the selectionMode property: select one list index 50 * at a time. 51 * 52 * @see #setSelectionMode 53 */ 54 int SINGLE_SELECTION = 0; 55 56 /** 57 * A value for the selectionMode property: select one contiguous 58 * range of indices at a time. 59 * 60 * @see #setSelectionMode 61 */ 62 int SINGLE_INTERVAL_SELECTION = 1; 63 64 /** 65 * A value for the selectionMode property: select one or more 66 * contiguous ranges of indices at a time. 67 * 68 * @see #setSelectionMode 69 */ 70 int MULTIPLE_INTERVAL_SELECTION = 2; 71 72 73 /** 74 * Changes the selection to be between {@code index0} and {@code index1} 75 * inclusive. {@code index0} doesn't have to be less than or equal to 76 * {@code index1}. 77 * <p> 78 * In {@code SINGLE_SELECTION} selection mode, only the second index 79 * is used. 80 * <p> 81 * If this represents a change to the current selection, then each 82 * {@code ListSelectionListener} is notified of the change. 83 * 84 * @param index0 one end of the interval. 85 * @param index1 other end of the interval 86 * @see #addListSelectionListener 87 */ 88 void setSelectionInterval(int index0, int index1); 89 90 91 /** 92 * Changes the selection to be the set union of the current selection 93 * and the indices between {@code index0} and {@code index1} inclusive. 94 * {@code index0} doesn't have to be less than or equal to {@code index1}. 95 * <p> 96 * In {@code SINGLE_SELECTION} selection mode, this is equivalent 97 * to calling {@code setSelectionInterval}, and only the second index 98 * is used. In {@code SINGLE_INTERVAL_SELECTION} selection mode, this 99 * method behaves like {@code setSelectionInterval}, unless the given 100 * interval is immediately adjacent to or overlaps the existing selection, 101 * and can therefore be used to grow the selection. 102 * <p> 103 * If this represents a change to the current selection, then each 104 * {@code ListSelectionListener} is notified of the change. 105 * 106 * @param index0 one end of the interval. 107 * @param index1 other end of the interval 108 * @see #addListSelectionListener 109 * @see #setSelectionInterval 110 */ 111 void addSelectionInterval(int index0, int index1); 112 113 114 /** 115 * Changes the selection to be the set difference of the current selection 116 * and the indices between {@code index0} and {@code index1} inclusive. 117 * {@code index0} doesn't have to be less than or equal to {@code index1}. 118 * <p> 119 * In {@code SINGLE_INTERVAL_SELECTION} selection mode, if the removal 120 * would produce two disjoint selections, the removal is extended through 121 * the greater end of the selection. For example, if the selection is 122 * {@code 0-10} and you supply indices {@code 5,6} (in any order) the 123 * resulting selection is {@code 0-4}. 124 * <p> 125 * If this represents a change to the current selection, then each 126 * {@code ListSelectionListener} is notified of the change. 127 * 128 * @param index0 one end of the interval. 129 * @param index1 other end of the interval 130 * @see #addListSelectionListener 131 */ 132 void removeSelectionInterval(int index0, int index1); 133 134 135 /** 136 * Returns the first selected index or -1 if the selection is empty. 137 */ 138 int getMinSelectionIndex(); 139 140 141 /** 142 * Returns the last selected index or -1 if the selection is empty. 143 */ 144 int getMaxSelectionIndex(); 145 146 147 /** 148 * Returns true if the specified index is selected. 149 */ 150 boolean isSelectedIndex(int index); 151 152 153 /** 154 * Return the first index argument from the most recent call to 155 * setSelectionInterval(), addSelectionInterval() or removeSelectionInterval(). 156 * The most recent index0 is considered the "anchor" and the most recent 157 * index1 is considered the "lead". Some interfaces display these 158 * indices specially, e.g. Windows95 displays the lead index with a 159 * dotted yellow outline. 160 * 161 * @see #getLeadSelectionIndex 162 * @see #setSelectionInterval 163 * @see #addSelectionInterval 164 */ 165 int getAnchorSelectionIndex(); 166 167 168 /** 169 * Set the anchor selection index. 170 * 171 * @see #getAnchorSelectionIndex 172 */ 173 void setAnchorSelectionIndex(int index); 174 175 176 /** 177 * Return the second index argument from the most recent call to 178 * setSelectionInterval(), addSelectionInterval() or removeSelectionInterval(). 179 * 180 * @see #getAnchorSelectionIndex 181 * @see #setSelectionInterval 182 * @see #addSelectionInterval 183 */ 184 int getLeadSelectionIndex(); 185 186 /** 187 * Set the lead selection index. 188 * 189 * @see #getLeadSelectionIndex 190 */ 191 void setLeadSelectionIndex(int index); 192 193 /** 194 * Change the selection to the empty set. If this represents 195 * a change to the current selection then notify each ListSelectionListener. 196 * 197 * @see #addListSelectionListener 198 */ 199 void clearSelection(); 200 201 /** 202 * Returns true if no indices are selected. 203 */ 204 boolean isSelectionEmpty(); 205 206 /** 207 * Insert length indices beginning before/after index. This is typically 208 * called to sync the selection model with a corresponding change 209 * in the data model. 210 */ 211 void insertIndexInterval(int index, int length, boolean before); 212 213 /** 214 * Remove the indices in the interval index0,index1 (inclusive) from 215 * the selection model. This is typically called to sync the selection 216 * model width a corresponding change in the data model. 217 */ 218 void removeIndexInterval(int index0, int index1); 219 220 /** 221 * Sets the {@code valueIsAdjusting} property, which indicates whether 222 * or not upcoming selection changes should be considered part of a single 223 * change. The value of this property is used to initialize the 224 * {@code valueIsAdjusting} property of the {@code ListSelectionEvent}s that 225 * are generated. 226 * <p> 227 * For example, if the selection is being updated in response to a user 228 * drag, this property can be set to {@code true} when the drag is initiated 229 * and set to {@code false} when the drag is finished. During the drag, 230 * listeners receive events with a {@code valueIsAdjusting} property 231 * set to {@code true}. At the end of the drag, when the change is 232 * finalized, listeners receive an event with the value set to {@code false}. 233 * Listeners can use this pattern if they wish to update only when a change 234 * has been finalized. 235 * <p> 236 * Setting this property to {@code true} begins a series of changes that 237 * is to be considered part of a single change. When the property is changed 238 * back to {@code false}, an event is sent out characterizing the entire 239 * selection change (if there was one), with the event's 240 * {@code valueIsAdjusting} property set to {@code false}. 241 * 242 * @param valueIsAdjusting the new value of the property 243 * @see #getValueIsAdjusting 244 * @see javax.swing.event.ListSelectionEvent#getValueIsAdjusting 245 */ 246 void setValueIsAdjusting(boolean valueIsAdjusting); 247 248 /** 249 * Returns {@code true} if the selection is undergoing a series of changes. 250 * 251 * @return true if the selection is undergoing a series of changes 252 * @see #setValueIsAdjusting 253 */ 254 boolean getValueIsAdjusting(); 255 256 /** 257 * Sets the selection mode. The following list describes the accepted 258 * selection modes: 259 * <ul> 260 * <li>{@code ListSelectionModel.SINGLE_SELECTION} - 261 * Only one list index can be selected at a time. In this mode, 262 * {@code setSelectionInterval} and {@code addSelectionInterval} are 263 * equivalent, both replacing the current selection with the index 264 * represented by the second argument (the "lead"). 265 * <li>{@code ListSelectionModel.SINGLE_INTERVAL_SELECTION} - 266 * Only one contiguous interval can be selected at a time. 267 * In this mode, {@code addSelectionInterval} behaves like 268 * {@code setSelectionInterval} (replacing the current selection), 269 * unless the given interval is immediately adjacent to or overlaps 270 * the existing selection, and can therefore be used to grow it. 271 * <li>{@code ListSelectionModel.MULTIPLE_INTERVAL_SELECTION} - 272 * In this mode, there's no restriction on what can be selected. 273 * </ul> 274 * 275 * @see #getSelectionMode 276 * @throws IllegalArgumentException if the selection mode isn't 277 * one of those allowed 278 */ 279 void setSelectionMode(int selectionMode); 280 281 /** 282 * Returns the current selection mode. 283 * 284 * @return the current selection mode 285 * @see #setSelectionMode 286 */ 287 int getSelectionMode(); 288 289 /** 290 * Add a listener to the list that's notified each time a change 291 * to the selection occurs. 292 * 293 * @param x the ListSelectionListener 294 * @see #removeListSelectionListener 295 * @see #setSelectionInterval 296 * @see #addSelectionInterval 297 * @see #removeSelectionInterval 298 * @see #clearSelection 299 * @see #insertIndexInterval 300 * @see #removeIndexInterval 301 */ 302 void addListSelectionListener(ListSelectionListener x); 303 304 /** 305 * Remove a listener from the list that's notified each time a 306 * change to the selection occurs. 307 * 308 * @param x the ListSelectionListener 309 * @see #addListSelectionListener 310 */ 311 void removeListSelectionListener(ListSelectionListener x); 312 }