| Frames | No Frames |
1: /* ListSelectionModel.java -- 2: Copyright (C) 2002, 2006, Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package javax.swing; 40: 41: import javax.swing.event.ListSelectionEvent; 42: import javax.swing.event.ListSelectionListener; 43: 44: /** 45: * A model that tracks the selection status of a list of items. Each item in 46: * the list is identified by a zero-based index only, so the model can be used 47: * to track the selection status of any type of list. The model 48: * supports three modes: 49: * <ul> 50: * <li><code>SINGLE_SELECTION</code> - only one item in the list may be 51: * selected;</li> 52: * <li><code>SINGLE_INTERVAL_SELECTION</code> - only one interval in the list 53: * may be selected;</li> 54: * <li><code>MULTIPLE_INTERVAL_SELECTION</code> - any combination of items in 55: * the list may be selected.</li> 56: * </ul> 57: * The model uses an event notification mechanism to notify listeners (see 58: * {@link ListSelectionListener}) about updates to the selection model. 59: * <p> 60: * This model is used to track row selections in the {@link JList} component, 61: * and row and column selections in the {@link JTable} component. 62: */ 63: public interface ListSelectionModel 64: { 65: 66: /** 67: * A selection mode in which only one item can be selected. 68: * 69: * @see #setSelectionMode(int) 70: */ 71: int SINGLE_SELECTION = 0; 72: 73: /** 74: * A selection mode in which a single interval can be selected (an interval 75: * is a range containing one or more contiguous items). 76: * 77: * @see #setSelectionMode(int) 78: */ 79: int SINGLE_INTERVAL_SELECTION = 1; 80: 81: /** 82: * A selection mode in which any combination of items can be selected. 83: * 84: * @see #setSelectionMode(int) 85: */ 86: int MULTIPLE_INTERVAL_SELECTION = 2; 87: 88: /** 89: * Sets the selection mode. 90: * <p> 91: * FIXME: The spec is silent about what happens to existing selections, for 92: * example when changing from an interval selection to single selection. 93: * 94: * @param mode one of {@link #SINGLE_SELECTION}, 95: * {@link #SINGLE_INTERVAL_SELECTION} and 96: * {@link #MULTIPLE_INTERVAL_SELECTION}. 97: * 98: * @see #getSelectionMode() 99: * 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: }