001/* ListSelectionModel.java --
002   Copyright (C) 2002, 2006, Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.swing;
040
041import javax.swing.event.ListSelectionEvent;
042import 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 */
063public 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}