Source for javax.swing.DefaultListModel

   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:    */
  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 &gt; 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: }