25.2 The Accessibility Package

Now let's discuss the issues an assistive technology encounters when hooking into an accessibility-friendly application.

25.2.1 The Path to Determining Accessibility

Almost all Swing objects support one or more forms of accessibility, which means that they implement the Accessible interface. However, for an assistive technology to find out which types of accessibility an application supports, the technology needs to do some investigating. The typical course of action runs like this:

1. The assistive technology locates a desired component in the target application with the help of the Accessibility Utility APIs. Once found, it invokes the getAccessibleContext( ) method of the component object, which is the sole method of the Accessible interface. This method returns a customized AccessibleContext object, often an inner class of the component.

2. The assistive technology can then use the AccessibleContext object to retrieve the name, description, role, state, parent, and children components of the accessible component in question.

3. The assistive technology can register for any property change events in the component it's interested in.

4. The assistive technology can call upon several standardized methods to determine whether those types of accessibility are supported. All AccessibleContext objects have these interface methods. If any of these methods return null, then the component does not support the specific accessibility type.

5. If they are not null, the objects returned by each of the various methods can then be used to access the functionality on the component.

Different components implement different types of accessibility. For example, a tree might export accessibility action, selection, and component properties, while a button might simply export component properties. Components do not have to support all five steps. Hence, assistive technologies need to determine exactly which accessible functionality each component supports by querying that component for information.

25.2.2 The Accessible Interface

All components that need to export functionality to outside objects must implement the Accessible interface. This interface consists of only one method: getAccessible-Context( ). Assistive technologies must always call this method first to retrieve an accessible-context object from the component. This object can then be used to query the component about its accessible capabilities.

25.2.2.1 Method

public abstract AccessibleContext getAccessibleContext( )

Return the AccessibleContext object of the current component, or null if the component does not support accessibility.

25.2.3 The AccessibleContext Class

The AccessibleContext class is the heart of accessibility. It bundles component information that any assistive technology can learn about. The class has three primary responsibilities. First, it allows access to the accessible properties of the host component: its name, role, description, and current state, as well as a parent object and a list of child objects, if applicable. Second, it provides the ability to register for any change events on those properties. Third, the AccessibleContext object is responsible for reporting the accessible functionality that the component exports. Technologies that obtain the AccessibleContext object of a component can then call upon the following methods to determine which types of accessible functionality can be used:

public AccessibleAction getAccessibleAction( ) public AccessibleComponent getAccessibleComponent( ) public AccessibleComponent getAccessibleEditableText( )  // 1.4 public AccessibleComponent getAccessibleIcon( )          // 1.3 public AccessibleSelection getAccessibleSelection( ) public AccessibleComponent getAccessibleTable( )         // 1.3 public AccessibleText getAccessibleText( ) public AccessibleValue getAccessibleValue( )

Each of these methods returns a special object that an assistive technology can use to modify properties or invoke functionality inside the component. In the event that a component does not support one or more types, the respective method returns null.

The AccessibleContext class contains several abstract methods. Hence, each component has its own subclass of AccessibleContext that is returned by the getAccessibleContext( ) method of the Accessible interface.

25.2.3.1 Properties

Table 25-1 shows the properties of the AccessibleContext class. The most important are accessibleName and accessibleDescription. Both properties are usually set by the programmer of the host application. The accessibleName property gives a name to the component; some Swing components automatically set the accessible name as the text of the component. accessibleDescription gives a terse description of how the user should interact with the component.

Table 25-1. AccessibleContext properties

Property	Data type	get	is	set	Default value
accessibleAction	AccessibleAction	·
accessibleChildi	Accessible	·
accessibleChildrenCounta	int	·
accessibleComponent	AccessibleComponent	·
accessibleDescriptionb	String	·		·
accessibleEditableText1.4	AccessibleEditableText
accessibleIcon1.3	AccessibleIcon[]
accessibleIndexInParenta	int	·
accessibleNameb	String	·		·
accessibleParent	Accessible	·		·
accessibleRelationSet	AccessibleRelationSet
accessibleRolea	AccessibleRole	·
accessibleSelection	AccessibleSelection	·
accessibleStateSeta	AccessibleStateSet	·
accessibleTable1.3	AccessibleTable	·
accessibleText	AccessibleText	·
accessibleValue	AccessibleValue	·
localea	Locale	·
1.3since 1.3, 1.4since 1.4, aabstract, bbound, iindexed

The read-only accessibleRole property defines the purpose of the component. Accessible role values are predefined constants, such as SCROLL_BAR or PUSHABLE_BUTTON; they essentially tell what the component is. The accessibleStateSet property reflects the current state of the accessible component. There are a host of states that a component can be in.

The accessibleAction , accessibleSelection, accessibleText, accessibleValue, and accessibleComponent properties refer to the individual types of accessibility supported by each component. Each property contains a read-only object, used exclusively for interfacing with the accessible area of the component. The get accessors for these methods return null if there's no accessible object of the requested type for this component. If you have looked at the Accessibility API, you might think there should be an accessibleHyperlink property, but no such property exists. To get an AccessibleHyperlink, use getAccessibleText( ) and check whether the result is an instance of AccessibleHypertext. Once you have an AccessibleHypertext object, call getLink( ) to get an AccessibleHyperlink.

The accessibleParent property places the component in its accessibility hierarchy. Note that the accessibility hierarchy may differ from the regular component hierarchy. For example, a CellRenderer object inside a Swing list component does not have the JList as its parent in the component hierarchy. However, it does have the JList as a parent in the accessibility hierarchy. That way, if an assistive technology wished to access the list itself, it is not cut off by limitations in the component hierarchy.

The accessibleChildrenCount , accessibleChild, and accessibleIndexInParent properties each give details about this component in the current accessibility hierarchy. accessibleChild is an indexed property that provides references to each of the component's accessible children, while accessibleChildrenCount is an integer that returns the number of accessible children present. If this component is the child of a parent component in the accessibility hierarchy, the accessibleIndexInParent property indicates which index the component currently holds.

25.2.3.2 Accessible names and descriptions

Assistive technologies use the accessibleName property to distinguish the component from others of the same type. With named components, such as those that extend AbstractButton, the accessible name is automatically extracted from its label. For all others, you should always set the accessibleName property when including the component in your application. With Swing components, you can set the accessibility name with the following code fragment:

mySwingComponent.getAccessibleContext.setAccessibleName("Execute");

An assistive technology attempts to reference a component by keying off of its name, so it's probably a good idea to stick with standardized names. In other words, if you create a JPopupMenu object containing various chemical elements, make sure to call it something reasonable like "Elements" and not "The Elements Popup Menu of Gerald's Application." The latter would be extremely difficult for assistive technologies to identify. A good rule of thumb is to keep the names short but unique.

You can set the accessibility description of each component with the following short segment of code:

myButton.getAccessibleContext( ).setAccessibleDescription(   "Closes the dialog");

You can also set the description of a Swing component by giving it a tooltip string:

myButton.getAccessibleContext( ).setToolTipText("Closes the dialog");

Both approaches are equivalent. Assistive technologies can use the description property to learn more about the accessible component. The description is not as important as the name, but it frequently helps the user by providing instructions on how to work with a specific component.

25.2.3.3 Events

Objects extending the AccessibleContext class must fire a PropertyChangeEvent when one of its bound properties is modified. Assistive technologies listen for these events and modify their states or react in some fashion if such a change occurs.

public void addPropertyChangeListener(PropertyChangeListener listener)

public void removePropertyChangeListener(PropertyChangeListener listener)

Add or remove the specified PropertyChangeListener from the object's list of listeners.

public void firePropertyChange(String property, Object oldValue, Object newValue)

Fire a PropertyChangeEvent to all registered listeners indicating that the property has changed and provide both the old value and the new value of the property.

25.2.3.4 Constants

AccessibleContext uses the string constants listed in Table 25-2 to represent various properties when communicating change events.

Table 25-2. AccessibleContext constants

Constant	Description
ACCESSIBLE_ACTION_PROPERTY1.3	The supported set of actions has changed.
ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY	The active descendant of a component has changed.
ACCESSIBLE_CARET_PROPERTY	An AccessibleText component's caret property has changed.
ACCESSIBLE_CHILD_PROPERTY	The accessibleChild property has changed.
ACCESSIBLE_DESCRIPTION_PROPERTY	The accessibleDescription property has changed.
ACCESSIBLE_HYPERTEXT_OFFSET1.4	A hypertext element has received focus.
ACCESSIBLE_NAME_PROPERTY	The accessibleName property has changed.
ACCESSIBLE_SELECTION_PROPERTY	The accessibleSelection property has changed.
ACCESSIBLE_STATE_PROPERTY	The accessibleStateSet property has changed.
ACCESSIBLE_TABLE_CAPTION_CHANGED1.3	The table caption has changed.
ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED1.3	The column's description has changed.
ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED1.3	The column's header has changed.
ACCESSIBLE_TABLE_MODEL_CHANGED1.3	The table's model has changed.
ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED1.3	The row's description has changed.
ACCESSIBLE_TABLE_ROW_HEADER_CHANGED1.3	The row's header has changed.
ACCESSIBLE_TABLE_SUMMARY_CHANGED1.3	The table's summary has changed.
ACCESSIBLE_TEXT_PROPERTY	The accessibleText property has changed.
ACCESSIBLE_VALUE_PROPERTY	The accessibleValue property has changed.
ACCESSIBLE_VISIBLE_DATA_PROPERTY	The visual appearance of the component has changed.
1.3since 1.3, 1.4since 1.4