Source for javax.swing.ListSelectionModel

   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: }