libjava/classpath/java/awt/Choice.java

   1 /* Choice.java -- Java choice button widget.
   2    Copyright (C) 1999, 2000, 2001, 2002, 2004 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
  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 import javax.accessibility.Accessible;
  49 import javax.accessibility.AccessibleAction;
  50 import javax.accessibility.AccessibleContext;
  51 import javax.accessibility.AccessibleRole;
  52
  53 /**
  54   * This class implements a drop down choice list.
  55   *
  56   * @author Aaron M. Renn (arenn@urbanophile.com)
  57   */
  58 public class Choice extends Component
  59   implements ItemSelectable, Serializable, Accessible
  60 {
  61
  62 /*
  63  * Static Variables
  64  */
  65
  66 // Serialization constant
  67 private static final long serialVersionUID = -4075310674757313071L;
  68
  69 /*************************************************************************/
  70
  71 /*
  72  * Instance Variables
  73  */
  74
  75 /**
  76   * @serial A list of items for the choice box, which can be <code>null</code>.
  77   * This is package-private to avoid an accessor method.
  78   */
  79 Vector pItems = new Vector();
  80
  81 /**
  82   * @serial The index of the selected item in the choice box.
  83   */
  84 private int selectedIndex = -1;
  85
  86 // Listener chain
  87 private ItemListener item_listeners;
  88
  89 /**
  90  * This class provides accessibility support for the
  91  * combo box.
  92  *
  93  * @author Jerry Quinn  (jlquinn@optonline.net)
  94  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  95  */
  96   protected class AccessibleAWTChoice
  97   extends AccessibleAWTComponent
  98   implements AccessibleAction
  99   {
 100
 101     /**
 102      * Serialization constant to match JDK 1.5
 103      */
 104     private static final long serialVersionUID = 7175603582428509322L;
 105
 106     /**
 107      * Default constructor which simply calls the
 108      * super class for generic component accessibility
 109      * handling.
 110      */
 111     public AccessibleAWTChoice()
 112     {
 113       super();
 114     }
 115
 116     /**
 117      * Returns an implementation of the <code>AccessibleAction</code>
 118      * interface for this accessible object.  In this case, the
 119      * current instance is simply returned (with a more appropriate
 120      * type), as it also implements the accessible action as well as
 121      * the context.
 122      *
 123      * @return the accessible action associated with this context.
 124      * @see javax.accessibility.AccessibleAction
 125      */
 126     public AccessibleAction getAccessibleAction()
 127     {
 128       return this;
 129     }
 130
 131     /**
 132      * Returns the role of this accessible object.
 133      *
 134      * @return the instance of <code>AccessibleRole</code>,
 135      *         which describes this object.
 136      * @see javax.accessibility.AccessibleRole
 137      */
 138     public AccessibleRole getAccessibleRole()
 139     {
 140       return AccessibleRole.COMBO_BOX;
 141     }
 142
 143     /**
 144      * Returns the number of actions associated with this accessible
 145      * object.  In this case, it is the number of choices available.
 146      *
 147      * @return the number of choices available.
 148      * @see javax.accessibility.AccessibleAction#getAccessibleActionCount()
 149      */
 150     public int getAccessibleActionCount()
 151     {
 152       return pItems.size();
 153     }
 154
 155     /**
 156      * Returns a description of the action with the supplied id.
 157      * In this case, it is the text used in displaying the particular
 158      * choice on-screen.
 159      *
 160      * @param i the id of the choice whose description should be
 161      *          retrieved.
 162      * @return the <code>String</code> used to describe the choice.
 163      * @see javax.accessibility.AccessibleAction#getAccessibleActionDescription(int)
 164      */
 165     public String getAccessibleActionDescription(int i)
 166     {
 167       return (String) pItems.get(i);
 168     }
 169
 170     /**
 171      * Executes the action with the specified id.  In this case,
 172      * calling this method provides the same behaviour as would
 173      * choosing a choice from the list in a visual manner.
 174      *
 175      * @param i the id of the choice to select.
 176      * @return true if a valid choice was specified.
 177      * @see javax.accessibility.AccessibleAction#doAccessibleAction(int)
 178      */
 179     public boolean doAccessibleAction(int i)
 180     {
 181       if (i < 0 || i >= pItems.size())
 182         return false;
 183
 184       Choice.this.processItemEvent(new ItemEvent(Choice.this,
 185                                                  ItemEvent.ITEM_STATE_CHANGED,
 186                                                  this, ItemEvent.SELECTED));
 187       return true;
 188     }
 189   }
 190
 191 /*************************************************************************/
 192
 193 /*
 194  * Constructors
 195  */
 196
 197   /**
 198    * Initializes a new instance of <code>Choice</code>.
 199    *
 200    * @exception HeadlessException If GraphicsEnvironment.isHeadless()
 201    * returns true
 202    */
 203   public Choice()
 204   {
 205     if (GraphicsEnvironment.isHeadless())
 206       throw new HeadlessException ();
 207   }
 208
 209 /*************************************************************************/
 210
 211 /*
 212  * Instance Methods
 213  */
 214
 215 /**
 216   * Returns the number of items in the list.
 217   *
 218   * @return The number of items in the list.
 219   */
 220 public int
 221 getItemCount()
 222 {
 223   return countItems ();
 224 }
 225
 226 /*************************************************************************/
 227
 228 /**
 229   * Returns the number of items in the list.
 230   *
 231   * @return The number of items in the list.
 232   *
 233   * @deprecated This method is deprecated in favor of <code>getItemCount</code>.
 234   */
 235 public int
 236 countItems()
 237 {
 238   return(pItems.size());
 239 }
 240
 241 /*************************************************************************/
 242
 243 /**
 244   * Returns the item at the specified index in the list.
 245   *
 246   * @param index The index into the list to return the item from.
 247   *
 248   * @exception ArrayIndexOutOfBoundsException If the index is invalid.
 249   */
 250 public String
 251 getItem(int index)
 252 {
 253   return((String)pItems.elementAt(index));
 254 }
 255
 256 /*************************************************************************/
 257
 258 /**
 259   * Adds the specified item to this choice box.
 260   *
 261   * @param item The item to add.
 262   *
 263   * @exception NullPointerException If the item's value is null
 264   *
 265   * @since 1.1
 266   */
 267 public synchronized void
 268 add(String item)
 269 {
 270   if (item == null)
 271     throw new NullPointerException ("item must be non-null");
 272
 273   pItems.addElement(item);
 274
 275   int i = pItems.size () - 1;
 276   if (peer != null)
 277     {
 278       ChoicePeer cp = (ChoicePeer) peer;
 279       cp.add (item, i);
 280     }
 281   else if (selectedIndex == -1)
 282     select(0);
 283 }
 284
 285 /*************************************************************************/
 286
 287 /**
 288   * Adds the specified item to this choice box.
 289   *
 290   * This method is oboslete since Java 2 platform 1.1. Please use @see add
 291   * instead.
 292   *
 293   * @param item The item to add.
 294   *
 295   * @exception NullPointerException If the item's value is equal to null
 296   */
 297 public synchronized void
 298 addItem(String item)
 299 {
 300   add(item);
 301 }
 302
 303 /*************************************************************************/
 304
 305 /** Inserts an item into this Choice.  Existing items are shifted
 306  * upwards.  If the new item is the only item, then it is selected.
 307  * If the currently selected item is shifted, then the first item is
 308  * selected.  If the currently selected item is not shifted, then it
 309  * remains selected.
 310  *
 311  * @param item The item to add.
 312  * @param index The index at which the item should be inserted.
 313  *
 314  * @exception IllegalArgumentException If index is less than 0
 315  */
 316 public synchronized void
 317 insert(String item, int index)
 318 {
 319   if (index < 0)
 320     throw new IllegalArgumentException ("index may not be less then 0");
 321
 322   if (index > getItemCount ())
 323     index = getItemCount ();
 324
 325   pItems.insertElementAt(item, index);
 326
 327   if (peer != null)
 328     {
 329       ChoicePeer cp = (ChoicePeer) peer;
 330       cp.add (item, index);
 331     }
 332   else if (selectedIndex == -1 || selectedIndex >= index)
 333     select(0);
 334 }
 335
 336 /*************************************************************************/
 337
 338 /**
 339   * Removes the specified item from the choice box.
 340   *
 341   * @param item The item to remove.
 342   *
 343   * @exception IllegalArgumentException If the specified item doesn't exist.
 344   */
 345 public synchronized void
 346 remove(String item)
 347 {
 348   int index = pItems.indexOf(item);
 349   if (index == -1)
 350     throw new IllegalArgumentException ("item \""
 351                                         + item + "\" not found in Choice");
 352   remove(index);
 353 }
 354
 355 /*************************************************************************/
 356
 357 /**
 358   * Removes the item at the specified index from the choice box.
 359   *
 360   * @param index The index of the item to remove.
 361   *
 362   * @exception IndexOutOfBoundsException If the index is not valid.
 363   */
 364 public synchronized void
 365 remove(int index)
 366 {
 367   if ((index < 0) || (index > getItemCount()))
 368     throw new IllegalArgumentException("Bad index: " + index);
 369
 370   pItems.removeElementAt(index);
 371
 372   if (peer != null)
 373     {
 374       ChoicePeer cp = (ChoicePeer) peer;
 375       cp.remove (index);
 376     }
 377   else
 378     {
 379       if (getItemCount() == 0)
 380         selectedIndex = -1;
 381       else if (index == selectedIndex)
 382         select(0);
 383     }
 384
 385   if (selectedIndex > index)
 386     --selectedIndex;
 387 }
 388
 389 /*************************************************************************/
 390
 391 /**
 392   * Removes all of the objects from this choice box.
 393   */
 394 public synchronized void
 395 removeAll()
 396 {
 397   if (getItemCount() <= 0)
 398     return;
 399
 400   pItems.removeAllElements ();
 401
 402   if (peer != null)
 403     {
 404       ChoicePeer cp = (ChoicePeer) peer;
 405       cp.removeAll ();
 406     }
 407
 408   selectedIndex = -1;
 409 }
 410
 411 /*************************************************************************/
 412
 413 /**
 414   * Returns the currently selected item, or null if no item is
 415   * selected.
 416   *
 417   * @return The currently selected item.
 418   */
 419 public synchronized String
 420 getSelectedItem()
 421 {
 422   return (selectedIndex == -1
 423           ? null
 424           : ((String)pItems.elementAt(selectedIndex)));
 425 }
 426
 427 /*************************************************************************/
 428
 429 /**
 430   * Returns an array with one row containing the selected item.
 431   *
 432   * @return An array containing the selected item.
 433   */
 434 public synchronized Object[]
 435 getSelectedObjects()
 436 {
 437   if (selectedIndex == -1)
 438     return null;
 439
 440   Object[] objs = new Object[1];
 441   objs[0] = pItems.elementAt(selectedIndex);
 442
 443   return(objs);
 444 }
 445
 446 /*************************************************************************/
 447
 448 /**
 449   * Returns the index of the selected item.
 450   *
 451   * @return The index of the selected item.
 452   */
 453 public int
 454 getSelectedIndex()
 455 {
 456   return(selectedIndex);
 457 }
 458
 459 /*************************************************************************/
 460
 461 /**
 462   * Forces the item at the specified index to be selected.
 463   *
 464   * @param index The index of the row to make selected.
 465   *
 466   * @exception IllegalArgumentException If the specified index is invalid.
 467   */
 468 public synchronized void
 469 select(int index)
 470 {
 471   if ((index < 0) || (index >= getItemCount()))
 472     throw new IllegalArgumentException("Bad index: " + index);
 473
 474   if (pItems.size() > 0) {
 475       selectedIndex = index;
 476       ChoicePeer cp = (ChoicePeer) peer;
 477       if (cp != null) {
 478           cp.select(index);
 479       }
 480   }
 481 }
 482
 483 /*************************************************************************/
 484
 485 /**
 486   * Forces the named item to be selected.
 487   *
 488   * @param item The item to be selected.
 489   *
 490   * @exception IllegalArgumentException If the specified item does not exist.
 491   */
 492 public synchronized void
 493 select(String item)
 494 {
 495   int index = pItems.indexOf(item);
 496   if (index >= 0)
 497     select(index);
 498 }
 499
 500 /*************************************************************************/
 501
 502 /**
 503   * Creates the native peer for this object.
 504   */
 505 public void
 506 addNotify()
 507 {
 508   if (peer == null)
 509     peer = getToolkit ().createChoice (this);
 510   super.addNotify ();
 511 }
 512
 513 /*************************************************************************/
 514
 515 /**
 516   * Adds the specified listener to the list of registered listeners for
 517   * this object.
 518   *
 519   * @param listener The listener to add.
 520   */
 521 public synchronized void
 522 addItemListener(ItemListener listener)
 523 {
 524   item_listeners = AWTEventMulticaster.add(item_listeners, listener);
 525 }
 526
 527 /*************************************************************************/
 528
 529 /**
 530   * Removes the specified listener from the list of registered listeners for
 531   * this object.
 532   *
 533   * @param listener The listener to remove.
 534   */
 535 public synchronized void
 536 removeItemListener(ItemListener listener)
 537 {
 538   item_listeners = AWTEventMulticaster.remove(item_listeners, listener);
 539 }
 540
 541 /*************************************************************************/
 542
 543 /**
 544   * Processes this event by invoking <code>processItemEvent()</code> if the
 545   * event is an instance of <code>ItemEvent</code>, otherwise the event
 546   * is passed to the superclass.
 547   *
 548   * @param event The event to process.
 549   */
 550 protected void
 551 processEvent(AWTEvent event)
 552 {
 553   if (event instanceof ItemEvent)
 554     processItemEvent((ItemEvent)event);
 555   else
 556     super.processEvent(event);
 557 }
 558
 559 /*************************************************************************/
 560
 561 /**
 562   * Processes item event by dispatching to any registered listeners.
 563   *
 564   * @param event The event to process.
 565   */
 566 protected void
 567 processItemEvent(ItemEvent event)
 568 {
 569   int index = pItems.indexOf((String) event.getItem());
 570   // Don't call back into the peers when selecting index here
 571   if (event.getStateChange() == ItemEvent.SELECTED)
 572     this.selectedIndex = index;
 573   if (item_listeners != null)
 574     item_listeners.itemStateChanged(event);
 575 }
 576
 577 /*************************************************************************/
 578
 579 /**
 580   * Returns a debugging string for this object.
 581   *
 582   * @return A debugging string for this object.
 583   */
 584 protected String
 585 paramString()
 586 {
 587   return ("selectedIndex=" + selectedIndex + "," + super.paramString());
 588 }
 589
 590   /**
 591    * Returns an array of all the objects currently registered as FooListeners
 592    * upon this Choice. FooListeners are registered using the addFooListener
 593    * method.
 594    *
 595    * @exception ClassCastException If listenerType doesn't specify a class or
 596    * interface that implements java.util.EventListener.
 597    *
 598    * @since 1.3
 599    */
 600   public EventListener[] getListeners (Class listenerType)
 601   {
 602     if (listenerType == ItemListener.class)
 603       return AWTEventMulticaster.getListeners (item_listeners, listenerType);
 604
 605     return super.getListeners (listenerType);
 606   }
 607
 608   /**
 609    * Returns all registered item listeners.
 610    *
 611    * @since 1.4
 612    */
 613   public ItemListener[] getItemListeners ()
 614   {
 615     return (ItemListener[]) getListeners (ItemListener.class);
 616   }
 617
 618   /**
 619    * Gets the AccessibleContext associated with this <code>Choice</code>.
 620    * The context is created, if necessary.
 621    *
 622    * @return the associated context
 623    */
 624   public AccessibleContext getAccessibleContext()
 625   {
 626     /* Create the context if this is the first request */
 627     if (accessibleContext == null)
 628       accessibleContext = new AccessibleAWTChoice();
 629     return accessibleContext;
 630   }
 631 } // class Choice