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 }