libjava/java/awt/Checkbox.java

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