GNU Classpath (0.20) | |
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: * 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
GNU Classpath (0.20) |