| Frames | No Frames |
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