summaryrefslogtreecommitdiff
path: root/libjava/classpath/javax/swing/ListSelectionModel.java
blob: 1cd67e9489a4286a40cacb585dface80ecf3e485 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
/* ListSelectionModel.java --
   Copyright (C) 2002, 2006, Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */


package javax.swing;

import javax.swing.event.ListSelectionEvent;
import javax.swing.event.ListSelectionListener;

/**
 * A model that tracks the selection status of a list of items.  Each item in
 * the list is identified by a zero-based index only, so the model can be used
 * to track the selection status of any type of list.  The model
 * supports three modes:
 * <ul>
 * <li><code>SINGLE_SELECTION</code> - only one item in the list may be
 *     selected;</li>
 * <li><code>SINGLE_INTERVAL_SELECTION</code> - only one interval in the list
 *     may be selected;</li>
 * <li><code>MULTIPLE_INTERVAL_SELECTION</code> - any combination of items in
 *     the list may be selected.</li>
 * </ul>
 * The model uses an event notification mechanism to notify listeners (see
 * {@link ListSelectionListener}) about updates to the selection model.
 * <p>
 * This model is used to track row selections in the {@link JList} component,
 * and row and column selections in the {@link JTable} component.
 */
public interface ListSelectionModel
{

  /**
   * A selection mode in which only one item can be selected.
   *
   * @see #setSelectionMode(int)
   */
  int SINGLE_SELECTION = 0;

  /**
   * A selection mode in which a single interval can be selected (an interval
   * is a range containing one or more contiguous items).
   *
   * @see #setSelectionMode(int)
   */
  int SINGLE_INTERVAL_SELECTION = 1;

  /**
   * A selection mode in which any combination of items can be selected.
   *
   * @see #setSelectionMode(int)
   */
  int MULTIPLE_INTERVAL_SELECTION = 2;

  /**
   * Sets the selection mode.
   * <p>
   * FIXME: The spec is silent about what happens to existing selections, for
   * example when changing from an interval selection to single selection.
   *
   * @param mode  one of {@link #SINGLE_SELECTION},
   *     {@link #SINGLE_INTERVAL_SELECTION} and
   *     {@link #MULTIPLE_INTERVAL_SELECTION}.
   *
   * @see #getSelectionMode()
   *
   * @throws IllegalArgumentException if <code>mode</code> is not one of the
   *     specified values.
   */
  void setSelectionMode(int mode);

  /**
   * Returns the selection mode, which is one of {@link #SINGLE_SELECTION},
   * {@link #SINGLE_INTERVAL_SELECTION} and
   * {@link #MULTIPLE_INTERVAL_SELECTION}.
   *
   * @return The selection mode.
   *
   * @see #setSelectionMode(int)
   */
  int getSelectionMode();

  /**
   * Clears the current selection from the model.  If the selection state
   * changes (that is, the existing selection is non-empty) a
   * {@link ListSelectionEvent} should be sent to all registered listeners.
   * <p>
   * FIXME: what happens to the anchor and lead selection indices (the spec
   * is silent about this)?  See:
   * <p>
   * http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4334792
   */
  void clearSelection();

  /**
   * Returns the lowest selected index, or <code>-1</code> if there is no
   * selection.
   *
   * @return The lowest selected index.
   *
   * @see #getMaxSelectionIndex()
   */
  int getMinSelectionIndex();

  /**
   * Returns the highest selected index, or <code>-1</code> if there is no
   * selection.
   *
   * @return The highest selected index.
   *
   * @see #getMinSelectionIndex()
   */
  int getMaxSelectionIndex();

  /**
   * Returns <code>true</code> if the specified item is selected, and
   * <code>false</code> otherwise.  Special note: if <code>index</code> is
   * negative, this method should return <code>false</code> (no exception
   * should be thrown).
   *
   * @param index  the item index (zero-based).
   *
   * @return <code>true</code> if the specified item is selected, and
   *     <code>false</code> otherwise.
   */
  boolean isSelectedIndex(int index);

  /**
   * Returns <code>true</code> if there is no selection, and <code>false</code>
   * otherwise.
   *
   * @return  <code>true</code> if there is no selection, and
   *     <code>false</code> otherwise.
   */
  boolean isSelectionEmpty();

  /**
   * Sets the selection interval to the specified range (note that
   * <code>anchor</code> can be less than, equal to, or greater than
   * <code>lead</code>).  If this results in the selection being changed,
   * a {@link ListSelectionEvent} is sent to all registered listeners.
   * <p>
   * If the selection mode is {@link #SINGLE_SELECTION}, only the
   * <code>lead</code> item is selected.
   *
   * @param anchor  the anchor index.
   * @param lead  the lead index.
   */
  void setSelectionInterval(int anchor, int lead);

  /**
   * Marks the items in the specified interval as selected.  The behaviour of
   * this method depends on the selection mode:
   * <ul>
   * <li><code>SINGLE_SELECTION</code> - only the <code>lead</code> item is
   *     selected;</li>
   * <li><code>SINGLE_INTERVAL_SELECTION</code> - the existing selection
   *     interval is replaced by the specified interval;</li>
   * <li><code>MULTIPLE_INTERVAL_SELECTION</code> - the specified interval is
   *     merged into the currently selected intervals.</li>
   * </ul>
   * Note that <code>anchor</code> can be less than, equal to, or greater than
   * <code>lead</code>.
   *
   * @param anchor  the index of the anchor item
   * @param lead  the index of the lead item.
   */
  void addSelectionInterval(int anchor, int lead);

  /**
   * Marks the items in the specified interval as not selected.  The behaviour
   * of this method depends on the selection mode:
   * <ul>
   * <li><code>SINGLE_SELECTION</code> - XXX;</li>
   * <li><code>SINGLE_INTERVAL_SELECTION</code> - XXX;</li>
   * <li><code>MULTIPLE_INTERVAL_SELECTION</code> - XXX.</li>
   * </ul>
   * Note that <code>anchor</code> can be less than, equal to, or greater than
   * <code>lead</code>.
   *
   * @param anchor  the index of the anchor item
   * @param lead  the index of the lead item.
   */
  void removeSelectionInterval(int anchor, int lead);

  /**
   * Inserts a new interval containing <code>length</code> items at the
   * specified <code>index</code> (the <code>before</code> flag indicates
   * whether the range is inserted before or after the existing item at
   * <code>index</code>).
   *
   * FIXME: What is the selection status of the new items? Bug 4870694.
   * FIXME: What event is generated?
   *
   * @param index  the index of the item.
   * @param length  the number of items in the interval to be inserted.
   * @param before  if <code>true</code>, the interval should be inserted
   *     before <code>index</code>, otherwise it is inserted after.
   *
   * @see #removeIndexInterval(int, int)
   */
  void insertIndexInterval(int index, int length, boolean before);

  /**
   * Removes the items in the specified range (inclusive) from the selection
   * model.  This method should be called when an interval is deleted from
   * the underlying list.
   *
   * FIXME: what happens to the lead and anchor indices if they are part of
   * the range that is removed?
   * FIXME: what event is generated
   *
   * @param index0  XXX
   * @param index1  XXX
   *
   * @see #insertIndexInterval(int, int, boolean)
   */
  void removeIndexInterval(int index0, int index1);

  /**
   * Returns the index of the anchor item.
   *
   * @return The index of the anchor item.
   *
   * @see #setAnchorSelectionIndex(int)
   */
  int getAnchorSelectionIndex();

  /**
   * Sets the index of the anchor item.
   *
   * @param index  the item index.
   *
   * @see #getAnchorSelectionIndex()
   */
  void setAnchorSelectionIndex(int index);

  /**
   * Returns the index of the lead item.
   *
   * @return The index of the lead item.
   *
   * @see #setLeadSelectionIndex(int)
   */
  int getLeadSelectionIndex();

  /**
   * Sets the index of the lead item.
   *
   * @param index  the item index.
   *
   * @see #getLeadSelectionIndex()
   */
  void setLeadSelectionIndex(int index);

  /**
   * Sets the flag that is passed to listeners for each change notification.
   * If a sequence of changes is made to the selection model, this flag should
   * be set to <code>true</code> at the start of the sequence, and
   * <code>false</code> for the last change - this gives listeners the option
   * to ignore interim changes if that is more efficient.
   *
   * @param valueIsAdjusting  the flag value.
   *
   * @see #getValueIsAdjusting()
   */
  void setValueIsAdjusting(boolean valueIsAdjusting);

  /**
   * Returns a flag that is passed to registered listeners when changes are
   * made to the model.  See the description for
   * {@link #setValueIsAdjusting(boolean)} for more information.
   *
   * @return The flag.
   */
  boolean getValueIsAdjusting();

  /**
   * Registers a listener with the model so that it receives notification
   * of changes to the model.
   *
   * @param listener  the listener (<code>null</code> ignored).
   *
   * @see #removeListSelectionListener(ListSelectionListener)
   */
  void addListSelectionListener(ListSelectionListener listener);

  /**
   * Deregisters a listener so that it no longer receives notification of
   * changes to the model.  If the specified listener is not registered with
   * the model, or is <code>null</code>, this method does nothing.
   *
   * @param listener  the listener (<code>null</code> ignored).
   *
   * @see #addListSelectionListener(ListSelectionListener)
   */
  void removeListSelectionListener(ListSelectionListener listener);

}