1 /* DefaultListModel.java -- 2 Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 package javax.swing; 39 40 import java.util.Enumeration; 41 import java.util.Vector; 42 43 /** 44 * The default implementation of {@link AbstractListModel}, used by 45 * {@link javax.swing.JList} and similar objects as the model of a list of 46 * values. The implementation is based on an underlying {@link 47 * java.util.Vector}. 48 * 49 * @author Andrew Selkirk 50 * @author Graydon Hoare (graydon@redhat.com) 51 */ 52 53 public class DefaultListModel extends AbstractListModel 54 { 55 private static final long serialVersionUID = 2315945659722172272L; 56 57 /** 58 * The vector of elements in this list model. 59 */ 60 private Vector elements = new Vector(); 61 62 /** 63 * Gets an element of the list at the provided index. 64 * 65 * @param index The index of the element to get 66 * 67 * @return The object at the given index 68 * 69 * @throws ArrayIndexOutOfBoundsException If the provided index is 70 * outside the bounds of the list <code>[0, size())</code> 71 */ elementAt(int index)72 public Object elementAt(int index) 73 { 74 return elements.elementAt(index); 75 } 76 77 /** 78 * Convert the list to a string representation. 79 * 80 * @return A string representation of the list 81 */ toString()82 public String toString() 83 { 84 return elements.toString(); 85 } 86 87 /** 88 * Gets the first index of a particular element in the list. 89 * 90 * @param element The element to search for 91 * 92 * @return The first index in the list at which an object 93 * <code>obj</code> exists such that <code>obj.equals(element)</code> is 94 * <code>true</code>; if no such object exists, the method returns 95 * <code>-1</code> 96 */ indexOf(Object element)97 public int indexOf(Object element) 98 { 99 return elements.indexOf(element); 100 } 101 102 /** 103 * Gets the first index of a particular element in a list which occurs 104 * <em>at or after</em> a particular index. 105 * 106 * @param element The element to search for 107 * @param startIndex The index to begin searching at 108 * 109 * @return The first index in the list, greater than or equal to 110 * <code>startIndex</code>, at which an object <code>obj</code> exists 111 * such that <code>obj.equals(element)</code> is <code>true</code>; if no 112 * such object exists, the method returns <code>-1</code> 113 */ indexOf(Object element, int startIndex)114 public int indexOf(Object element, int startIndex) 115 { 116 return elements.indexOf(element, startIndex); 117 } 118 119 /** 120 * Gets the last index of a particular element in the list. 121 * 122 * @param element The element to search for 123 * 124 * @return The last index in the list at which an object 125 * <code>obj</code> exists such that <code>obj.equals(element)</code> is 126 * <code>true</code>; if no such object exists, the method returns 127 * <code>-1</code> 128 */ lastIndexOf(Object element)129 public int lastIndexOf(Object element) 130 { 131 return elements.lastIndexOf(element); 132 } 133 134 /** 135 * Gets the last index of a particular element in a list which occurs 136 * <em>at or before</em> a particular index. 137 * 138 * @param element The element to search for 139 * @param endIndex The index to finish searching at 140 * 141 * @return The last index in the list, less than to or equal to 142 * <code>endIndexIndex</code>, at which an object <code>obj</code> exists 143 * such that <code>obj.equals(element)</code> is <code>true</code>; if no 144 * such object exists, the method returns <code>-1</code> 145 */ lastIndexOf(Object element, int endIndex)146 public int lastIndexOf(Object element, int endIndex) 147 { 148 return elements.lastIndexOf(element, endIndex); 149 } 150 151 /** 152 * Gets the list element at a particular index. 153 * 154 * @param index The index to get the list value at 155 * 156 * @return The list value at the provided index 157 * 158 * @throws ArrayIndexOutOfBoundsException If the provided index is 159 * outside the bounds of the list <code>[0, size())</code> 160 */ get(int index)161 public Object get(int index) 162 { 163 return elements.get(index); 164 } 165 166 /** 167 * Sets the list element at a particular index. 168 * 169 * @param index The list index at which to set a value 170 * @param element The value to set at the specified index 171 * 172 * @return The value previously held at the specified index 173 * 174 * @throws ArrayIndexOutOfBoundsException If the provided index is 175 * outside the bounds of the list <code>[0, size())</code> 176 */ set(int index, Object element)177 public Object set(int index, Object element) 178 { 179 Object result; 180 result = elements.set(index, element); 181 fireContentsChanged(this, index, index); 182 return result; 183 } 184 185 /** 186 * Inserts an element at a particular index in the list. Each element at 187 * index <code>i >= index</code> is shifted to position <code>i + 1</code>. 188 * If <code>index</code> is equal to <code>size()</code>, this is 189 * equivalent to appending an element to the array. Any 190 * <code>index</code> greater than <code>size()</code> is illegal. 191 * 192 * @param index The index to insert the element at 193 * @param element The element to insert at the index 194 * 195 * @throws ArrayIndexOutOfBoundsException If the provided index is 196 * outside the bounds <code>[0, size()]</code> 197 */ add(int index, Object element)198 public void add(int index, Object element) 199 { 200 elements.add(index, element); 201 fireIntervalAdded(this, index, index); 202 } 203 204 /** 205 * Inserts an element at the end of the list. This is equivalent to 206 * calling <code>list.add(list.size(), element)</code>. 207 * 208 * @param element The element to add to the list 209 */ addElement(Object element)210 public void addElement(Object element) 211 { 212 int s = elements.size(); 213 elements.add(element); 214 fireIntervalAdded(this, s, s); 215 } 216 217 /** 218 * Gets the number of elements in the list. 219 * 220 * @return The number of elements in the list 221 */ size()222 public int size() 223 { 224 return elements.size(); 225 } 226 227 /** 228 * Gets an array containing the elements of the list. 229 * 230 * @return An array of the objects in the list, in the order they occur 231 * in the list 232 */ toArray()233 public Object[] toArray() 234 { 235 return elements.toArray(); 236 } 237 238 /** 239 * Determines whether a particular element is a member of the list. 240 * 241 * @param element The element to search for 242 * 243 * @return <code>true</code> if <code>element</code> is a member of the 244 * list, otherwise <code>false</code> 245 */ contains(Object element)246 public boolean contains(Object element) 247 { 248 return elements.contains(element); 249 } 250 251 /** 252 * Copies the list into a provided array. The provided array must be at 253 * least as large as the list. 254 * 255 * @param array The array to copy the list into 256 * 257 * @throws IndexOutOfBoundsException if the array is too small to hold the 258 * elements of the list 259 */ copyInto(Object[] array)260 public void copyInto(Object[] array) 261 { 262 elements.copyInto(array); 263 } 264 265 /** 266 * Erases all the elements of the list, setting the list's size to 0. 267 */ clear()268 public void clear() 269 { 270 int s = elements.size(); 271 if (s > 0) 272 { 273 elements.clear(); 274 fireIntervalRemoved(this, 0, s - 1); 275 } 276 } 277 278 /** 279 * Removes the element at a particular index from the list. 280 * 281 * @param index The index of the element to remove 282 * 283 * @return The value at the index, which has been removed from the list 284 * 285 * @throws ArrayIndexOutOfBoundsException If the provided index is 286 * outside the bounds of the list <code>[0, size())</code> 287 */ remove(int index)288 public Object remove(int index) 289 { 290 Object result; 291 result = elements.remove(index); 292 fireIntervalRemoved(this, index, index); 293 return result; 294 } 295 296 /** 297 * Determines whether the list is empty. 298 * 299 * @return <code>true</code> if the list is empty, otherwise 300 * <code>false</code> 301 */ isEmpty()302 public boolean isEmpty() 303 { 304 return elements.isEmpty(); 305 } 306 307 /** 308 * Returns an {@link java.util.Enumeration} over the elements of the list. 309 * 310 * @return A new enumeration which iterates over the list 311 */ elements()312 public Enumeration<?> elements() 313 { 314 return elements.elements(); 315 } 316 317 /** 318 * Sets the capacity of the list to be equal to its size. The list's capacity 319 * is the number of elements it can hold before it needs to be reallocated. 320 * The list's size is the number of elements it currently holds. 321 */ trimToSize()322 public void trimToSize() 323 { 324 elements.trimToSize(); 325 } 326 327 /** 328 * Ensures that the list's capacity is at least equal to 329 * <code>size</code>. The list's capacity is the number of elements it 330 * can hold before it needs to be reallocated. 331 * 332 * @param size The capacity to ensure the list can hold 333 */ ensureCapacity(int size)334 public void ensureCapacity(int size) 335 { 336 elements.ensureCapacity(size); 337 } 338 339 /** 340 * Sets the size of the list to a particular value. If the specified size 341 * is greater than the current size, the values at the excess list 342 * indices are set to <code>null</code>. If the specified size is less 343 * than the current size, the excess elements are removed from the list. 344 * 345 * @param size The new size to set the list to 346 */ setSize(int size)347 public void setSize(int size) 348 { 349 int oldSize = elements.size(); 350 elements.setSize(size); 351 if (oldSize < size) 352 { 353 fireIntervalAdded(this, oldSize, size - 1); 354 } 355 else if (oldSize > size) 356 { 357 this.fireIntervalRemoved(this, size, oldSize - 1); 358 } 359 } 360 361 /** 362 * Gets the capacity of the list. The list's capacity is the number of 363 * elements it can hold before it needs to be reallocated. 364 * 365 * @return The capacity of the list 366 */ capacity()367 public int capacity() 368 { 369 return elements.capacity(); 370 } 371 372 /** 373 * Gets the first element in the list. 374 * 375 * @return The first element in the list 376 */ firstElement()377 public Object firstElement() 378 { 379 return elements.firstElement(); 380 } 381 382 /** 383 * Gets the last element in the list. 384 * 385 * @return The last element in the list 386 */ lastElement()387 public Object lastElement() 388 { 389 return elements.lastElement(); 390 } 391 392 /** 393 * Sets the list element at a particular index. 394 * 395 * @param element The value to set at the specified index 396 * @param index The list index at which to set a value 397 * 398 * @throws ArrayIndexOutOfBoundsException If the provided index is 399 * outside the bounds of the list <code>[0, size())</code> 400 */ setElementAt(Object element, int index)401 public void setElementAt(Object element, int index) 402 { 403 elements.setElementAt(element, index); 404 fireContentsChanged(this, index, index); 405 } 406 407 /** 408 * Removes the element at a particular index from the list. 409 * 410 * @param index The index of the element to remove 411 * 412 * @throws ArrayIndexOutOfBoundsException If the provided index is 413 * outside the bounds of the list <code>[0, size())</code> 414 */ removeElementAt(int index)415 public void removeElementAt(int index) 416 { 417 elements.remove(index); 418 fireIntervalRemoved(this, index, index); 419 } 420 421 /** 422 * Inserts an element at a particular index in the list. Each element at 423 * index <code>i >= index</code> is shifted to position <code>i + 1</code>. 424 * If <code>index</code> is equal to <code>size()</code>, this is 425 * equivalent to appending an element to the array. Any 426 * <code>index</code> greater than <code>size()</code> is illegal. 427 * 428 * @param element The element to insert at the index 429 * @param index The index to insert the element at 430 * 431 * @throws ArrayIndexOutOfBoundsException If the provided index is 432 * outside the bounds <code>[0, size()]</code> 433 */ insertElementAt(Object element, int index)434 public void insertElementAt(Object element, int index) 435 { 436 elements.insertElementAt(element, index); 437 fireIntervalAdded(this, index, index); 438 } 439 440 /** 441 * Removes the first occurrence of a particular element in the list. If the 442 * element does not exist in the list, nothing happens. 443 * 444 * @param element The element to remove 445 * 446 * @return <code>true</code> if the element existed in the list (and was 447 * removed), <code>false</code> otherwise 448 */ removeElement(Object element)449 public boolean removeElement(Object element) 450 { 451 int index; 452 index = elements.indexOf(element); 453 if (index != -1) 454 { 455 elements.remove(index); 456 fireIntervalRemoved(this, index, index); 457 return true; 458 } 459 return false; 460 } 461 462 /** 463 * Remove all elements in the list. 464 */ removeAllElements()465 public void removeAllElements() 466 { 467 int size; 468 size = size(); 469 if (size > 0) 470 { 471 elements.clear(); 472 fireIntervalRemoved(this, 0, size - 1); 473 } 474 } 475 476 /** 477 * Remove all elements between <code>startIndex</code> and 478 * <code>endIndex</code> inclusive. 479 * 480 * @param startIndex The first index in the range to remove 481 * @param endIndex The last index in the range to remove 482 * 483 * @throws ArrayIndexOutOfBoundsException if either index is outside the 484 * valid range of indices for this list <code>[0, size())</code> 485 * @throws IllegalArgumentException if <code>startIndex > endIndex</code> 486 */ removeRange(int startIndex, int endIndex)487 public void removeRange(int startIndex, int endIndex) 488 { 489 int index; 490 if (startIndex > endIndex) 491 throw new IllegalArgumentException(); 492 for (index = endIndex; index >= startIndex; index--) 493 elements.remove(index); 494 fireIntervalRemoved(this, startIndex, endIndex); 495 } 496 497 /** 498 * Gets the size of the list. 499 * 500 * @return The number of elements currently in the list 501 */ getSize()502 public int getSize() 503 { 504 return elements.size(); 505 } 506 507 /** 508 * Gets the list element at a particular index. 509 * 510 * @param index The index to get the list value at 511 * 512 * @return The list value at the provided index 513 * 514 * @throws ArrayIndexOutOfBoundsException If the provided index is 515 * outside the bounds of the list <code>[0, size())</code> 516 */ getElementAt(int index)517 public Object getElementAt(int index) 518 { 519 return elements.get(index); 520 } 521 } 522