libjava/classpath/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., 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 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    * Constant used when a component's bounds have changed.  The old and
 253    * new bounds are given in the event.
 254    * @since 1.5
 255    */
 256   public static final String ACCESSIBLE_COMPONENT_BOUNDS_CHANGED
 257     = "accessibleComponentBoundsChanged";
 258
 259   /**
 260    * Constant used when the state of child objects changes.  The old
 261    * value in the event is always null, and the new value is the component
 262    * whose children have changed.
 263    * @since 1.5
 264    */
 265   public static final String ACCESSIBLE_INVALIDATE_CHILDREN
 266     = "accessibleInvalidateChildren";
 267
 268   /**
 269    * Constant used when the attributes of some text have changed.
 270    * On insertion, the old value is null and the new value is an
 271    * {@link AccessibleAttributeSequence} describing the insertion.
 272    * On deletion, the old value is an {@link AccessibleAttributeSequence}
 273    * and the new value is null.  For replacement, both the old
 274    * and new values are {@link AccessibleAttributeSequence} objects.
 275    * @since 1.5
 276    */
 277   public static final String ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED
 278     = "accessibleTextAttributesChanged";
 279
 280   /**
 281    * The accessible parent of this object.
 282    *
 283    * @see #getAccessibleParent()
 284    * @see #setAccessibleParent(Accessible)
 285    */
 286   protected Accessible accessibleParent;
 287
 288   /**
 289    * A localized string naming this object.
 290    *
 291    * @see #getAccessibleName()
 292    * @see #setAccessibleName(String)
 293    */
 294   protected String accessibleName;
 295
 296   /**
 297    * A localized string describing this object.
 298    *
 299    * @see #getAccessibleDescription()
 300    * @see #setAccessibleDescription(String)
 301    */
 302   protected String accessibleDescription;
 303
 304   /**
 305    * The listener tool.
 306    *
 307    * @see #addPropertyChangeListener(PropertyChangeListener)
 308    * @see #removePropertyChangeListener(PropertyChangeListener)
 309    * @see #firePropertyChange(String, Object, Object)
 310    */
 311   private final PropertyChangeSupport listeners
 312     = new PropertyChangeSupport(this);
 313
 314   /**
 315    * Default constructor.
 316    */
 317   public AccessibleContext()
 318   {
 319   }
 320
 321   /**
 322    * Get the localized name of the object. For example, a label may just
 323    * return the text of the label, while an entry field for city may return
 324    * "city" in en_US.
 325    *
 326    * @return the accessible object's name, or null if it is unnamed
 327    * @see #setAccessibleName(String)
 328    */
 329   public String getAccessibleName()
 330   {
 331     return accessibleName;
 332   }
 333
 334   /**
 335    * Set the localized name of the object. This will fire a
 336    * PropertyChangeEvent with ACCESSIBLE_NAME_PROPERTY.
 337    *
 338    * @param s the new name
 339    * @see #getAccessibleName()
 340    * @see #addPropertyChangeListener(PropertyChangeListener)
 341    */
 342   public void setAccessibleName(String s)
 343   {
 344     listeners.firePropertyChange(ACCESSIBLE_NAME_PROPERTY, accessibleName, s);
 345     accessibleName = s;
 346   }
 347
 348   /**
 349    * Get the localized description of the object. For example, a 'Cancel'
 350    * button may be described as "Ignore changes and close dialog box" in
 351    * en_US.
 352    *
 353    * @return the accessible object's description, or null if there is none
 354    * @see #setAccessibleDescription(String)
 355    */
 356   public String getAccessibleDescription()
 357   {
 358     return accessibleDescription;
 359   }
 360
 361   /**
 362    * Set the localized name of the object. This will fire a
 363    * PropertyChangeEvent with ACCESSIBLE_DESCRIPTION_PROPERTY.
 364    *
 365    * @param s the new description
 366    * @see #getAccessibleDescription()
 367    * @see #addPropertyChangeListener(PropertyChangeListener)
 368    */
 369   public void setAccessibleDescription(String s)
 370   {
 371     listeners.firePropertyChange(ACCESSIBLE_DESCRIPTION_PROPERTY,
 372                                  accessibleDescription, s);
 373     accessibleDescription = s;
 374   }
 375
 376   /**
 377    * Gets the role of this object. For example, a button serves the role of
 378    * AccessibleRole.PUSH_BUTTON. This allows assistive technologies to funnel
 379    * similar objects into the same assistance classes. Note that the class
 380    * is extensible, to define new roles if necessary.
 381    *
 382    * @return the role of the object
 383    * @see AccessibleRole
 384    */
 385   public abstract AccessibleRole getAccessibleRole();
 386
 387   /**
 388    * Gets the state set of this object. A change in the state of the object
 389    * will fire a PropertyChangeEvent for ACCESSIBLE_STATE_PROPERTY.
 390    *
 391    * @return the current state of the object
 392    * @see AccessibleState
 393    * @see AccessibleStateSet
 394    * @see #addPropertyChangeListener(PropertyChangeListener)
 395    */
 396   public abstract AccessibleStateSet getAccessibleStateSet();
 397
 398   /**
 399    * Return the accessible parent of this object.
 400    *
 401    * @return the accessible parent, or null if there is none
 402    */
 403   public Accessible getAccessibleParent()
 404   {
 405     return accessibleParent;
 406   }
 407
 408   /**
 409    * Sets the accessible parent of this object. This should only be used when
 410    * the current parent object should not be the accessible parent; only the
 411    * parent of the accessible child should call this method.
 412    *
 413    * @param a the new parent
 414    */
 415   public void setAccessibleParent(Accessible a)
 416   {
 417     accessibleParent = a;
 418   }
 419
 420   /**
 421    * Gets the index of this object within its accessible parent.
 422    *
 423    * @return the 0-based index, or -1 if there is no accessible parent
 424    * @see #getAccessibleParent()
 425    * @see #getAccessibleChildrenCount()
 426    * @see #getAccessibleChild(int)
 427    */
 428   public abstract int getAccessibleIndexInParent();
 429
 430   /**
 431    * Returns the number of accessible children of this object.
 432    *
 433    * @return the number of accessible children
 434    * @see #getAccessibleChild(int)
 435    */
 436   public abstract int getAccessibleChildrenCount();
 437
 438   /**
 439    * Returns the specified accessible chile.
 440    *
 441    * @param i the 0-based index to get
 442    * @return the child, or null if out of bounds
 443    * @see #getAccessibleChildrenCount()
 444    */
 445   public abstract Accessible getAccessibleChild(int i);
 446
 447   /**
 448    * Gets the component locale, deferring to the parent if one is not declared.
 449    *
 450    * @return the locale
 451    * @throws java.awt.IllegalComponentStateException if there is no locale
 452    *         or parent
 453    */
 454   public abstract Locale getLocale();
 455
 456   /**
 457    * Add a PropertyChangeListener to the listener list. This listener will
 458    * be notified of all property changes to the accessible object.
 459    *
 460    * @param l the listener to add
 461    * @see #ACCESSIBLE_NAME_PROPERTY
 462    * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
 463    * @see #ACCESSIBLE_STATE_PROPERTY
 464    * @see #ACCESSIBLE_VALUE_PROPERTY
 465    * @see #ACCESSIBLE_SELECTION_PROPERTY
 466    * @see #ACCESSIBLE_TEXT_PROPERTY
 467    * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
 468    * @see #removePropertyChangeListener(PropertyChangeListener)
 469    */
 470   public void addPropertyChangeListener(PropertyChangeListener l)
 471   {
 472     listeners.addPropertyChangeListener(l);
 473   }
 474
 475   /**
 476    * Remove a PropertyChangeListener from the listener list.
 477    *
 478    * @param l the listener to remove
 479    * @see #addPropertyChangeListener(PropertyChangeListener)
 480    */
 481   public void removePropertyChangeListener(PropertyChangeListener l)
 482   {
 483     listeners.removePropertyChangeListener(l);
 484   }
 485
 486   /**
 487    * Get any supported accessible actions. The default implementation returns
 488    * null.
 489    *
 490    * @return the supported action, or null
 491    * @see AccessibleAction
 492    */
 493   public AccessibleAction getAccessibleAction()
 494   {
 495     return null;
 496   }
 497
 498   /**
 499    * Get any supported accessible compoent. The default implementation returns
 500    * null.
 501    *
 502    * @return the supported component, or null
 503    * @see AccessibleComponent
 504    */
 505   public AccessibleComponent getAccessibleComponent()
 506   {
 507     return null;
 508   }
 509
 510   /**
 511    * Get any supported accessible selection. The default implementation returns
 512    * null.
 513    *
 514    * @return the supported selection, or null
 515    * @see AccessibleSelection
 516    */
 517   public AccessibleSelection getAccessibleSelection()
 518   {
 519     return null;
 520   }
 521
 522   /**
 523    * Get any supported accessible text. The default implementation returns
 524    * null.
 525    *
 526    * @return the supported text, or null
 527    * @see AccessibleText
 528    */
 529   public AccessibleText getAccessibleText()
 530   {
 531     return null;
 532   }
 533
 534   /**
 535    * Get any supported accessible editable text. The default implementation
 536    * returns null.
 537    *
 538    * @return the supported editable text, or null
 539    * @see AccessibleEditableText
 540    */
 541   public AccessibleEditableText getAccessibleEditableText()
 542   {
 543     return null;
 544   }
 545
 546   /**
 547    * Get any supported accessible value. The default implementation returns
 548    * null.
 549    *
 550    * @return the supported value, or null
 551    * @see AccessibleValue
 552    */
 553   public AccessibleValue getAccessibleValue()
 554   {
 555     return null;
 556   }
 557
 558   /**
 559    * Get all supported accessible icons. The default implementation returns
 560    * null.
 561    *
 562    * @return the supported icons, or null
 563    * @see AccessibleIcon
 564    */
 565   public AccessibleIcon[] getAccessibleIcon()
 566   {
 567     return null;
 568   }
 569
 570   /**
 571    * Get any supported accessible relation set. The default implementation
 572    * returns an empty AccessibleRelationSet.
 573    *
 574    * @return the supported relation set, or <code>null</code>
 575    *
 576    * @see AccessibleRelationSet
 577    */
 578   public AccessibleRelationSet getAccessibleRelationSet()
 579   {
 580     return new AccessibleRelationSet();
 581   }
 582
 583   /**
 584    * Get any supported accessible table. The default implementation returns
 585    * null.
 586    *
 587    * @return the supported table, or null
 588    * @see AccessibleTable
 589    */
 590   public AccessibleTable getAccessibleTable()
 591   {
 592     return null;
 593   }
 594
 595   /**
 596    * Fire an event to report property changes. This is intended for use by
 597    * the accessible objects, not general application programs. If oldValue and
 598    * newValue differ, and the listenter list is not empty, a PropertyChange
 599    * event is fired to each listener.
 600    *
 601    * @param name the property name
 602    * @param oldValue the prior value
 603    * @param newValue the updated value
 604    * @see PropertyChangeSupport
 605    * @see #addPropertyChangeListener(PropertyChangeListener)
 606    * @see #removePropertyChangeListener(PropertyChangeListener)
 607    * @see #ACCESSIBLE_NAME_PROPERTY
 608    * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
 609    * @see #ACCESSIBLE_STATE_PROPERTY
 610    * @see #ACCESSIBLE_VALUE_PROPERTY
 611    * @see #ACCESSIBLE_SELECTION_PROPERTY
 612    * @see #ACCESSIBLE_TEXT_PROPERTY
 613    * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
 614    */
 615   public void firePropertyChange(String name, Object oldValue, Object newValue)
 616   {
 617     listeners.firePropertyChange(name, oldValue, newValue);
 618   }
 619 } // class AccessibleContext