25.4 Types of Accessibility

Accessible components can export several types of assistive functionalities for example: actions, text properties, component properties, icon properties, selections, table properties, hypertext, and bounded-range value properties. Most of these functions are already present in the Swing components, so if you stick closely to Swing, you probably won't need to implement these interfaces in your components. In an effort to explain how one might implement these interfaces, we have provided a simple example showing how to add AccessibleAction support to an AWT-based component.

25.4.1 The AccessibleAction Interface

The AccessibleAction interface outlines the methods that an accessible object or component must have to export its actions. The idea is that an assistive technology can determine the correct action by obtaining the total number of actions that the component exports, then reviewing each of their descriptions to resolve the correct one. Once this has occurred, the doAccessibleAction( ) method can be called with the correct index to invoke the required method.

25.4.1.1 Properties

The properties in Table 25-5 must be readable through the AccessibleAction interface. accessibleActionCount stores the number of accessible actions that the component implements. The indexed property accessibleActionDescription provides a string describing the action associated with the given index. The action with index 0 is the component's default action.

Table 25-5. AccessibleAction properties

Property	Data type	get	is	set	Default value
accessibleActionCount	int	·
accessibleActionDescriptioni	Action	·
iindexed

25.4.1.2 Method

public abstract boolean doAccessibleAction(int index)

Invokes an action based on the given index. The method returns false if an action with that index does not exist. It returns true if successful.

25.4.2 The AccessibleComponent Interface

The AccessibleComponent interface should be supported by any component that is drawn to a graphical context on the screen. Assistive technologies can use this interface to change how the component is drawn. Almost all of the methods in this interface call equivalent methods in the java.awt.Component class, so you will find this accessibility type in almost every Swing component. Adding AccessibleComponent support to your own components is a trivial exercise.

25.4.2.1 Properties

The properties in Table 25-6 must be made available by classes that implement the AccessibleComponent interface. These properties should be fairly self-explanatory if you're familiar with the way JComponents work. The background and foreground properties let you manipulate the component's background and foreground colors. The cursor and font properties let you manipulate the component's cursor or font.

Table 25-6. AccessibleComponent properties

Property	Data type	get	is	set	Default value
background	Color	·		·
bounds	Rectangle	·		·
cursor	Cursor	·		·
enabled	boolean		·	·
focusTraversable	boolean		·
font	Font	·		·
foreground	Color	·		·
location	Point	·		·
locationOnScreen	Point	·
showing	boolean		·
size	Dimension	·		·
visible	boolean		·	·

The enabled , showing, and visible properties let you find out the component's status. A component that is enabled has AccessibleState.ENABLED as part of its accessibleStateSet property. Likewise, a component that is visible has AccessibleState.VISIBLE as part of its accessibleStateSet, and a component that is showing has AccessibleState.SHOWING as part of its accessibleStateSet. A visible component is showing only if all of its ancestors are also visible. Remember that it's possible for a component that's showing to be hidden by another component.

The location , locationOnScreen, bounds, and size properties let you find out about the real estate occupied by the component. location gives you access to the component's position in the parent container's coordinate system; locationOnScreen gives you access to the component's position in the screen's coordinate system. The bounds property is a Rectangle that describes the component's bounding box; the size property is a Dimension that gives you the component's width and height, including any insets or borders.

The focusTraversable property tells you whether this object can accept focus. If its value is true, the component also has AccessibleState.FOCUSABLE as part of its accessibleStateSet.

25.4.2.2 Events

Objects implementing the AccessibleComponent interface must be able to register listeners for focus events generated by the component.

public abstract void addFocusListener(FocusListener l)

public abstract void removeFocusListener(FocusListener l)

Add or remove the specified FocusListener from the event listener list.

25.4.2.3 Methods

public abstract boolean contains(Point p)

Return a boolean indicating whether the point passed in (in object coordinates) is within the bounding box of the component.

public abstract Accessible getAccessibleAt(Point p)

Return a component that implements the Accessible interface under the point passed in, or null if one does not exist.

public abstract void requestFocus( )

Make a request to grab the focus. Note that the method returns void; if it does not succeed, it will not notify the caller.

25.4.3 The AccessibleSelection Interface

AccessibleSelection is a simple interface that allows assistive technologies to query a component for information about its current selections. By selections, we mean choosing one or more items in a component, such as from a JList. The interface also contains methods that allow outside modification to the current set of selections.

The AccessibleSelection interface works by interfacing with two separate lists. The first is the standard data list of objects that have been added to the component, typically with an add( ) method. The second is the selection list; this list contains zero-based indexes into the former list. With Swing, the JList class is the most obvious candidate for implementing the AccessibleSelection interface. With this class, the interface simply monitors both the model and the selection model of the JList to complete its functionality.

Again, this is a case where the objects in the accessibility hierarchy differ from the traditional component hierarchy. Here, the accessible children of an AccessibleSelection component should be the objects returned by the getAccessibleSelection( ) method in other words, the objects added to the selectable list. As you might guess, all the objects that can be selected must implement the Accessible interface.

25.4.3.1 Properties

The properties listed in Table 25-7 must be readable through the AccessibleSelection interface. The accessibleSelectionCount property tells you how many selections the user has made. accessibleSelection, which is indexed, lets you access a particular selection given by the index. accessibleChildSelected, which is also indexed, lets you find out whether a particular child of the component is on the selection list; in this case, the index refers to one of the component's children, and a true value indicates that the child specified by the index is on the selection list.

Table 25-7. AccessibleSelection properties

Property	Data type	get	is	set	Default value
accessibleSelectionCount	int	·
accessibleSelectioni	Accessible	·
accessibleChildSelectedi	boolean		·
iindexed

25.4.3.2 Methods

public abstract void addAccessibleSelection(int index)

Add the child referenced by index in the data list to the selection list. If the child is already present, it is not added again. If the selection list supports only one selection at a time, the child replaces the previous selection on the list.

public abstract void removeAccessibleSelection(int index)

Remove the child referenced by index in the data list from the current selection list. If the child is not currently selected, this method has no effect.

public abstract void clearAccessibleSelection( )

Clear the selection list.

public abstract void selectAllAccessibleSelection( )

Add every child contained in the component to the selection list.

25.4.4 The AccessibleText Interface

The AccessibleText methods are used to export "editable" text to assistive technologies. By editable, we mean text that the user can normally click and change, as opposed to static text that you would see in labels or buttons. The AccessibleText interface provides several methods that allow you not only to change the text, but to obtain many of its attributes. The AccessibleText interface is generally used only with the Swing components because much of the required functionality is not available in AWT components.

25.4.4.1 Properties

The read-only properties in Table 25-8 must be made available by classes that implement the AccessibleText interface.

Table 25-8. AccessibleText properties

Property	Data type	get	is	set	Default value
caretPosition	int	·
characterAttributei	AttributeSet	·
characterBoundsi	Rectangle	·
charCount	int	·
selectedText	String	·
selectionEnd	int	·
selectionStart	int	·
iindexed

25.4.4.2 Constants

The AccessibleText interface uses the constants listed in Table 25-9. The charCount property lets you retrieve the total number of characters in the text buffer. characterBounds lets you retrieve the Rectangle bounding the character at a given index. caretPosition gives you the index of the character directly to the right of the caret.

Table 25-9. AccessibleText constants

State	Meaning
CHARACTER	Retrieves the current character at or near the specified index
WORD	Retrieves the current word at or near the specified index
SENTENCE	Retrieves the current sentence at or near the specified index

25.4.4.3 Methods

public abstract String getAfterIndex(int part, int index)

Return the current character, word, or sentence after the given index, depending on which AccessibleText constant is passed in.

public abstract String getAtIndex(int part, int index)

Return the current character, word, or sentence from the given index, depending on which AccessibleText constant is passed in.

public abstract String getBeforeIndex(int part, int index)

Return the current character, word, or sentence before the given index, depending on which AccessibleText constant is passed in.

public abstract int getIndexAtPoint(Point p)

Take a Point in local coordinates and return an index to the text character that resides under the point. If there is no text under the given point, the method must return -1.

25.4.5 The AccessibleHypertext Interface

The AccessibleHypertext interface extends the AccessibleText interface to allow access to hypertext, such as you'd see in a web page. In order to determine whether a given component has any accessible hyperlinks in it, call the getAccessibleText( ) method of the component's AccessibleContext object and check to see if the object returned is an instance of the AccessibleHypertext interface. If it is, the resulting object is a special hypertext accessibility object that can be used to obtain not only the traditional accessible text information but also the number of hyperlinks in the page and AccessibleHyperlink objects for each link.

25.4.5.1 Properties

AccessibleHypertext defines the properties listed in Table 25-10. The linkCount property tells you the number of hyperlinks in the text. The indexed property linkIndex gives you the index of the hyperlink at the given character offset into the text. The link property itself, which is also indexed, lets you access the hyperlink specified by the index. For example, to find the hyperlink associated with character n, you could write:

AccessibleHyperlink h = getLink(getLinkIndex(n));

Table 25-10. AccessibleHypertext properties

Property	Data type	get	is	set	Default value
linki	AccessibleHyperlink	·
linkCount	int	·
linkIndexi	int	·
iindexed See also properties of the AccessibleText interface (Table 25-8).

25.4.6 The AccessibleHyperlink Class

The AccessibleHyperlink class is an abstract class that encapsulates an HTML hyperlink in a text document. Hyperlinks (and concrete extensions of the AccessibleHyperlink class) are found only inside the document models of a JEditorPane. The AccessibleHyperlink class implements the AccessibleAction interface, which normally provides support for any number of actions in accessible components. For the most part, AccessibleHyperlink objects have only one action associated with them, which results in loading the text pane with the HTML document or image associated with the link. AccessibleHyperlink objects are returned from the getLink( ) accessor of an AccessibleHypertext object.

25.4.6.1 Properties

The AccessibleHyperlink class defines the properties listed in Table 25-11. All of the properties are abstract. The endIndex and startIndex properties let you access the starting and ending offsets of this hyperlink in the document from which it came. The valid property is true if the document that this hyperlink points to is still valid (i.e., has not changed).

Table 25-11. AccessibleHyperlink properties

Property	Data type	get	is	set	Default value
accessibleActionAnchora,i	Object	·
accessibleActionCounta	int	·
accessibleActionDescriptiona,i	String	·
accessibleActionObjecta,i	String	·
endIndexa	int	·
startIndexa	int	·
valida	boolean		·
aabstract, iindexed

The remaining properties let you work with an AccessibleAction (or actions) associated with this hyperlink. accessibleActionCount lets you find out how many actions are associated with the hyperlink; this is usually one, but there can be more. If there are more, the first action is not considered the default. accessibleActionDescription lets you retrieve a String describing a particular action. accessibleActionObject lets you access an object representing the action itself. For example, given a hyperlink to the URL http://www.oreilly.com/, getAccessibleActionObject will return a Java URL pointing to http://www.oreilly.com/. Finally, accessibleActionAnchor gives you the object that is displayed on the screen to represent the link. For example, if the link is a clickable image, getAccessibleActionAnchor returns an ImageIcon; if the link is represented by text, this method returns a String containing the text.

25.4.6.2 Method

public abstract boolean doAccessibleAction(int index)

This method performs the action specified by the given integer index.

25.4.7 The AccessibleValue Interface

The AccessibleValue interface is responsible for handling a bounded-range value property inside a component. For example, the current value of a slider would be considered an accessible value that a component can export to an assistive technology. This is a simple interface that contains only four methods. Note that the value's data type is the generic Number; it is up to the caller to ensure that the data type passed in is correct and that the value returned is cast to the correct object.

25.4.7.1 Methods

public abstract Number getCurrentAccessibleValue( )

Return the current value as a Number. If the value has not been initialized, this method returns null.

public abstract boolean setCurrentAccessibleValue(Number n)

Attempt to set the current value to the number passed in. If the number passed in is not the correct type, or if it cannot be set, the method returns false. Otherwise, the method returns true.

public abstract Number getMinimumAccessibleValue( )

Return the current minimum value as a Number. The caller is responsible for casting the returned Number to the appropriate data type.

public abstract Number getMaximumAccessibleValue( )

Return the current maximum value as a Number. The caller is responsible for casting the returned Number to the appropriate data type.