001 /* ListSelectionModel.java -- 002 Copyright (C) 2002, 2006, Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package javax.swing; 040 041 import javax.swing.event.ListSelectionEvent; 042 import javax.swing.event.ListSelectionListener; 043 044 /** 045 * A model that tracks the selection status of a list of items. Each item in 046 * the list is identified by a zero-based index only, so the model can be used 047 * to track the selection status of any type of list. The model 048 * supports three modes: 049 * <ul> 050 * <li><code>SINGLE_SELECTION</code> - only one item in the list may be 051 * selected;</li> 052 * <li><code>SINGLE_INTERVAL_SELECTION</code> - only one interval in the list 053 * may be selected;</li> 054 * <li><code>MULTIPLE_INTERVAL_SELECTION</code> - any combination of items in 055 * the list may be selected.</li> 056 * </ul> 057 * The model uses an event notification mechanism to notify listeners (see 058 * {@link ListSelectionListener}) about updates to the selection model. 059 * <p> 060 * This model is used to track row selections in the {@link JList} component, 061 * and row and column selections in the {@link JTable} component. 062 */ 063 public interface ListSelectionModel 064 { 065 066 /** 067 * A selection mode in which only one item can be selected. 068 * 069 * @see #setSelectionMode(int) 070 */ 071 int SINGLE_SELECTION = 0; 072 073 /** 074 * A selection mode in which a single interval can be selected (an interval 075 * is a range containing one or more contiguous items). 076 * 077 * @see #setSelectionMode(int) 078 */ 079 int SINGLE_INTERVAL_SELECTION = 1; 080 081 /** 082 * A selection mode in which any combination of items can be selected. 083 * 084 * @see #setSelectionMode(int) 085 */ 086 int MULTIPLE_INTERVAL_SELECTION = 2; 087 088 /** 089 * Sets the selection mode. 090 * <p> 091 * FIXME: The spec is silent about what happens to existing selections, for 092 * example when changing from an interval selection to single selection. 093 * 094 * @param mode one of {@link #SINGLE_SELECTION}, 095 * {@link #SINGLE_INTERVAL_SELECTION} and 096 * {@link #MULTIPLE_INTERVAL_SELECTION}. 097 * 098 * @see #getSelectionMode() 099 * 100 * @throws IllegalArgumentException if <code>mode</code> is not one of the 101 * specified values. 102 */ 103 void setSelectionMode(int mode); 104 105 /** 106 * Returns the selection mode, which is one of {@link #SINGLE_SELECTION}, 107 * {@link #SINGLE_INTERVAL_SELECTION} and 108 * {@link #MULTIPLE_INTERVAL_SELECTION}. 109 * 110 * @return The selection mode. 111 * 112 * @see #setSelectionMode(int) 113 */ 114 int getSelectionMode(); 115 116 /** 117 * Clears the current selection from the model. If the selection state 118 * changes (that is, the existing selection is non-empty) a 119 * {@link ListSelectionEvent} should be sent to all registered listeners. 120 * <p> 121 * FIXME: what happens to the anchor and lead selection indices (the spec 122 * is silent about this)? See: 123 * <p> 124 * http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4334792 125 */ 126 void clearSelection(); 127 128 /** 129 * Returns the lowest selected index, or <code>-1</code> if there is no 130 * selection. 131 * 132 * @return The lowest selected index. 133 * 134 * @see #getMaxSelectionIndex() 135 */ 136 int getMinSelectionIndex(); 137 138 /** 139 * Returns the highest selected index, or <code>-1</code> if there is no 140 * selection. 141 * 142 * @return The highest selected index. 143 * 144 * @see #getMinSelectionIndex() 145 */ 146 int getMaxSelectionIndex(); 147 148 /** 149 * Returns <code>true</code> if the specified item is selected, and 150 * <code>false</code> otherwise. Special note: if <code>index</code> is 151 * negative, this method should return <code>false</code> (no exception 152 * should be thrown). 153 * 154 * @param index the item index (zero-based). 155 * 156 * @return <code>true</code> if the specified item is selected, and 157 * <code>false</code> otherwise. 158 */ 159 boolean isSelectedIndex(int index); 160 161 /** 162 * Returns <code>true</code> if there is no selection, and <code>false</code> 163 * otherwise. 164 * 165 * @return <code>true</code> if there is no selection, and 166 * <code>false</code> otherwise. 167 */ 168 boolean isSelectionEmpty(); 169 170 /** 171 * Sets the selection interval to the specified range (note that 172 * <code>anchor</code> can be less than, equal to, or greater than 173 * <code>lead</code>). If this results in the selection being changed, 174 * a {@link ListSelectionEvent} is sent to all registered listeners. 175 * <p> 176 * If the selection mode is {@link #SINGLE_SELECTION}, only the 177 * <code>lead</code> item is selected. 178 * 179 * @param anchor the anchor index. 180 * @param lead the lead index. 181 */ 182 void setSelectionInterval(int anchor, int lead); 183 184 /** 185 * Marks the items in the specified interval as selected. The behaviour of 186 * this method depends on the selection mode: 187 * <ul> 188 * <li><code>SINGLE_SELECTION</code> - only the <code>lead</code> item is 189 * selected;</li> 190 * <li><code>SINGLE_INTERVAL_SELECTION</code> - the existing selection 191 * interval is replaced by the specified interval;</li> 192 * <li><code>MULTIPLE_INTERVAL_SELECTION</code> - the specified interval is 193 * merged into the currently selected intervals.</li> 194 * </ul> 195 * Note that <code>anchor</code> can be less than, equal to, or greater than 196 * <code>lead</code>. 197 * 198 * @param anchor the index of the anchor item 199 * @param lead the index of the lead item. 200 */ 201 void addSelectionInterval(int anchor, int lead); 202 203 /** 204 * Marks the items in the specified interval as not selected. The behaviour 205 * of this method depends on the selection mode: 206 * <ul> 207 * <li><code>SINGLE_SELECTION</code> - XXX;</li> 208 * <li><code>SINGLE_INTERVAL_SELECTION</code> - XXX;</li> 209 * <li><code>MULTIPLE_INTERVAL_SELECTION</code> - XXX.</li> 210 * </ul> 211 * Note that <code>anchor</code> can be less than, equal to, or greater than 212 * <code>lead</code>. 213 * 214 * @param anchor the index of the anchor item 215 * @param lead the index of the lead item. 216 */ 217 void removeSelectionInterval(int anchor, int lead); 218 219 /** 220 * Inserts a new interval containing <code>length</code> items at the 221 * specified <code>index</code> (the <code>before</code> flag indicates 222 * whether the range is inserted before or after the existing item at 223 * <code>index</code>). 224 * 225 * FIXME: What is the selection status of the new items? Bug 4870694. 226 * FIXME: What event is generated? 227 * 228 * @param index the index of the item. 229 * @param length the number of items in the interval to be inserted. 230 * @param before if <code>true</code>, the interval should be inserted 231 * before <code>index</code>, otherwise it is inserted after. 232 * 233 * @see #removeIndexInterval(int, int) 234 */ 235 void insertIndexInterval(int index, int length, boolean before); 236 237 /** 238 * Removes the items in the specified range (inclusive) from the selection 239 * model. This method should be called when an interval is deleted from 240 * the underlying list. 241 * 242 * FIXME: what happens to the lead and anchor indices if they are part of 243 * the range that is removed? 244 * FIXME: what event is generated 245 * 246 * @param index0 XXX 247 * @param index1 XXX 248 * 249 * @see #insertIndexInterval(int, int, boolean) 250 */ 251 void removeIndexInterval(int index0, int index1); 252 253 /** 254 * Returns the index of the anchor item. 255 * 256 * @return The index of the anchor item. 257 * 258 * @see #setAnchorSelectionIndex(int) 259 */ 260 int getAnchorSelectionIndex(); 261 262 /** 263 * Sets the index of the anchor item. 264 * 265 * @param index the item index. 266 * 267 * @see #getAnchorSelectionIndex() 268 */ 269 void setAnchorSelectionIndex(int index); 270 271 /** 272 * Returns the index of the lead item. 273 * 274 * @return The index of the lead item. 275 * 276 * @see #setLeadSelectionIndex(int) 277 */ 278 int getLeadSelectionIndex(); 279 280 /** 281 * Sets the index of the lead item. 282 * 283 * @param index the item index. 284 * 285 * @see #getLeadSelectionIndex() 286 */ 287 void setLeadSelectionIndex(int index); 288 289 /** 290 * Sets the flag that is passed to listeners for each change notification. 291 * If a sequence of changes is made to the selection model, this flag should 292 * be set to <code>true</code> at the start of the sequence, and 293 * <code>false</code> for the last change - this gives listeners the option 294 * to ignore interim changes if that is more efficient. 295 * 296 * @param valueIsAdjusting the flag value. 297 * 298 * @see #getValueIsAdjusting() 299 */ 300 void setValueIsAdjusting(boolean valueIsAdjusting); 301 302 /** 303 * Returns a flag that is passed to registered listeners when changes are 304 * made to the model. See the description for 305 * {@link #setValueIsAdjusting(boolean)} for more information. 306 * 307 * @return The flag. 308 */ 309 boolean getValueIsAdjusting(); 310 311 /** 312 * Registers a listener with the model so that it receives notification 313 * of changes to the model. 314 * 315 * @param listener the listener (<code>null</code> ignored). 316 * 317 * @see #removeListSelectionListener(ListSelectionListener) 318 */ 319 void addListSelectionListener(ListSelectionListener listener); 320 321 /** 322 * Deregisters a listener so that it no longer receives notification of 323 * changes to the model. If the specified listener is not registered with 324 * the model, or is <code>null</code>, this method does nothing. 325 * 326 * @param listener the listener (<code>null</code> ignored). 327 * 328 * @see #addListSelectionListener(ListSelectionListener) 329 */ 330 void removeListSelectionListener(ListSelectionListener listener); 331 332 }