libjava/java/awt/Choice.java

   1 /* Choice.java -- Java choice button widget.
   2    Copyright (C) 1999, 2000, 2001, 2002 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
  39 package java.awt;
  40
  41 import java.awt.event.ItemEvent;
  42 import java.awt.event.ItemListener;
  43 import java.awt.peer.ChoicePeer;
  44 import java.io.Serializable;
  45 import java.util.EventListener;
  46 import java.util.Vector;
  47
  48 /**
  49   * This class implements a drop down choice list.
  50   *
  51   * @author Aaron M. Renn (arenn@urbanophile.com)
  52   */
  53 public class Choice extends Component implements ItemSelectable, Serializable
  54 {
  55
  56 /*
  57  * Static Variables
  58  */
  59
  60 // Serialization constant
  61 private static final long serialVersionUID = -4075310674757313071L;
  62
  63 /*************************************************************************/
  64
  65 /*
  66  * Instance Variables
  67  */
  68
  69 /**
  70   * @serial A list of items for the choice box, which can be <code>null</code>.
  71   */
  72 private Vector pItems = new Vector();
  73
  74 /**
  75   * @serial The index of the selected item in the choice box.
  76   */
  77 private int selectedIndex = -1;
  78
  79 // Listener chain
  80 private ItemListener item_listeners;
  81
  82 /*************************************************************************/
  83
  84 /*
  85  * Constructors
  86  */
  87
  88   /**
  89    * Initializes a new instance of <code>Choice</code>.
  90    *
  91    * @exception HeadlessException If GraphicsEnvironment.isHeadless()
  92    * returns true
  93    */
  94   public Choice()
  95   {
  96     if (GraphicsEnvironment.isHeadless())
  97       throw new HeadlessException ();
  98   }
  99
 100 /*************************************************************************/
 101
 102 /*
 103  * Instance Methods
 104  */
 105
 106 /**
 107   * Returns the number of items in the list.
 108   *
 109   * @return The number of items in the list.
 110   */
 111 public int
 112 getItemCount()
 113 {
 114   return(pItems.size());
 115 }
 116
 117 /*************************************************************************/
 118
 119 /**
 120   * Returns the number of items in the list.
 121   *
 122   * @return The number of items in the list.
 123   *
 124   * @deprecated This method is deprecated in favor of <code>getItemCount</code>.
 125   */
 126 public int
 127 countItems()
 128 {
 129   return(pItems.size());
 130 }
 131
 132 /*************************************************************************/
 133
 134 /**
 135   * Returns the item at the specified index in the list.
 136   *
 137   * @param index The index into the list to return the item from.
 138   *
 139   * @exception ArrayIndexOutOfBoundsException If the index is invalid.
 140   */
 141 public String
 142 getItem(int index)
 143 {
 144   return((String)pItems.elementAt(index));
 145 }
 146
 147 /*************************************************************************/
 148
 149 /**
 150   * Adds the specified item to this choice box.
 151   *
 152   * @param item The item to add.
 153   *
 154   * @exception NullPointerException If the item's value is null
 155   *
 156   * @since 1.1
 157   */
 158 public synchronized void
 159 add(String item)
 160 {
 161   if (item == null)
 162     throw new NullPointerException ("item must be non-null");
 163
 164   pItems.addElement(item);
 165
 166   int i = pItems.size () - 1;
 167   if (peer != null)
 168     {
 169       ChoicePeer cp = (ChoicePeer) peer;
 170       cp.add (item, i);
 171     }
 172
 173   if (i == 0)
 174   {
 175     selectedIndex = 0;
 176     // We must generate an ItemEvent here
 177     Toolkit.getDefaultToolkit().getSystemEventQueue().postEvent (
 178       new ItemEvent ((ItemSelectable)this,
 179                      ItemEvent.ITEM_STATE_CHANGED,
 180                      getItem(0),
 181                      ItemEvent.SELECTED));
 182   }
 183 }
 184
 185 /*************************************************************************/
 186
 187 /**
 188   * Adds the specified item to this choice box.
 189   *
 190   * This method is oboslete since Java 2 platform 1.1. Please use @see add
 191   * instead.
 192   *
 193   * @param item The item to add.
 194   *
 195   * @exception NullPointerException If the item's value is equal to null
 196   */
 197 public synchronized void
 198 addItem(String item)
 199 {
 200   add(item);
 201 }
 202
 203 /*************************************************************************/
 204
 205 /** Inserts an item into this Choice.  Existing items are shifted
 206  * upwards.  If the new item is the only item, then it is selected.
 207  * If the currently selected item is shifted, then the first item is
 208  * selected.  If the currently selected item is not shifted, then it
 209  * remains selected.
 210  *
 211  * @param item The item to add.
 212  * @param index The index at which the item should be inserted.
 213  *
 214  * @exception IllegalArgumentException If index is less than 0
 215  */
 216 public synchronized void
 217 insert(String item, int index)
 218 {
 219   if (index < 0)
 220     throw new IllegalArgumentException ("index may not be less then 0");
 221
 222   if (index > getItemCount ())
 223     index = getItemCount ();
 224
 225   pItems.insertElementAt(item, index);
 226
 227   if (peer != null)
 228     {
 229       ChoicePeer cp = (ChoicePeer) peer;
 230       cp.add (item, index);
 231     }
 232
 233   if (getItemCount () == 1 || selectedIndex >= index)
 234   {
 235     select (0);
 236     // We must generate an ItemEvent here
 237     Toolkit.getDefaultToolkit().getSystemEventQueue().postEvent (
 238       new ItemEvent ((ItemSelectable)this,
 239                      ItemEvent.ITEM_STATE_CHANGED,
 240                      getItem(0),
 241                      ItemEvent.SELECTED));
 242   }
 243 }
 244
 245 /*************************************************************************/
 246
 247 /**
 248   * Removes the specified item from the choice box.
 249   *
 250   * @param item The item to remove.
 251   *
 252   * @exception IllegalArgumentException If the specified item doesn't exist.
 253   */
 254 public synchronized void
 255 remove(String item)
 256 {
 257   int index = pItems.indexOf(item);
 258   if (index == -1)
 259     throw new IllegalArgumentException ("item \""
 260                                         + item + "\" not found in Choice");
 261   remove(index);
 262 }
 263
 264 /*************************************************************************/
 265
 266 /**
 267   * Removes the item at the specified index from the choice box.
 268   *
 269   * @param index The index of the item to remove.
 270   *
 271   * @exception IndexOutOfBoundsException If the index is not valid.
 272   */
 273 public synchronized void
 274 remove(int index)
 275 {
 276   pItems.removeElementAt(index);
 277
 278   if (peer != null)
 279     {
 280       ChoicePeer cp = (ChoicePeer) peer;
 281       cp.remove (index);
 282     }
 283
 284   if ((index == selectedIndex) && (getItemCount() > 0))
 285   {
 286     select (0);
 287     // We must generate an ItemEvent here
 288     Toolkit.getDefaultToolkit().getSystemEventQueue().postEvent (
 289       new ItemEvent ((ItemSelectable)this,
 290                      ItemEvent.ITEM_STATE_CHANGED,
 291                      getItem(0),
 292                      ItemEvent.SELECTED));
 293   }
 294   else if (selectedIndex > index)
 295     --selectedIndex;
 296 }
 297
 298 /*************************************************************************/
 299
 300 /**
 301   * Removes all of the objects from this choice box.
 302   */
 303 public synchronized void
 304 removeAll()
 305 {
 306   int count = getItemCount();
 307
 308   if (count <= 0)
 309     return;
 310
 311   ChoicePeer cp = (ChoicePeer) peer;
 312
 313   // Select the first item to prevent an spurious ItemEvent to be generated
 314   if (cp != null)
 315     {
 316       cp.select (0);
 317       selectedIndex = 0; // Just to keep consistent
 318     }
 319
 320   for (int i = (count - 1); i >= 0; i--)
 321     {
 322       // Always remove the last to avoid generation of ItemEvents.
 323       pItems.removeElementAt(i);
 324       if (cp != null)
 325         cp.remove (i);
 326     }
 327
 328   selectedIndex = -1;
 329 }
 330
 331 /*************************************************************************/
 332
 333 /**
 334   * Returns the currently selected item, or null if no item is
 335   * selected.
 336   *
 337   * @return The currently selected item.
 338   */
 339 public synchronized String
 340 getSelectedItem()
 341 {
 342   return (selectedIndex == -1
 343           ? null
 344           : ((String)pItems.elementAt(selectedIndex)));
 345 }
 346
 347 /*************************************************************************/
 348
 349 /**
 350   * Returns an array with one row containing the selected item.
 351   *
 352   * @return An array containing the selected item.
 353   */
 354 public synchronized Object[]
 355 getSelectedObjects()
 356 {
 357   if (selectedIndex == -1)
 358     return null;
 359
 360   Object[] objs = new Object[1];
 361   objs[0] = pItems.elementAt(selectedIndex);
 362
 363   return(objs);
 364 }
 365
 366 /*************************************************************************/
 367
 368 /**
 369   * Returns the index of the selected item.
 370   *
 371   * @return The index of the selected item.
 372   */
 373 public int
 374 getSelectedIndex()
 375 {
 376   return(selectedIndex);
 377 }
 378
 379 /*************************************************************************/
 380
 381 /**
 382   * Forces the item at the specified index to be selected.
 383   *
 384   * @param index The index of the row to make selected.
 385   *
 386   * @exception IllegalArgumentException If the specified index is invalid.
 387   */
 388 public synchronized void
 389 select(int index)
 390 {
 391   if ((index < 0) || (index > getItemCount()))
 392     throw new IllegalArgumentException("Bad index: " + index);
 393
 394   this.selectedIndex = index;
 395   if (peer != null)
 396     {
 397       ChoicePeer cp = (ChoicePeer) peer;
 398       cp.select (index);
 399     }
 400 }
 401
 402 /*************************************************************************/
 403
 404 /**
 405   * Forces the named item to be selected.
 406   *
 407   * @param item The item to be selected.
 408   *
 409   * @exception IllegalArgumentException If the specified item does not exist.
 410   */
 411 public synchronized void
 412 select(String item)
 413 {
 414   int index = pItems.indexOf(item);
 415   if (index >= 0)
 416     select(index);
 417 }
 418
 419 /*************************************************************************/
 420
 421 /**
 422   * Creates the native peer for this object.
 423   */
 424 public void
 425 addNotify()
 426 {
 427   if (peer == null)
 428     peer = getToolkit ().createChoice (this);
 429   super.addNotify ();
 430 }
 431
 432 /*************************************************************************/
 433
 434 /**
 435   * Adds the specified listener to the list of registered listeners for
 436   * this object.
 437   *
 438   * @param listener The listener to add.
 439   */
 440 public synchronized void
 441 addItemListener(ItemListener listener)
 442 {
 443   item_listeners = AWTEventMulticaster.add(item_listeners, listener);
 444 }
 445
 446 /*************************************************************************/
 447
 448 /**
 449   * Removes the specified listener from the list of registered listeners for
 450   * this object.
 451   *
 452   * @param listener The listener to remove.
 453   */
 454 public synchronized void
 455 removeItemListener(ItemListener listener)
 456 {
 457   item_listeners = AWTEventMulticaster.remove(item_listeners, listener);
 458 }
 459
 460 /*************************************************************************/
 461
 462 /**
 463   * Processes this event by invoking <code>processItemEvent()</code> if the
 464   * event is an instance of <code>ItemEvent</code>, otherwise the event
 465   * is passed to the superclass.
 466   *
 467   * @param event The event to process.
 468   */
 469 protected void
 470 processEvent(AWTEvent event)
 471 {
 472   if (event instanceof ItemEvent)
 473     processItemEvent((ItemEvent)event);
 474   else
 475     super.processEvent(event);
 476 }
 477
 478 /*************************************************************************/
 479
 480 /**
 481   * Processes item event by dispatching to any registered listeners.
 482   *
 483   * @param event The event to process.
 484   */
 485 protected void
 486 processItemEvent(ItemEvent event)
 487 {
 488   if (item_listeners != null)
 489     item_listeners.itemStateChanged(event);
 490 }
 491
 492 void
 493 dispatchEventImpl(AWTEvent e)
 494 {
 495   if (e.id <= ItemEvent.ITEM_LAST
 496       && e.id >= ItemEvent.ITEM_FIRST
 497       && (item_listeners != null
 498           || (eventMask & AWTEvent.ITEM_EVENT_MASK) != 0))
 499     processEvent(e);
 500   else
 501     super.dispatchEventImpl(e);
 502 }
 503
 504 /*************************************************************************/
 505
 506 /**
 507   * Returns a debugging string for this object.
 508   *
 509   * @return A debugging string for this object.
 510   */
 511 protected String
 512 paramString()
 513 {
 514   return ("selectedIndex=" + selectedIndex + "," + super.paramString());
 515 }
 516
 517   /**
 518    * Returns an array of all the objects currently registered as FooListeners
 519    * upon this Choice. FooListeners are registered using the addFooListener
 520    * method.
 521    *
 522    * @exception ClassCastException If listenerType doesn't specify a class or
 523    * interface that implements java.util.EventListener.
 524    *
 525    * @since 1.3
 526    */
 527   public EventListener[] getListeners (Class listenerType)
 528   {
 529     if (listenerType == ItemListener.class)
 530       return AWTEventMulticaster.getListeners (item_listeners, listenerType);
 531
 532     return super.getListeners (listenerType);
 533   }
 534
 535   /**
 536    * Returns all registered item listeners.
 537    *
 538    * @since 1.4
 539    */
 540   public ItemListener[] getItemListeners ()
 541   {
 542     return (ItemListener[]) getListeners (ItemListener.class);
 543   }
 544 } // class Choice