1. /*
  2. * @(#)ListSelectionModel.java 1.20 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.swing;
  8. import javax.swing.event.*;
  9. /**
  10. * This interface represents the current state of the
  11. * selection for any of the components that display a
  12. * list of values with stable indices. The selection is
  13. * modeled as a set of intervals, each interval represents
  14. * a contiguous range of selected list elements.
  15. * The methods for modifying the set of selected intervals
  16. * all take a pair of indices, index0 and index1, that represent
  17. * a closed interval, i.e. the interval includes both index0 and
  18. * index1.
  19. *
  20. * @version 1.20 01/23/03
  21. * @author Hans Muller
  22. * @author Philip Milne
  23. * @see DefaultListSelectionModel
  24. */
  25. public interface ListSelectionModel
  26. {
  27. /**
  28. * A value for the selectionMode property: select one list index
  29. * at a time.
  30. *
  31. * @see #setSelectionMode
  32. */
  33. int SINGLE_SELECTION = 0;
  34. /**
  35. * A value for the selectionMode property: select one contiguous
  36. * range of indices at a time.
  37. *
  38. * @see #setSelectionMode
  39. */
  40. int SINGLE_INTERVAL_SELECTION = 1;
  41. /**
  42. * A value for the selectionMode property: select one or more
  43. * contiguous ranges of indices at a time.
  44. *
  45. * @see #setSelectionMode
  46. */
  47. int MULTIPLE_INTERVAL_SELECTION = 2;
  48. /**
  49. * Change the selection to be between index0 and index1 inclusive.
  50. * If this represents a change to the current selection, then
  51. * notify each ListSelectionListener. Note that index0 doesn't have
  52. * to be less than or equal to index1.
  53. *
  54. * @param index0 one end of the interval.
  55. * @param index1 other end of the interval
  56. * @see #addListSelectionListener
  57. */
  58. void setSelectionInterval(int index0, int index1);
  59. /**
  60. * Change the selection to be the set union of the current selection
  61. * and the indices between index0 and index1 inclusive. If this represents
  62. * a change to the current selection, then notify each
  63. * ListSelectionListener. Note that index0 doesn't have to be less
  64. * than or equal to index1.
  65. *
  66. * @param index0 one end of the interval.
  67. * @param index1 other end of the interval
  68. * @see #addListSelectionListener
  69. */
  70. void addSelectionInterval(int index0, int index1);
  71. /**
  72. * Change the selection to be the set difference of the current selection
  73. * and the indices between index0 and index1 inclusive. If this represents
  74. * a change to the current selection, then notify each
  75. * ListSelectionListener. Note that index0 doesn't have to be less
  76. * than or equal to index1.
  77. *
  78. * @param index0 one end of the interval.
  79. * @param index1 other end of the interval
  80. * @see #addListSelectionListener
  81. */
  82. void removeSelectionInterval(int index0, int index1);
  83. /**
  84. * Returns the first selected index or -1 if the selection is empty.
  85. */
  86. int getMinSelectionIndex();
  87. /**
  88. * Returns the last selected index or -1 if the selection is empty.
  89. */
  90. int getMaxSelectionIndex();
  91. /**
  92. * Returns true if the specified index is selected.
  93. */
  94. boolean isSelectedIndex(int index);
  95. /**
  96. * Return the first index argument from the most recent call to
  97. * setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
  98. * The most recent index0 is considered the "anchor" and the most recent
  99. * index1 is considered the "lead". Some interfaces display these
  100. * indices specially, e.g. Windows95 displays the lead index with a
  101. * dotted yellow outline.
  102. *
  103. * @see #getLeadSelectionIndex
  104. * @see #setSelectionInterval
  105. * @see #addSelectionInterval
  106. */
  107. int getAnchorSelectionIndex();
  108. /**
  109. * Set the anchor selection index.
  110. *
  111. * @see #getAnchorSelectionIndex
  112. */
  113. void setAnchorSelectionIndex(int index);
  114. /**
  115. * Return the second index argument from the most recent call to
  116. * setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
  117. *
  118. * @see #getAnchorSelectionIndex
  119. * @see #setSelectionInterval
  120. * @see #addSelectionInterval
  121. */
  122. int getLeadSelectionIndex();
  123. /**
  124. * Set the lead selection index.
  125. *
  126. * @see #getLeadSelectionIndex
  127. */
  128. void setLeadSelectionIndex(int index);
  129. /**
  130. * Change the selection to the empty set. If this represents
  131. * a change to the current selection then notify each ListSelectionListener.
  132. *
  133. * @see #addListSelectionListener
  134. */
  135. void clearSelection();
  136. /**
  137. * Returns true if no indices are selected.
  138. */
  139. boolean isSelectionEmpty();
  140. /**
  141. * Insert length indices beginning before/after index. This is typically
  142. * called to sync the selection model with a corresponding change
  143. * in the data model.
  144. */
  145. void insertIndexInterval(int index, int length, boolean before);
  146. /**
  147. * Remove the indices in the interval index0,index1 (inclusive) from
  148. * the selection model. This is typically called to sync the selection
  149. * model width a corresponding change in the data model.
  150. */
  151. void removeIndexInterval(int index0, int index1);
  152. /**
  153. * This property is true if upcoming changes to the value
  154. * of the model should be considered a single event. For example
  155. * if the model is being updated in response to a user drag,
  156. * the value of the valueIsAdjusting property will be set to true
  157. * when the drag is initiated and be set to false when
  158. * the drag is finished. This property allows listeners to
  159. * to update only when a change has been finalized, rather
  160. * than always handling all of the intermediate values.
  161. *
  162. * @param valueIsAdjusting The new value of the property.
  163. * @see #getValueIsAdjusting
  164. */
  165. void setValueIsAdjusting(boolean valueIsAdjusting);
  166. /**
  167. * Returns true if the value is undergoing a series of changes.
  168. * @return true if the value is currently adjusting
  169. * @see #setValueIsAdjusting
  170. */
  171. boolean getValueIsAdjusting();
  172. /**
  173. * Set the selection mode. The following selectionMode values are allowed:
  174. * <ul>
  175. * <li> <code>SINGLE_SELECTION</code>
  176. * Only one list index can be selected at a time. In this
  177. * mode the setSelectionInterval and addSelectionInterval
  178. * methods are equivalent, and only the second index
  179. * argument (the "lead index") is used.
  180. * <li> <code>SINGLE_INTERVAL_SELECTION</code>
  181. * One contiguous index interval can be selected at a time.
  182. * In this mode setSelectionInterval and addSelectionInterval
  183. * are equivalent.
  184. * <li> <code>MULTIPLE_INTERVAL_SELECTION</code>
  185. * In this mode, there's no restriction on what can be selected.
  186. * </ul>
  187. *
  188. * @see #getSelectionMode
  189. */
  190. void setSelectionMode(int selectionMode);
  191. /**
  192. * Returns the current selection mode.
  193. * @return The value of the selectionMode property.
  194. * @see #setSelectionMode
  195. */
  196. int getSelectionMode();
  197. /**
  198. * Add a listener to the list that's notified each time a change
  199. * to the selection occurs.
  200. *
  201. * @param x the ListSelectionListener
  202. * @see #removeListSelectionListener
  203. * @see #setSelectionInterval
  204. * @see #addSelectionInterval
  205. * @see #removeSelectionInterval
  206. * @see #clearSelection
  207. * @see #insertIndexInterval
  208. * @see #removeIndexInterval
  209. */
  210. void addListSelectionListener(ListSelectionListener x);
  211. /**
  212. * Remove a listener from the list that's notified each time a
  213. * change to the selection occurs.
  214. *
  215. * @param x the ListSelectionListener
  216. * @see #addListSelectionListener
  217. */
  218. void removeListSelectionListener(ListSelectionListener x);
  219. }