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