libjava/classpath/javax/swing/ListSelectionModel.java

   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 }