libjava/javax/accessibility/AccessibleContext.java

   1 /* AccessibleContext.java -- the context of an accessible object
   2    Copyright (C) 2002 Free Software Foundation
   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 package javax.accessibility;
  39
  40 import java.beans.PropertyChangeListener;
  41 import java.beans.PropertyChangeSupport;
  42 import java.util.Locale;
  43
  44 /**
  45  * The minimum information that all accessible objects return. This includes
  46  * name, description, role, and state of the object, parents and children,
  47  * and any other useful information. If a component supports further details,
  48  * it should implement one of the following:<ul>
  49  * <li>{@link AccessibleAction} - the object can perform actions</li>
  50  * <li>{@link AccessibleComponent} - the object has a graphical
  51  *     representation</li>
  52  * <li>{@link AccessibleSelection} - the object allows its children to be
  53  *     selected</li>
  54  * <li>{@link AccessibleText} - the object represents editable text</li>
  55  * <li>{@link AccessibleValue} - the object represents a numerical value</li>
  56  * </ul>
  57  *
  58  * @author Eric Blake <ebb9@email.byu.edu>
  59  * @since 1.2
  60  * @status updated to 1.4
  61  */
  62 public abstract class AccessibleContext
  63 {
  64   /**
  65    * Constant used when the accessible name has changed. Both the old and new
  66    * values are listed in the event.
  67    *
  68    * @see #getAccessibleName()
  69    * @see #addPropertyChangeListener(PropertyChangeListener)
  70    */
  71   public static final String ACCESSIBLE_NAME_PROPERTY
  72     = "AccessibleName";
  73
  74   /**
  75    * Constant used when the accessible description has changed. Both the old
  76    * and new values are listed in the event.
  77    *
  78    * @see #getAccessibleDescription()
  79    * @see #addPropertyChangeListener(PropertyChangeListener)
  80    */
  81   public static final String ACCESSIBLE_DESCRIPTION_PROPERTY
  82     = "AccessibleDescription";
  83
  84   /**
  85    * Constant used when the accessibleStateSet has changed. Both the old and
  86    * new values are listed in the event, although either may be null if a
  87    * state was disabled at that time.
  88    *
  89    * @see #getAccessibleStateSet()
  90    * @see AccessibleState
  91    * @see AccessibleStateSet
  92    * @see #addPropertyChangeListener(PropertyChangeListener)
  93    */
  94   public static final String ACCESSIBLE_STATE_PROPERTY
  95     = "AccessibleState";
  96
  97   /**
  98    * Constant used when the accessibleValue has changed. Both the old and new
  99    * values are listed in the event.
 100    *
 101    * @see #getAccessibleValue()
 102    * @see #addPropertyChangeListener(PropertyChangeListener)
 103    */
 104   public static final String ACCESSIBLE_VALUE_PROPERTY
 105     = "AccessibleValue";
 106
 107   /**
 108    * Constant used when the accessibleSelection has changed. Both the old and
 109    * new values of the event are reserved for future use.
 110    *
 111    * @see #getAccessibleSelection()
 112    * @see #addPropertyChangeListener(PropertyChangeListener)
 113    */
 114   public static final String ACCESSIBLE_SELECTION_PROPERTY
 115     = "AccessibleSelection";
 116
 117   /**
 118    * Constant used when the accessibleText has changed. Both the old and new
 119    * values of the event are reserved for future use.
 120    *
 121    * @see #getAccessibleText()
 122    * @see #addPropertyChangeListener(PropertyChangeListener)
 123    */
 124   public static final String ACCESSIBLE_TEXT_PROPERTY
 125     = "AccessibleText";
 126
 127   /**
 128    * Constant used when the accessibleText caret has changed. Both the old and
 129    * new values are listed in the event.
 130    *
 131    * @see #addPropertyChangeListener(PropertyChangeListener)
 132    */
 133   public static final String ACCESSIBLE_CARET_PROPERTY
 134     = "AccessibleCaret";
 135
 136   /**
 137    * Constant used when the visible data has changed. Both the old and new
 138    * values of the event are reserved for future use.
 139    *
 140    * @see #addPropertyChangeListener(PropertyChangeListener)
 141    */
 142   public static final String ACCESSIBLE_VISIBLE_DATA_PROPERTY
 143     = "AccessibleVisibleData";
 144
 145   /**
 146    * Constant used when children are added or removed. On addition, the new
 147    * value of the event holds the new child; on removal, the old value holds
 148    * the removed child.
 149    *
 150    * @see #addPropertyChangeListener(PropertyChangeListener)
 151    */
 152   public static final String ACCESSIBLE_CHILD_PROPERTY
 153     = "AccessibleChild";
 154
 155   /**
 156    * Constant used when active descendent of a component has changed. Both
 157    * the old and new values are listed in the event.
 158    *
 159    * @see #addPropertyChangeListener(PropertyChangeListener)
 160    */
 161   public static final String ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY
 162     = "AccessibleActiveDescendant";
 163
 164   /**
 165    * Constant used when the accessible table caption has changed. Both the
 166    * old and new values are listed in the event.
 167    *
 168    * @see Accessible
 169    * @see AccessibleTable
 170    */
 171   public static final String ACCESSIBLE_TABLE_CAPTION_CHANGED
 172     = "accessibleTableCaptionChanged";
 173
 174   /**
 175    * Constant used when the accessible table summary has changed. Both the
 176    * old and new values are listed in the event.
 177    *
 178    * @see Accessible
 179    * @see AccessibleTable
 180    */
 181   public static final String ACCESSIBLE_TABLE_SUMMARY_CHANGED
 182     = "accessibleTableSummaryChanged";
 183
 184   /**
 185    * Constant used when the accessible table model has changed. Only the new
 186    * value of the event has meaning.
 187    *
 188    * @see AccessibleTable
 189    * @see AccessibleTableModelChange
 190    */
 191   public static final String ACCESSIBLE_TABLE_MODEL_CHANGED
 192     = "accessibleTableModelChanged";
 193
 194   /**
 195    * Constant used when the accessible table row header has changed. Only the
 196    * new value of the event has meaning.
 197    *
 198    * @see AccessibleTable
 199    * @see AccessibleTableModelChange
 200    */
 201   public static final String ACCESSIBLE_TABLE_ROW_HEADER_CHANGED
 202     = "accessibleTableRowHeaderChanged";
 203
 204   /**
 205    * Constant used when the accessible table row description has changed. Only
 206    * the new value of the event has meaning.
 207    *
 208    * @see AccessibleTable
 209    */
 210   public static final String ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED
 211     = "accessibleTableRowDescriptionChanged";
 212
 213   /**
 214    * Constant used when the accessible table column header has changed. Only
 215    * the new value of the event has meaning.
 216    *
 217    * @see AccessibleTable
 218    * @see AccessibleTableModelChange
 219    */
 220   public static final String ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED
 221     = "accessibleTableColumnHeaderChanged";
 222
 223   /**
 224    * Constant used when the accessible table column description has changed.
 225    * Only the new value of the event has meaning.
 226    *
 227    * @see AccessibleTable
 228    */
 229   public static final String ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED
 230     = "accessibleTableColumnDescriptionChanged";
 231
 232   /**
 233    * Constant used when supported set of actions has changed. Both the old
 234    * and new values are listed in the event.
 235    *
 236    * @see AccessibleAction
 237    */
 238   public static final String ACCESSIBLE_ACTION_PROPERTY
 239     = "accessibleActionProperty";
 240
 241   /**
 242    * Constant used when a hypertext element received focus. Both the old
 243    * and new values are listed in the event, with -1 indicating that no link
 244    * had focus.
 245    *
 246    * @see AccessibleHyperlink
 247    */
 248   public static final String ACCESSIBLE_HYPERTEXT_OFFSET
 249     = "AccessibleHypertextOffset";
 250
 251   /**
 252    * The accessible parent of this object.
 253    *
 254    * @see #getAccessibleParent()
 255    * @see #setAccessibleParent(Accessible)
 256    */
 257   protected Accessible accessibleParent;
 258
 259   /**
 260    * A localized string naming this object.
 261    *
 262    * @see #getAccessibleName()
 263    * @see #setAccessibleName(String)
 264    */
 265   protected String accessibleName;
 266
 267   /**
 268    * A localized string describing this object.
 269    *
 270    * @see #getAccessibleDescription()
 271    * @see #setAccessibleDescription(String)
 272    */
 273   protected String accessibleDescription;
 274
 275   /**
 276    * The listener tool.
 277    *
 278    * @see #addPropertyChangeListener(PropertyChangeListener)
 279    * @see #removePropertyChangeListener(PropertyChangeListener)
 280    * @see #firePropertyChange(String, Object, Object)
 281    */
 282   private final PropertyChangeSupport listeners
 283     = new PropertyChangeSupport(this);
 284
 285   /**
 286    * Default constructor.
 287    */
 288   public AccessibleContext()
 289   {
 290   }
 291
 292   /**
 293    * Get the localized name of the object. For example, a label may just
 294    * return the text of the label, while an entry field for city may return
 295    * "city" in en_US.
 296    *
 297    * @return the accessible object's name, or null if it is unnamed
 298    * @see #setAccessibleName(String)
 299    */
 300   public String getAccessibleName()
 301   {
 302     return accessibleName;
 303   }
 304
 305   /**
 306    * Set the localized name of the object. This will fire a
 307    * PropertyChangeEvent with ACCESSIBLE_NAME_PROPERTY.
 308    *
 309    * @param s the new name
 310    * @see #getAccessibleName()
 311    * @see #addPropertyChangeListener(PropertyChangeListener)
 312    */
 313   public void setAccessibleName(String s)
 314   {
 315     listeners.firePropertyChange(ACCESSIBLE_NAME_PROPERTY, accessibleName, s);
 316     accessibleName = s;
 317   }
 318
 319   /**
 320    * Get the localized description of the object. For example, a 'Cancel'
 321    * button may be described as "Ignore changes and close dialog box" in
 322    * en_US.
 323    *
 324    * @return the accessible object's description, or null if there is none
 325    * @see #setAccessibleDescription(String)
 326    */
 327   public String getAccessibleDescription()
 328   {
 329     return accessibleDescription;
 330   }
 331
 332   /**
 333    * Set the localized name of the object. This will fire a
 334    * PropertyChangeEvent with ACCESSIBLE_DESCRIPTION_PROPERTY.
 335    *
 336    * @param s the new description
 337    * @see #getAccessibleDescription()
 338    * @see #addPropertyChangeListener(PropertyChangeListener)
 339    */
 340   public void setAccessibleDescription(String s)
 341   {
 342     listeners.firePropertyChange(ACCESSIBLE_DESCRIPTION_PROPERTY,
 343                                  accessibleDescription, s);
 344     accessibleDescription = s;
 345   }
 346
 347   /**
 348    * Gets the role of this object. For example, a button serves the role of
 349    * AccessibleRole.PUSH_BUTTON. This allows assistive technologies to funnel
 350    * similar objects into the same assistance classes. Note that the class
 351    * is extensible, to define new roles if necessary.
 352    *
 353    * @return the role of the object
 354    * @see AccessibleRole
 355    */
 356   public abstract AccessibleRole getAccessibleRole();
 357
 358   /**
 359    * Gets the state set of this object. A change in the state of the object
 360    * will fire a PropertyChangeEvent for ACCESSIBLE_STATE_PROPERTY.
 361    *
 362    * @return the current state of the object
 363    * @see AccessibleState
 364    * @see AccessibleStateSet
 365    * @see #addPropertyChangeListener(PropertyChangeListener)
 366    */
 367   public abstract AccessibleStateSet getAccessibleStateSet();
 368
 369   /**
 370    * Return the accessible parent of this object.
 371    *
 372    * @return the accessible parent, or null if there is none
 373    */
 374   public Accessible getAccessibleParent()
 375   {
 376     return accessibleParent;
 377   }
 378
 379   /**
 380    * Sets the accessible parent of this object. This should only be used when
 381    * the current parent object should not be the accessible parent; only the
 382    * parent of the accessible child should call this method.
 383    *
 384    * @param a the new parent
 385    */
 386   public void setAccessibleParent(Accessible a)
 387   {
 388     accessibleParent = a;
 389   }
 390
 391   /**
 392    * Gets the index of this object within its accessible parent.
 393    *
 394    * @return the 0-based index, or -1 if there is no accessible parent
 395    * @see #getAccessibleParent()
 396    * @see #getAccessibleChildrenCount()
 397    * @see #getAccessibleChild(int)
 398    */
 399   public abstract int getAccessibleIndexInParent();
 400
 401   /**
 402    * Returns the number of accessible children of this object.
 403    *
 404    * @return the number of accessible children
 405    * @see #getAccessibleChild(int)
 406    */
 407   public abstract int getAccessibleChildrenCount();
 408
 409   /**
 410    * Returns the specified accessible chile.
 411    *
 412    * @param i the 0-based index to get
 413    * @return the child, or null if out of bounds
 414    * @see #getAccessibleChildrenCount()
 415    */
 416   public abstract Accessible getAccessibleChild(int i);
 417
 418   /**
 419    * Gets the component locale, deferring to the parent if one is not declared.
 420    *
 421    * @return the locale
 422    * @throws java.awt.IllegalComponentStateException if there is no locale
 423    *         or parent
 424    */
 425   public abstract Locale getLocale();
 426
 427   /**
 428    * Add a PropertyChangeListener to the listener list. This listener will
 429    * be notified of all property changes to the accessible object.
 430    *
 431    * @param l the listener to add
 432    * @see #ACCESSIBLE_NAME_PROPERTY
 433    * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
 434    * @see #ACCESSIBLE_STATE_PROPERTY
 435    * @see #ACCESSIBLE_VALUE_PROPERTY
 436    * @see #ACCESSIBLE_SELECTION_PROPERTY
 437    * @see #ACCESSIBLE_TEXT_PROPERTY
 438    * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
 439    * @see #removePropertyChangeListener(PropertyChangeListener)
 440    */
 441   public void addPropertyChangeListener(PropertyChangeListener l)
 442   {
 443     listeners.addPropertyChangeListener(l);
 444   }
 445
 446   /**
 447    * Remove a PropertyChangeListener from the listener list.
 448    *
 449    * @param l the listener to remove
 450    * @see #addPropertyChangeListener(PropertyChangeListener)
 451    */
 452   public void removePropertyChangeListener(PropertyChangeListener l)
 453   {
 454     listeners.removePropertyChangeListener(l);
 455   }
 456
 457   /**
 458    * Get any supported accessible actions. The default implementation returns
 459    * null.
 460    *
 461    * @return the supported action, or null
 462    * @see AccessibleAction
 463    */
 464   public AccessibleAction getAccessibleAction()
 465   {
 466     return null;
 467   }
 468
 469   /**
 470    * Get any supported accessible compoent. The default implementation returns
 471    * null.
 472    *
 473    * @return the supported component, or null
 474    * @see AccessibleComponent
 475    */
 476   public AccessibleComponent getAccessibleComponent()
 477   {
 478     return null;
 479   }
 480
 481   /**
 482    * Get any supported accessible selection. The default implementation returns
 483    * null.
 484    *
 485    * @return the supported selection, or null
 486    * @see AccessibleSelection
 487    */
 488   public AccessibleSelection getAccessibleSelection()
 489   {
 490     return null;
 491   }
 492
 493   /**
 494    * Get any supported accessible text. The default implementation returns
 495    * null.
 496    *
 497    * @return the supported text, or null
 498    * @see AccessibleText
 499    */
 500   public AccessibleText getAccessibleText()
 501   {
 502     return null;
 503   }
 504
 505   /**
 506    * Get any supported accessible editable text. The default implementation
 507    * returns null.
 508    *
 509    * @return the supported editable text, or null
 510    * @see AccessibleEditableText
 511    */
 512   public AccessibleEditableText getAccessibleEditableText()
 513   {
 514     return null;
 515   }
 516
 517   /**
 518    * Get any supported accessible value. The default implementation returns
 519    * null.
 520    *
 521    * @return the supported value, or null
 522    * @see AccessibleValue
 523    */
 524   public AccessibleValue getAccessibleValue()
 525   {
 526     return null;
 527   }
 528
 529   /**
 530    * Get all supported accessible icons. The default implementation returns
 531    * null.
 532    *
 533    * @return the supported icons, or null
 534    * @see AccessibleIcon
 535    */
 536   public AccessibleIcon[] getAccessibleIcon()
 537   {
 538     return null;
 539   }
 540
 541   /**
 542    * Get any supported accessible relation set. The default implementation
 543    * returns null.
 544    *
 545    * @return the supported relation set, or null
 546    * @see AccessibleRelationSet
 547    */
 548   public AccessibleRelationSet getAccessibleRelationSet()
 549   {
 550     return null;
 551   }
 552
 553   /**
 554    * Get any supported accessible table. The default implementation returns
 555    * null.
 556    *
 557    * @return the supported table, or null
 558    * @see AccessibleTable
 559    */
 560   public AccessibleTable getAccessibleTable()
 561   {
 562     return null;
 563   }
 564
 565   /**
 566    * Fire an event to report property changes. This is intended for use by
 567    * the accessible objects, not general application programs. If oldValue and
 568    * newValue differ, and the listenter list is not empty, a PropertyChange
 569    * event is fired to each listener.
 570    *
 571    * @param name the property name
 572    * @param oldValue the prior value
 573    * @param newValue the updated value
 574    * @see PropertyChangeSupport
 575    * @see #addPropertyChangeListener(PropertyChangeListener)
 576    * @see #removePropertyChangeListener(PropertyChangeListener)
 577    * @see #ACCESSIBLE_NAME_PROPERTY
 578    * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
 579    * @see #ACCESSIBLE_STATE_PROPERTY
 580    * @see #ACCESSIBLE_VALUE_PROPERTY
 581    * @see #ACCESSIBLE_SELECTION_PROPERTY
 582    * @see #ACCESSIBLE_TEXT_PROPERTY
 583    * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
 584    */
 585   public void firePropertyChange(String name, Object oldValue, Object newValue)
 586   {
 587     listeners.firePropertyChange(name, oldValue, newValue);
 588   }
 589 } // class AccessibleContext