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 */ AccessibleContext()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 */ getAccessibleName()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 */ setAccessibleName(String s)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 */ getAccessibleDescription()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 */ setAccessibleDescription(String s)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 */ getAccessibleRole()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 */ getAccessibleStateSet()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 */ getAccessibleParent()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 */ setAccessibleParent(Accessible a)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 */ getAccessibleIndexInParent()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 */ getAccessibleChildrenCount()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 */ getAccessibleChild(int i)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 */ getLocale()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 */ addPropertyChangeListener(PropertyChangeListener l)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 */ removePropertyChangeListener(PropertyChangeListener l)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 */ getAccessibleAction()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 */ getAccessibleComponent()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 */ getAccessibleSelection()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 */ getAccessibleText()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 */ getAccessibleEditableText()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 */ getAccessibleValue()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 */ getAccessibleIcon()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 */ getAccessibleRelationSet()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 */ getAccessibleTable()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 */ firePropertyChange(String name, Object oldValue, Object newValue)585 public void firePropertyChange(String name, Object oldValue, Object newValue) 586 { 587 listeners.firePropertyChange(name, oldValue, newValue); 588 } 589 } // class AccessibleContext 590