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    }