libjava/javax/swing/DefaultListModel.java

   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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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  * This is a default subclass of the {@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    */
  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    */
  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    */
  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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 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    */
 517   public Object getElementAt(int index)
 518   {
 519     return elements.get(index);
 520   }
 521 }