Source for javax.accessibility.AccessibleContext

   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:    * 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