1. /*
  2. * @(#)AccessibleContext.java 1.24 01/11/29
  3. *
  4. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.accessibility;
  8. import java.util.Locale;
  9. import java.beans.PropertyChangeListener;
  10. import java.beans.PropertyChangeSupport;
  11. import java.awt.IllegalComponentStateException;
  12. /**
  13. * AccessibleContext represents the minimum information all accessible objects
  14. * return. This information includes the accessible name, description, role,
  15. * and state of the object, as well as information about the parent and
  16. * children of the object. AccessibleContext also contains methods for
  17. * obtaining more specific accessibility information about a component.
  18. * If the component supports it, these methods will return an object that
  19. * implements one or more of the following interfaces:
  20. * <P><ul>
  21. * <li>{@link AccessibleAction} - the object can perform one or more actions.
  22. * This interface provides the standard mechanism for an assistive
  23. * technology to determine what those actions are and tell the object
  24. * to perform those actions. Any object that can be manipulated should
  25. * support this interface.
  26. * <li>{@link AccessibleComponent} - the object has a graphical representation.
  27. * This interface provides the standard mechanism for an assistive
  28. * technology to determine and set the graphical representation of the
  29. * object. Any object that is rendered on the screen should support
  30. * this interface.
  31. * <li>{@link AccessibleSelection} - the object allows its children to be
  32. * selected. This interface provides the standard mechanism for an
  33. * assistive technology to determine the currently selected children
  34. * as well as modify the selection set. Any object that has children
  35. * that can be selected should support this interface.
  36. * <li>{@link AccessibleText} - the object presents editable textual information
  37. * on the display. This interface provides the standard mechanism for
  38. * an assistive technology to access that text via its content, attributes,
  39. * and spatial location. Any object that contains editable text should
  40. * support this interface.
  41. * <li>{@link AccessibleValue} - the object supports a numerical value. This
  42. * interface provides the standard mechanism for an assistive technology
  43. * to determine and set the current value of the object, as well as the
  44. * minimum and maximum values. Any object that supports a numerical value
  45. * should support this interface.</ul>
  46. * <P>In the future, additional interfaces (e.g., AccessibleTable) may be
  47. * added, and the abstract class AccessibleContext will be updated
  48. * accordingly.
  49. *
  50. * @version 1.17 02/04/98 11:50:50
  51. * @author Peter Korn
  52. * @author Hans Muller
  53. * @author Willie Walker
  54. */
  55. public abstract class AccessibleContext {
  56. /**
  57. * Constant used to determine when the accessibleName property has
  58. * changed. The old value in the PropertyChangeEvent will be the old
  59. * accessibleName and the new value will be the new accessibleName.
  60. *
  61. * @see #getAccessibleName
  62. * @see #addPropertyChangeListener
  63. */
  64. public static final String ACCESSIBLE_NAME_PROPERTY = "AccessibleName";
  65. /**
  66. * Constant used to determine when the accessibleDescription property has
  67. * changed. The old value in the PropertyChangeEvent will be the
  68. * old accessibleDescription and the new value will be the new
  69. * accessibleDescription.
  70. *
  71. * @see #getAccessibleDescription
  72. * @see #addPropertyChangeListener
  73. */
  74. public static final String ACCESSIBLE_DESCRIPTION_PROPERTY = "AccessibleDescription";
  75. /**
  76. * Constant used to determine when the accessibleStateSet property has
  77. * changed. The old value will be the old AccessibleState and the new
  78. * value will be the new AccessibleState in the accessibleStateSet.
  79. * For example, if a component that supports the vertical and horizontal
  80. * states changes its orientation from vertical to horizontal, the old
  81. * value will be AccessibleState.VERTICAL and the new value will be
  82. * AccessibleState.HORIZONTAL. Please note that either value can also
  83. * be null. For example, when a component changes from being enabled
  84. * to disabled, the old value will be AccessibleState.ENABLED
  85. * and the new value will null.
  86. *
  87. * @see #getAccessibleStateSet
  88. * @see AccessibleState
  89. * @see AccessibleStateSet
  90. * @see #addPropertyChangeListener
  91. */
  92. public static final String ACCESSIBLE_STATE_PROPERTY = "AccessibleState";
  93. /**
  94. * Constant used to determine when the accessibleValue property has
  95. * changed. The old value in the PropertyChangeEvent will be a Number
  96. * representing the old value and the new value will be a Number
  97. * representing the new value.
  98. *
  99. * @see #getAccessibleValue
  100. * @see #addPropertyChangeListener
  101. */
  102. public static final String ACCESSIBLE_VALUE_PROPERTY = "AccessibleValue";
  103. /**
  104. * Constant used to determine when the accessibleSelection has changed.
  105. * The old and new values in the PropertyChangeEvent are currently
  106. * reserved for future use.
  107. *
  108. * @see #getAccessibleSelection
  109. * @see #addPropertyChangeListener
  110. */
  111. public static final String ACCESSIBLE_SELECTION_PROPERTY = "AccessibleSelection";
  112. /**
  113. * Constant used to determine when the accessibleText has changed.
  114. * The old and new values in the PropertyChangeEvent are currently
  115. * reserved for future use.
  116. *
  117. * @see #getAccessibleText
  118. * @see #addPropertyChangeListener
  119. */
  120. public static final String ACCESSIBLE_TEXT_PROPERTY = "AccessibleText";
  121. /**
  122. * Constant used to determine when the accessibleText caret has changed.
  123. * has changed. The old value in the PropertyChangeEvent will be an
  124. * integer representing the old caret position, and the new value will
  125. * be an integer representing the new/current caret position.
  126. *
  127. * @see #addPropertyChangeListener
  128. */
  129. public static final String ACCESSIBLE_CARET_PROPERTY = "AccessibleCaret";
  130. /**
  131. * Constant used to determine when the visual appearance of the object
  132. * has changed. The old and new values in the PropertyChangeEvent are
  133. * currently reserved for future use.
  134. *
  135. * @see #addPropertyChangeListener
  136. */
  137. public static final String ACCESSIBLE_VISIBLE_DATA_PROPERTY = "AccessibleVisibleData";
  138. /**
  139. * Constant used to determine when Accessible children are added/removed
  140. * from the object. If an Accessible child is being added, the old
  141. * value will be null and the new value the Accessible child. If an
  142. * Accessible child is being removed, the old value will be the Accessible
  143. * child, and the new value will be null.
  144. *
  145. * @see #addPropertyChangeListener
  146. */
  147. public static final String ACCESSIBLE_CHILD_PROPERTY = "AccessibleChild";
  148. /**
  149. * Constant used to determine when the active descendant of a component
  150. * has changed. The active descendant is used for objects such as
  151. * list, tree, and table, which may have transient children. When the
  152. * active descendant has changed, the old value of the property change
  153. * event will be the Accessible representing the previous active child, and
  154. * the new value will be the Accessible representing the current active
  155. * child.
  156. *
  157. * @see #addPropertyChangeListener
  158. */
  159. public static final String ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY = "AccessibleActiveDescendant";
  160. /**
  161. * The accessible parent of this object.
  162. *
  163. * @see #getAccessibleParent
  164. * @see #setAccessibleParent
  165. */
  166. protected Accessible accessibleParent = null;
  167. /**
  168. * A localized String containing the name of the object.
  169. *
  170. * @see #getAccessibleName
  171. * @see #setAccessibleName
  172. */
  173. protected String accessibleName = null;
  174. /**
  175. * A localized String containing the description of the object.
  176. *
  177. * @see #getAccessibleDescription
  178. * @see #setAccessibleDescription
  179. */
  180. protected String accessibleDescription = null;
  181. /**
  182. * Used to handle the listener list for property change events.
  183. *
  184. * @see #addPropertyChangeListener
  185. * @see #removePropertyChangeListener
  186. * @see #firePropertyChangeListener
  187. */
  188. private PropertyChangeSupport accessibleChangeSupport = null;
  189. /**
  190. * Get the accessibleName property of this object. The accessibleName
  191. * property of an object is a localized String that designates the purpose
  192. * of the object. For example, the accessibleName property of a label
  193. * or button might be the text of the label or button itself. In the
  194. * case of an object that doesn't display its name, the accessibleName
  195. * should still be set. For example, in the case of a text field used
  196. * to enter the name of a city, the accessibleName for the en_US locale
  197. * could be 'city.'
  198. *
  199. * @return the localized name of the object; null if this
  200. * object does not have a name
  201. *
  202. * @see #setAccessibleName
  203. */
  204. public String getAccessibleName() {
  205. return accessibleName;
  206. }
  207. /**
  208. * Set the localized accessible name of this object. Changing the
  209. * name will cause a PropertyChangeEvent to be fired for the
  210. * ACCESSIBLE_NAME_PROPERTY property.
  211. *
  212. * @param s the new localized name of the object.
  213. *
  214. * @see #getAccessibleName
  215. * @see #addPropertyChangeListener
  216. */
  217. public void setAccessibleName(String s) {
  218. String oldName = accessibleName;
  219. accessibleName = s;
  220. firePropertyChange(ACCESSIBLE_NAME_PROPERTY,oldName,accessibleName);
  221. }
  222. /**
  223. * Get the accessibleDescription property of this object. The
  224. * accessibleDescription property of this object is a short localized
  225. * phrase describing the purpose of the object. For example, in the
  226. * case of a 'Cancel' button, the accessibleDescription could be
  227. * 'Ignore changes and close dialog box.'
  228. *
  229. * @return the localized description of the object; null if
  230. * this object does not have a description
  231. *
  232. * @see #setAccessibleDescription
  233. */
  234. public String getAccessibleDescription() {
  235. return accessibleDescription;
  236. }
  237. /**
  238. * Set the accessible description of this object. Changing the
  239. * name will cause a PropertyChangeEvent to be fired for the
  240. * ACCESSIBLE_DESCRIPTION_PROPERTY property.
  241. *
  242. * @param s the new localized description of the object
  243. *
  244. * @see #setAccessibleName
  245. * @see #addPropertyChangeListener
  246. */
  247. public void setAccessibleDescription(String s) {
  248. String oldDescription = accessibleDescription;
  249. accessibleDescription = s;
  250. firePropertyChange(ACCESSIBLE_DESCRIPTION_PROPERTY,
  251. oldDescription,accessibleDescription);
  252. }
  253. /**
  254. * Get the role of this object. The role of the object is the generic
  255. * purpose or use of the class of this object. For example, the role
  256. * of a push button is AccessibleRole.PUSH_BUTTON. The roles in
  257. * AccessibleRole are provided so component developers can pick from
  258. * a set of predefined roles. This enables assistive technologies to
  259. * provide a consistent interface to various tweaked subclasses of
  260. * components (e.g., use AccessibleRole.PUSH_BUTTON for all components
  261. * that act like a push button) as well as distinguish between sublasses
  262. * that behave differently (e.g., AccessibleRole.CHECK_BOX for check boxes
  263. * and AccessibleRole.RADIO_BUTTON for radio buttons).
  264. * <p>Note that the AccessibleRole class is also extensible, so
  265. * custom component developers can define their own AccessibleRole's
  266. * if the set of predefined roles is inadequate.
  267. *
  268. * @return an instance of AccessibleRole describing the role of the object
  269. * @see AccessibleRole
  270. */
  271. public abstract AccessibleRole getAccessibleRole();
  272. /**
  273. * Get the state set of this object. The AccessibleStateSet of an object
  274. * is composed of a set of unique AccessibleState's. A change in the
  275. * AccessibleStateSet of an object will cause a PropertyChangeEvent to
  276. * be fired for the ACCESSIBLE_STATE_PROPERTY property.
  277. *
  278. * @return an instance of AccessibleStateSet containing the
  279. * current state set of the object
  280. * @see AccessibleStateSet
  281. * @see AccessibleState
  282. * @see #addPropertyChangeListener
  283. */
  284. public abstract AccessibleStateSet getAccessibleStateSet();
  285. /**
  286. * Get the Accessible parent of this object.
  287. *
  288. * @return the Accessible parent of this object; null if this
  289. * object does not have an Accessible parent
  290. */
  291. public Accessible getAccessibleParent() {
  292. return accessibleParent;
  293. }
  294. /**
  295. * Set the Accessible parent of this object. This is meant to be used
  296. * only in the situations where the actual component's parent should
  297. * not be treated as the component's accessible parent and is a method
  298. * that should only be called by the parent of the accessible child.
  299. *
  300. * @param a - Accessible to be set as the parent
  301. */
  302. public void setAccessibleParent(Accessible a) {
  303. accessibleParent = a;
  304. }
  305. /**
  306. * Get the 0-based index of this object in its accessible parent.
  307. *
  308. * @return the 0-based index of this object in its parent; -1 if this
  309. * object does not have an accessible parent.
  310. *
  311. * @see #getAccessibleParent
  312. * @see #getAccessibleChildrenCount
  313. * @see #getAccessibleChild
  314. */
  315. public abstract int getAccessibleIndexInParent();
  316. /**
  317. * Returns the number of accessible children of the object.
  318. *
  319. * @return the number of accessible children of the object.
  320. */
  321. public abstract int getAccessibleChildrenCount();
  322. /**
  323. * Return the specified Accessible child of the object. The Accessible
  324. * children of an Accessible object are zero-based, so the first child
  325. * of an Accessible child is at index 0, the second child is at index 1,
  326. * and so on.
  327. *
  328. * @param i zero-based index of child
  329. * @return the Accessible child of the object
  330. * @see #getAccessibleChildrenCount
  331. */
  332. public abstract Accessible getAccessibleChild(int i);
  333. /**
  334. * Gets the locale of the component. If the component does not have a
  335. * locale, then the locale of its parent is returned.
  336. *
  337. * @return This component's locale. If this component does not have
  338. * a locale, the locale of its parent is returned.
  339. *
  340. * @exception IllegalComponentStateException
  341. * If the Component does not have its own locale and has not yet been
  342. * added to a containment hierarchy such that the locale can be
  343. * determined from the containing parent.
  344. */
  345. public abstract Locale getLocale() throws IllegalComponentStateException;
  346. /**
  347. * Add a PropertyChangeListener to the listener list.
  348. * The listener is registered for all Accessible properties and will
  349. * be called when those properties change.
  350. *
  351. * @see #ACCESSIBLE_NAME_PROPERTY
  352. * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
  353. * @see #ACCESSIBLE_STATE_PROPERTY
  354. * @see #ACCESSIBLE_VALUE_PROPERTY
  355. * @see #ACCESSIBLE_SELECTION_PROPERTY
  356. * @see #ACCESSIBLE_TEXT_PROPERTY
  357. * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
  358. *
  359. * @param listener The PropertyChangeListener to be added
  360. */
  361. public void addPropertyChangeListener(PropertyChangeListener listener) {
  362. if (accessibleChangeSupport == null) {
  363. accessibleChangeSupport = new PropertyChangeSupport(this);
  364. }
  365. accessibleChangeSupport.addPropertyChangeListener(listener);
  366. }
  367. /**
  368. * Remove a PropertyChangeListener from the listener list.
  369. * This removes a PropertyChangeListener that was registered
  370. * for all properties.
  371. *
  372. * @param listener The PropertyChangeListener to be removed
  373. */
  374. public void removePropertyChangeListener(PropertyChangeListener listener) {
  375. if (accessibleChangeSupport != null) {
  376. accessibleChangeSupport.removePropertyChangeListener(listener);
  377. }
  378. }
  379. /**
  380. * Get the AccessibleAction associated with this object that supports
  381. * one or more actions.
  382. *
  383. * @return AccessibleAction if supported by object; else return null
  384. * @see AccessibleAction
  385. */
  386. public AccessibleAction getAccessibleAction() {
  387. return null;
  388. }
  389. /**
  390. * Get the AccessibleComponent associated with this object that has a
  391. * graphical representation.
  392. *
  393. * @return AccessibleComponent if supported by object; else return null
  394. * @see AccessibleComponent
  395. */
  396. public AccessibleComponent getAccessibleComponent() {
  397. return null;
  398. }
  399. /**
  400. * Get the AccessibleSelection associated with this object which allows its
  401. * Accessible children to be selected.
  402. *
  403. * @return AccessibleSelection if supported by object; else return null
  404. * @see AccessibleSelection
  405. */
  406. public AccessibleSelection getAccessibleSelection() {
  407. return null;
  408. }
  409. // /**
  410. // * Get the AccessibleTable associated with this object if one
  411. // * exists. Otherwise return null.
  412. // */
  413. // public AccessibleTable getAccessibleTable() {
  414. // return null;
  415. // }
  416. /**
  417. * Get the AccessibleText associated with this object presently editable
  418. * text on the display.
  419. *
  420. * @return AccessibleText if supported by object; else return null
  421. * @see AccessibleText
  422. */
  423. public AccessibleText getAccessibleText() {
  424. return null;
  425. }
  426. /**
  427. * Get the AccessibleValue associated with this object that supports a
  428. * Numerical value.
  429. *
  430. * @return AccessibleValue if supported by object; else return null
  431. * @see AccessibleValue
  432. */
  433. public AccessibleValue getAccessibleValue() {
  434. return null;
  435. }
  436. /**
  437. * Support for reporting bound property changes. If oldValue and
  438. * newValue are not equal and the PropertyChangeEvent listener list
  439. * is not empty, then fire a PropertyChange event to each listener.
  440. * In general, this is for use by the Accessible objects themselves
  441. * and should not be called by an application program.
  442. * @param propertyName The programmatic name of the property that
  443. * was changed.
  444. * @param oldValue The old value of the property.
  445. * @param newValue The new value of the property.
  446. * @see java.beans.PropertyChangeSupport
  447. * @see #addPropertyChangeListener
  448. * @see #removePropertyChangeListener
  449. * @see #ACCESSIBLE_NAME_PROPERTY
  450. * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
  451. * @see #ACCESSIBLE_STATE_PROPERTY
  452. * @see #ACCESSIBLE_VALUE_PROPERTY
  453. * @see #ACCESSIBLE_SELECTION_PROPERTY
  454. * @see #ACCESSIBLE_TEXT_PROPERTY
  455. * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
  456. */
  457. public void firePropertyChange(String propertyName,
  458. Object oldValue,
  459. Object newValue) {
  460. if (accessibleChangeSupport != null) {
  461. accessibleChangeSupport.firePropertyChange(propertyName,
  462. oldValue,
  463. newValue);
  464. }
  465. }
  466. }