001 /*
002 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.swing;
027
028 import javax.swing.event.*;
029
030 /**
031 * This interface represents the current state of the
032 * selection for any of the components that display a
033 * list of values with stable indices. The selection is
034 * modeled as a set of intervals, each interval represents
035 * a contiguous range of selected list elements.
036 * The methods for modifying the set of selected intervals
037 * all take a pair of indices, index0 and index1, that represent
038 * a closed interval, i.e. the interval includes both index0 and
039 * index1.
040 *
041 * @version 1.29 05/05/07
042 * @author Hans Muller
043 * @author Philip Milne
044 * @see DefaultListSelectionModel
045 */
046
047 public interface ListSelectionModel {
048 /**
049 * A value for the selectionMode property: select one list index
050 * at a time.
051 *
052 * @see #setSelectionMode
053 */
054 int SINGLE_SELECTION = 0;
055
056 /**
057 * A value for the selectionMode property: select one contiguous
058 * range of indices at a time.
059 *
060 * @see #setSelectionMode
061 */
062 int SINGLE_INTERVAL_SELECTION = 1;
063
064 /**
065 * A value for the selectionMode property: select one or more
066 * contiguous ranges of indices at a time.
067 *
068 * @see #setSelectionMode
069 */
070 int MULTIPLE_INTERVAL_SELECTION = 2;
071
072 /**
073 * Changes the selection to be between {@code index0} and {@code index1}
074 * inclusive. {@code index0} doesn't have to be less than or equal to
075 * {@code index1}.
076 * <p>
077 * In {@code SINGLE_SELECTION} selection mode, only the second index
078 * is used.
079 * <p>
080 * If this represents a change to the current selection, then each
081 * {@code ListSelectionListener} is notified of the change.
082 *
083 * @param index0 one end of the interval.
084 * @param index1 other end of the interval
085 * @see #addListSelectionListener
086 */
087 void setSelectionInterval(int index0, int index1);
088
089 /**
090 * Changes the selection to be the set union of the current selection
091 * and the indices between {@code index0} and {@code index1} inclusive.
092 * {@code index0} doesn't have to be less than or equal to {@code index1}.
093 * <p>
094 * In {@code SINGLE_SELECTION} selection mode, this is equivalent
095 * to calling {@code setSelectionInterval}, and only the second index
096 * is used. In {@code SINGLE_INTERVAL_SELECTION} selection mode, this
097 * method behaves like {@code setSelectionInterval}, unless the given
098 * interval is immediately adjacent to or overlaps the existing selection,
099 * and can therefore be used to grow the selection.
100 * <p>
101 * If this represents a change to the current selection, then each
102 * {@code ListSelectionListener} is notified of the change.
103 *
104 * @param index0 one end of the interval.
105 * @param index1 other end of the interval
106 * @see #addListSelectionListener
107 * @see #setSelectionInterval
108 */
109 void addSelectionInterval(int index0, int index1);
110
111 /**
112 * Changes the selection to be the set difference of the current selection
113 * and the indices between {@code index0} and {@code index1} inclusive.
114 * {@code index0} doesn't have to be less than or equal to {@code index1}.
115 * <p>
116 * In {@code SINGLE_INTERVAL_SELECTION} selection mode, if the removal
117 * would produce two disjoint selections, the removal is extended through
118 * the greater end of the selection. For example, if the selection is
119 * {@code 0-10} and you supply indices {@code 5,6} (in any order) the
120 * resulting selection is {@code 0-4}.
121 * <p>
122 * If this represents a change to the current selection, then each
123 * {@code ListSelectionListener} is notified of the change.
124 *
125 * @param index0 one end of the interval.
126 * @param index1 other end of the interval
127 * @see #addListSelectionListener
128 */
129 void removeSelectionInterval(int index0, int index1);
130
131 /**
132 * Returns the first selected index or -1 if the selection is empty.
133 */
134 int getMinSelectionIndex();
135
136 /**
137 * Returns the last selected index or -1 if the selection is empty.
138 */
139 int getMaxSelectionIndex();
140
141 /**
142 * Returns true if the specified index is selected.
143 */
144 boolean isSelectedIndex(int index);
145
146 /**
147 * Return the first index argument from the most recent call to
148 * setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
149 * The most recent index0 is considered the "anchor" and the most recent
150 * index1 is considered the "lead". Some interfaces display these
151 * indices specially, e.g. Windows95 displays the lead index with a
152 * dotted yellow outline.
153 *
154 * @see #getLeadSelectionIndex
155 * @see #setSelectionInterval
156 * @see #addSelectionInterval
157 */
158 int getAnchorSelectionIndex();
159
160 /**
161 * Set the anchor selection index.
162 *
163 * @see #getAnchorSelectionIndex
164 */
165 void setAnchorSelectionIndex(int index);
166
167 /**
168 * Return the second index argument from the most recent call to
169 * setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
170 *
171 * @see #getAnchorSelectionIndex
172 * @see #setSelectionInterval
173 * @see #addSelectionInterval
174 */
175 int getLeadSelectionIndex();
176
177 /**
178 * Set the lead selection index.
179 *
180 * @see #getLeadSelectionIndex
181 */
182 void setLeadSelectionIndex(int index);
183
184 /**
185 * Change the selection to the empty set. If this represents
186 * a change to the current selection then notify each ListSelectionListener.
187 *
188 * @see #addListSelectionListener
189 */
190 void clearSelection();
191
192 /**
193 * Returns true if no indices are selected.
194 */
195 boolean isSelectionEmpty();
196
197 /**
198 * Insert length indices beginning before/after index. This is typically
199 * called to sync the selection model with a corresponding change
200 * in the data model.
201 */
202 void insertIndexInterval(int index, int length, boolean before);
203
204 /**
205 * Remove the indices in the interval index0,index1 (inclusive) from
206 * the selection model. This is typically called to sync the selection
207 * model width a corresponding change in the data model.
208 */
209 void removeIndexInterval(int index0, int index1);
210
211 /**
212 * Sets the {@code valueIsAdjusting} property, which indicates whether
213 * or not upcoming selection changes should be considered part of a single
214 * change. The value of this property is used to initialize the
215 * {@code valueIsAdjusting} property of the {@code ListSelectionEvent}s that
216 * are generated.
217 * <p>
218 * For example, if the selection is being updated in response to a user
219 * drag, this property can be set to {@code true} when the drag is initiated
220 * and set to {@code false} when the drag is finished. During the drag,
221 * listeners receive events with a {@code valueIsAdjusting} property
222 * set to {@code true}. At the end of the drag, when the change is
223 * finalized, listeners receive an event with the value set to {@code false}.
224 * Listeners can use this pattern if they wish to update only when a change
225 * has been finalized.
226 * <p>
227 * Setting this property to {@code true} begins a series of changes that
228 * is to be considered part of a single change. When the property is changed
229 * back to {@code false}, an event is sent out characterizing the entire
230 * selection change (if there was one), with the event's
231 * {@code valueIsAdjusting} property set to {@code false}.
232 *
233 * @param valueIsAdjusting the new value of the property
234 * @see #getValueIsAdjusting
235 * @see javax.swing.event.ListSelectionEvent#getValueIsAdjusting
236 */
237 void setValueIsAdjusting(boolean valueIsAdjusting);
238
239 /**
240 * Returns {@code true} if the selection is undergoing a series of changes.
241 *
242 * @return true if the selection is undergoing a series of changes
243 * @see #setValueIsAdjusting
244 */
245 boolean getValueIsAdjusting();
246
247 /**
248 * Sets the selection mode. The following list describes the accepted
249 * selection modes:
250 * <ul>
251 * <li>{@code ListSelectionModel.SINGLE_SELECTION} -
252 * Only one list index can be selected at a time. In this mode,
253 * {@code setSelectionInterval} and {@code addSelectionInterval} are
254 * equivalent, both replacing the current selection with the index
255 * represented by the second argument (the "lead").
256 * <li>{@code ListSelectionModel.SINGLE_INTERVAL_SELECTION} -
257 * Only one contiguous interval can be selected at a time.
258 * In this mode, {@code addSelectionInterval} behaves like
259 * {@code setSelectionInterval} (replacing the current selection),
260 * unless the given interval is immediately adjacent to or overlaps
261 * the existing selection, and can therefore be used to grow it.
262 * <li>{@code ListSelectionModel.MULTIPLE_INTERVAL_SELECTION} -
263 * In this mode, there's no restriction on what can be selected.
264 * </ul>
265 *
266 * @see #getSelectionMode
267 * @throws IllegalArgumentException if the selection mode isn't
268 * one of those allowed
269 */
270 void setSelectionMode(int selectionMode);
271
272 /**
273 * Returns the current selection mode.
274 *
275 * @return the current selection mode
276 * @see #setSelectionMode
277 */
278 int getSelectionMode();
279
280 /**
281 * Add a listener to the list that's notified each time a change
282 * to the selection occurs.
283 *
284 * @param x the ListSelectionListener
285 * @see #removeListSelectionListener
286 * @see #setSelectionInterval
287 * @see #addSelectionInterval
288 * @see #removeSelectionInterval
289 * @see #clearSelection
290 * @see #insertIndexInterval
291 * @see #removeIndexInterval
292 */
293 void addListSelectionListener(ListSelectionListener x);
294
295 /**
296 * Remove a listener from the list that's notified each time a
297 * change to the selection occurs.
298 *
299 * @param x the ListSelectionListener
300 * @see #addListSelectionListener
301 */
302 void removeListSelectionListener(ListSelectionListener x);
303 }
|