libjava/classpath/java/awt/Checkbox.java

   1 /* Checkbox.java -- An AWT checkbox widget
   2    Copyright (C) 1999, 2000, 2001, 2002, 2005, 2006
   3    Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20 02110-1301 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39
  40 package java.awt;
  41
  42 import java.awt.event.ItemEvent;
  43 import java.awt.event.ItemListener;
  44 import java.awt.peer.CheckboxPeer;
  45 import java.io.Serializable;
  46
  47 import javax.accessibility.Accessible;
  48 import javax.accessibility.AccessibleAction;
  49 import javax.accessibility.AccessibleContext;
  50 import javax.accessibility.AccessibleRole;
  51 import javax.accessibility.AccessibleState;
  52 import javax.accessibility.AccessibleStateSet;
  53 import javax.accessibility.AccessibleValue;
  54
  55 /**
  56  * This class implements a component which has an on/off state.  Two
  57  * or more Checkboxes can be grouped by a CheckboxGroup.
  58  *
  59  * @author Aaron M. Renn (arenn@urbanophile.com)
  60  * @author Tom Tromey (tromey@redhat.com)
  61  */
  62 public class Checkbox extends Component
  63   implements ItemSelectable, Accessible, Serializable
  64 {
  65
  66 // FIXME: Need readObject/writeObject for this.
  67
  68 /*
  69  * Static Variables
  70  */
  71
  72 // Serialization Constant
  73 private static final long serialVersionUID = 7270714317450821763L;
  74
  75 /*************************************************************************/
  76
  77 /*
  78  * Instance Variables
  79  */
  80
  81 /**
  82   * @serial The checkbox group for this checkbox.
  83   */
  84 private CheckboxGroup group;
  85
  86 /**
  87   * @serial The label on this checkbox.
  88   */
  89 private String label;
  90
  91 /**
  92   * @serial The state of this checkbox.
  93   * This is package-private to avoid an accessor method.
  94   */
  95 boolean state;
  96
  97 // The list of listeners for this object.
  98 private transient ItemListener item_listeners;
  99
 100   /*
 101    * The number used to generate the name returned by getName.
 102    */
 103   private static transient long next_checkbox_number;
 104
 105 /**
 106  * This class provides accessibility support for the
 107  * checkbox.
 108  *
 109  * @author Jerry Quinn  (jlquinn@optonline.net)
 110  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
 111  */
 112 protected class AccessibleAWTCheckbox
 113   extends AccessibleAWTComponent
 114   implements ItemListener, AccessibleAction, AccessibleValue
 115 {
 116   /**
 117    * Serialization constant to match JDK 1.5
 118    */
 119   private static final long serialVersionUID = 7881579233144754107L;
 120
 121   /**
 122    * Default constructor which simply calls the
 123    * super class for generic component accessibility
 124    * handling.
 125    */
 126   public AccessibleAWTCheckbox()
 127   {
 128     super();
 129   }
 130
 131   /**
 132    * Captures changes to the state of the checkbox and
 133    * fires appropriate accessible property change events.
 134    *
 135    * @param event the event fired.
 136    * @see java.awt.event.ItemListener#itemStateChanged(java.awt.event.ItemEvent)
 137    */
 138   public void itemStateChanged(ItemEvent event)
 139   {
 140     firePropertyChange(ACCESSIBLE_STATE_PROPERTY,
 141                        state ? null : AccessibleState.CHECKED,
 142                        state ? AccessibleState.CHECKED : null);
 143   }
 144
 145   /**
 146    * Returns an implementation of the <code>AccessibleAction</code>
 147    * interface for this accessible object.  In this case, the
 148    * current instance is simply returned (with a more appropriate
 149    * type), as it also implements the accessible action as well as
 150    * the context.
 151    *
 152    * @return the accessible action associated with this context.
 153    * @see javax.accessibility.AccessibleAction
 154    */
 155   public AccessibleAction getAccessibleAction()
 156   {
 157     return this;
 158   }
 159
 160   /**
 161    * Returns an implementation of the <code>AccessibleValue</code>
 162    * interface for this accessible object.  In this case, the
 163    * current instance is simply returned (with a more appropriate
 164    * type), as it also implements the accessible value as well as
 165    * the context.
 166    *
 167    * @return the accessible value associated with this context.
 168    * @see javax.accessibility.AccessibleValue
 169    */
 170   public AccessibleValue getAccessibleValue()
 171   {
 172     return this;
 173   }
 174
 175   /*
 176    * The following methods are implemented in the JDK (up to
 177    * 1.5) as stubs.  We do likewise here.
 178    */
 179
 180   /**
 181    * Returns the number of actions associated with this accessible
 182    * object.  This default implementation returns 0.
 183    *
 184    * @return the number of accessible actions available.
 185    * @see javax.accessibility.AccessibleAction#getAccessibleActionCount()
 186    */
 187   public int getAccessibleActionCount()
 188   {
 189     // 1.4.1 and 1.5 do this
 190     return 0;
 191   }
 192
 193   /**
 194    * Returns a description of the action with the supplied id.
 195    * This default implementation always returns null.
 196    *
 197    * @param i the id of the action whose description should be
 198    *          retrieved.
 199    * @return a <code>String</code> describing the action.
 200    * @see javax.accessibility.AccessibleAction#getAccessibleActionDescription(int)
 201    */
 202   public String getAccessibleActionDescription(int i)
 203   {
 204     // 1.5 does this
 205     return null;
 206   }
 207
 208   /**
 209    * Executes the action with the specified id.  This
 210    * default implementation simply returns false.
 211    *
 212    * @param i the id of the action to perform.
 213    * @return true if the action was performed.
 214    * @see javax.accessibility.AccessibleAction#doAccessibleAction(int)
 215    */
 216   public boolean doAccessibleAction(int i)
 217   {
 218     // 1.5 does this
 219     return false;
 220   }
 221
 222   /**
 223    * Returns the current value of this accessible object.
 224    * If no value has been set, null is returned.  This
 225    * default implementation always returns null, regardless.
 226    *
 227    * @return the numeric value of this object, or null if
 228    *         no value has been set.
 229    * @see javax.accessibility.AccessibleValue#getCurrentAccessibleValue()
 230    */
 231   public Number getCurrentAccessibleValue()
 232   {
 233     // 1.5 does this
 234     return null;
 235   }
 236
 237   /**
 238    * Sets the current value of this accessible object
 239    * to that supplied.  In this default implementation,
 240    * the value is never set and the method always returns
 241    * false.
 242    *
 243    * @param number the new accessible value.
 244    * @return true if the value was set.
 245    * @see javax.accessibility.AccessibleValue#setCurrentAccessibleValue(java.lang.Number)
 246    */
 247   public boolean setCurrentAccessibleValue(Number number)
 248   {
 249     // 1.5 does this
 250     return false;
 251   }
 252
 253   /**
 254    * Returns the minimum acceptable accessible value used
 255    * by this object, or null if no minimum value exists.
 256    * This default implementation always returns null.
 257    *
 258    * @return the minimum acceptable accessible value, or null
 259    *         if there is no minimum.
 260    * @see javax.accessibility.AccessibleValue#getMinimumAccessibleValue()
 261    */
 262   public Number getMinimumAccessibleValue()
 263   {
 264     return null;
 265   }
 266
 267   /**
 268    * Returns the maximum acceptable accessible value used
 269    * by this object, or null if no maximum value exists.
 270    * This default implementation always returns null.
 271    *
 272    * @return the maximum acceptable accessible value, or null
 273    *         if there is no maximum.
 274    * @see javax.accessibility.AccessibleValue#getMaximumAccessibleValue()
 275    */
 276   public Number getMaximumAccessibleValue()
 277   {
 278     return null;
 279   }
 280
 281   /**
 282    * Returns the role of this accessible object.
 283    *
 284    * @return the instance of <code>AccessibleRole</code>,
 285    *         which describes this object.
 286    * @see javax.accessibility.AccessibleRole
 287    */
 288   public AccessibleRole getAccessibleRole()
 289   {
 290     return AccessibleRole.CHECK_BOX;
 291   }
 292
 293   /**
 294    * Returns the state set of this accessible object.
 295    *
 296    * @return a set of <code>AccessibleState</code>s
 297    *         which represent the current state of the
 298    *         accessible object.
 299    * @see javax.accessibility.AccessibleState
 300    * @see javax.accessibility.AccessibleStateSet
 301    */
 302   public AccessibleStateSet getAccessibleStateSet()
 303   {
 304     AccessibleStateSet set = super.getAccessibleStateSet();
 305     if (state)
 306       set.add(AccessibleState.CHECKED);
 307     return set;
 308   }
 309
 310 }
 311
 312 /*************************************************************************/
 313
 314 /*
 315  * Constructors
 316  */
 317
 318 /**
 319   * Initializes a new instance of <code>Checkbox</code> with no label,
 320   * an initial state of off, and that is not part of any checkbox group.
 321   */
 322 public
 323 Checkbox()
 324 {
 325   this("", false, null);
 326 }
 327
 328 /*************************************************************************/
 329
 330 /**
 331   * Initializes a new instance of <code>Checkbox</code> with the specified
 332   * label, an initial state of off, and that is not part of any checkbox
 333   * group.
 334   *
 335   * @param label The label for this checkbox.
 336   */
 337 public
 338 Checkbox(String label)
 339 {
 340   this(label, false, null);
 341 }
 342
 343 /*************************************************************************/
 344
 345 /**
 346   * Initializes a new instance of <code>Checkbox</code> with the specified
 347   * label and initial state, and that is not part of any checkbox
 348   * group.
 349   *
 350   * @param label The label for this checkbox.
 351   * @param state The initial state of the checkbox, <code>true</code> for
 352   * on, <code>false</code> for off.
 353   */
 354 public
 355 Checkbox(String label, boolean state)
 356 {
 357   this(label, state, null);
 358 }
 359
 360 /*************************************************************************/
 361
 362 /**
 363   * Initializes a new instance of <code>Checkbox</code> with the specified
 364   * label, initial state, and checkbox group.
 365   *
 366   * @param label The label for this checkbox.
 367   * @param group The checkbox group for this box, or <code>null</code>
 368   * if there is no checkbox group.
 369   * @param state The initial state of the checkbox, <code>true</code> for
 370   * on, <code>false</code> for off.
 371   */
 372 public
 373 Checkbox(String label, CheckboxGroup group, boolean state)
 374 {
 375   this(label, state, group);
 376 }
 377
 378 /*************************************************************************/
 379
 380 /**
 381   * Initializes a new instance of <code>Checkbox</code> with the specified
 382   * label, initial state, and checkbox group.
 383   *
 384   * @param label The label for this checkbox.
 385   * @param state The initial state of the checkbox, <code>true</code> for
 386   * on, <code>false</code> for off.
 387   * @param group The checkbox group for this box, or <code>null</code>
 388   * if there is no checkbox group.
 389   */
 390 public
 391 Checkbox(String label, boolean state, CheckboxGroup group)
 392 {
 393   this.label = label;
 394   this.state = state;
 395   this.group = group;
 396
 397   if ( state && group != null )
 398     {
 399       group.setSelectedCheckbox(this);
 400     }
 401 }
 402
 403 /*************************************************************************/
 404
 405 /*
 406  * Instance Variables
 407  */
 408
 409 /**
 410   * Returns the label for this checkbox.
 411   *
 412   * @return The label for this checkbox.
 413   */
 414 public String
 415 getLabel()
 416 {
 417   return(label);
 418 }
 419
 420 /*************************************************************************/
 421
 422 /**
 423   * Sets the label for this checkbox to the specified value.
 424   *
 425   * @param label The new checkbox label.
 426   */
 427 public synchronized void
 428 setLabel(String label)
 429 {
 430   this.label = label;
 431   if (peer != null)
 432     {
 433       CheckboxPeer cp = (CheckboxPeer) peer;
 434       cp.setLabel(label);
 435     }
 436 }
 437
 438 /*************************************************************************/
 439
 440 /**
 441   * Returns the state of this checkbox.
 442   *
 443   * @return The state of this checkbox, which will be <code>true</code> for
 444   * on and <code>false</code> for off.
 445   */
 446 public boolean
 447 getState()
 448 {
 449   return(state);
 450 }
 451
 452 /*************************************************************************/
 453
 454 /**
 455   * Sets the state of this checkbox to the specified value.
 456   *
 457   * @param state The new state of the checkbox, which will be <code>true</code>
 458   * for on or <code>false</code> for off.
 459   */
 460 public synchronized void
 461 setState(boolean state)
 462 {
 463   if (this.state != state)
 464     {
 465       this.state = state;
 466       if (peer != null)
 467         {
 468           CheckboxPeer cp = (CheckboxPeer) peer;
 469           cp.setState (state);
 470         }
 471     }
 472 }
 473
 474 /*************************************************************************/
 475
 476 /**
 477   * Returns an array of length one containing the checkbox label if this
 478   * checkbox is selected.  Otherwise <code>null</code> is returned.
 479   *
 480   * @return The selection state of this checkbox.
 481   */
 482 public Object[]
 483 getSelectedObjects()
 484 {
 485   if (state == false)
 486     return(null);
 487
 488   Object[] objs = new Object[1];
 489   objs[0] = label;
 490
 491   return(objs);
 492 }
 493
 494 /*************************************************************************/
 495
 496 /**
 497   * Returns the checkbox group this object is a member of, if any.
 498   *
 499   * @return This object's checkbox group, of <code>null</code> if it is
 500   * not a member of any group.
 501   */
 502 public CheckboxGroup
 503 getCheckboxGroup()
 504 {
 505   return(group);
 506 }
 507
 508 /*************************************************************************/
 509
 510 /**
 511   * Sets this object's checkbox group to the specified group.
 512   *
 513   * @param group The new checkbox group, or <code>null</code> to make this
 514   * object part of no checkbox group.
 515   */
 516 public synchronized void
 517 setCheckboxGroup(CheckboxGroup group)
 518 {
 519   this.group = group;
 520   if (peer != null)
 521     {
 522       CheckboxPeer cp = (CheckboxPeer) peer;
 523       cp.setCheckboxGroup (group);
 524     }
 525 }
 526
 527 /*************************************************************************/
 528
 529 /**
 530   * Creates this object's native peer.
 531   */
 532 public void
 533 addNotify()
 534 {
 535   if (peer == null)
 536     peer = getToolkit ().createCheckbox (this);
 537   super.addNotify ();
 538 }
 539
 540   public ItemListener[] getItemListeners ()
 541   {
 542     return (ItemListener[])
 543       AWTEventMulticaster.getListeners (item_listeners, ItemListener.class);
 544   }
 545
 546 /**
 547   * Adds a new listeners to the list of registered listeners for this object.
 548   *
 549   * @param listener The new listener to add.
 550   */
 551 public synchronized void
 552 addItemListener(ItemListener listener)
 553 {
 554   item_listeners = AWTEventMulticaster.add(item_listeners, listener);
 555 }
 556
 557 /*************************************************************************/
 558
 559 /**
 560   * Removes a listener from the list of registered listeners for this object.
 561   *
 562   * @param listener The listener to remove.
 563   */
 564 public synchronized void
 565 removeItemListener(ItemListener listener)
 566 {
 567   item_listeners = AWTEventMulticaster.remove(item_listeners, listener);
 568 }
 569
 570 /*************************************************************************/
 571
 572 /**
 573   * Processes this event by calling <code>processItemEvent()</code> if it
 574   * is any instance of <code>ItemEvent</code>.  Otherwise it is passed to
 575   * the superclass for processing.
 576   *
 577   * @param event The event to process.
 578   */
 579 protected void
 580 processEvent(AWTEvent event)
 581 {
 582   if (event instanceof ItemEvent)
 583     processItemEvent((ItemEvent)event);
 584   else
 585     super.processEvent(event);
 586 }
 587
 588 /*************************************************************************/
 589
 590 /**
 591   * Processes this event by dispatching it to any registered listeners.
 592   *
 593   * @param event The <code>ItemEvent</code> to process.
 594   */
 595 protected void
 596 processItemEvent(ItemEvent event)
 597 {
 598   if (item_listeners != null)
 599     item_listeners.itemStateChanged(event);
 600 }
 601
 602 void
 603 dispatchEventImpl(AWTEvent e)
 604 {
 605   if (e.id <= ItemEvent.ITEM_LAST
 606       && e.id >= ItemEvent.ITEM_FIRST)
 607     {
 608       ItemEvent ie = (ItemEvent) e;
 609       int itemState = ie.getStateChange();
 610       setState(itemState == ItemEvent.SELECTED ? true : false);
 611       if (item_listeners != null
 612           || (eventMask & AWTEvent.ITEM_EVENT_MASK) != 0)
 613         processEvent(e);
 614     }
 615   else
 616     super.dispatchEventImpl(e);
 617 }
 618
 619 /*************************************************************************/
 620
 621 /**
 622   * Returns a debugging string for this object.
 623   */
 624 protected String
 625 paramString()
 626 {
 627   // Note: We cannot add the checkbox group information here because this
 628   // would trigger infinite recursion when CheckboxGroup.toString() is
 629   // called and the box is in its selected state.
 630   return ("label=" + label + ",state=" + state + "," + super.paramString());
 631 }
 632
 633 /**
 634  * Gets the AccessibleContext associated with this <code>Checkbox</code>.
 635  * The context is created, if necessary.
 636  *
 637  * @return the associated context
 638  */
 639 public AccessibleContext getAccessibleContext()
 640 {
 641   /* Create the context if this is the first request */
 642   if (accessibleContext == null)
 643   {
 644     AccessibleAWTCheckbox ac = new AccessibleAWTCheckbox();
 645     accessibleContext = ac;
 646     addItemListener(ac);
 647   }
 648   return accessibleContext;
 649 }
 650
 651   /**
 652    * Generate a unique name for this checkbox.
 653    *
 654    * @return A unique name for this checkbox.
 655    */
 656   String generateName()
 657   {
 658     return "checkbox" + getUniqueLong();
 659   }
 660
 661   private static synchronized long getUniqueLong()
 662   {
 663     return next_checkbox_number++;
 664   }
 665 }