Skip to main content



6.0 The accessibility API
The Java Accessibility API is a set of interfaces and classes designedby the Sun Microsystems Accessibility Group, IBM Human Ability and Accessibility Center, Trace Research and Development Center of the University of Wisconsin atMadison, and other leading accessibility organizations.

The Java Accessibility API defines a common signature, which can be implemented on application components, giving them a known interface to allow assistive technologies to extract the accessibility information from the application.

The Java Accessibility API is shipped with Java 2 SDK Standard Edition (SE) as the javax.accessibility package.


6.1 Interface accessible
This section covers what a Java interface is and how you use the interface to give objects an accessible signature.

6.1.1 Interfaces
For those new to Java, an interface is a defined signature of methods and properties that can be implemented by a particular class. As a developer, if you were to "implement" the interface on your particular class, you would need to provide all the methods and properties as defined by the signature. Failure to meet the interface specification would result in compilation errors. In Java, an assistive technology can examine if an object is an instance of a particular interface using the instanceof operator. The first interface we will describe tells us whether an object has implemented the basic Accessibility API.

6.1.2 Using interface accessible
Accessible is an interface that you need to apply to your class file to let assistive technologies know you have implemented the Accessibility API. The following Java code example shows you how to implement Accessible on your own custom component.

 import java.awt;
 import javax.accessibility;
 class MyButton implements Accessible extends Component{
      AccessibleContext getAccessibleContext() {
         ...
      }
 }

Figure 4.0 Implementation of Accessible
The Accessible interface provides a method that returns the AccessibleContext. The AccessibleContext provides the most basic accessibility information needed for any component.

The object that getAccessibleContext() returns also implements more detailed accessibility information based on the role of the GUI class being used. Some of the methods that AccessibleContext defines, return a null value because they really do not apply. For example, there is no reason to implement the AccessibleText interface on a scroll bar.

One way to maintain the AccessibleContext is by keeping an internal class inside your GUI class file, which keeps track of the accessibility information. When an assistive technology asks for the AccessibleContext, you simply provide the reference to your internal AccessibleContext.


6.2 AccessibleContext
AccessibleContext is an abstract class that must be maintained by each GUI object making up your program. It contains much of the accessibility information. Table 3.1 shows the methods AccessibleContext supports and their descriptions.

Assistive technologies can easily use AccessibleContext. For example, by querying AccessibleContext, an assistive technology program can know about and announce changes in a text field.

AccessibleContext Abstract Class Methods
Method Description
addPropertyChangeListener
(PropertyChangeListener)
Adds a PropertyChangeListener to the listener list.
firePropertyChange(String property, Object oldValue, Object newValue) Supports reporting bound property changes.
getAccessibleAction() Gets the AccessibleAction associated with this object that supports one or more actions.
getAccessibleChild(int) Returns the specified Accessible child of the object.
getAccessibleChildrenCount() Returns the number of Accessible children of the object.
getAccessibleComponent() Gets the AccessibleComponent associated with this object.
getAccessibleDescription() Gets the AccessibleDescription property of this object.
getAccessibleIcon() Gets the AccessibleIcon associated with an object that has one or more associated icons. If your object has an icon displayed within it you should return an AccessibleIcon object or null otherwise. If you have more than one icon displayed you should provide a description in AccessibleIcon that best describes the information represented by the collection of icons.

Note: Supported in Java 2 SDK 1.3 or later

getAccessibleIndexInParent() Gets the 0-based index of this object in its accessible parent.
getAccessibleName() Gets the AccessibleName property of this object.
getAccessibleParent() Gets the AccessibleParent of this object.
getAccessibleRelationSet() Gets the AccessibleRelationSet for this object. This set is a collection of symantic relationships between this and other components.

Note: Supported in Java 2 SDK 1.3 or later

getAccessibleRole() Get the role of this object.
getAccessibleSelection() Gets the AccessibleSelection associated with this object.
getAccessibleStateSet() Get the state set of this object.
getAccessibleTable() Gets the AccessibleTable contained in this object. Applications which present data in a 2-dimensional table format must return an AccesssibleTable object or null if it does not. Note: The AccessibleRole of the object supporting AccessibleTable should be AccessibleRole.TABLE. See

Note: Supported in Java 2 SDK 1.3 or later

getAccessibleText() Gets the AccessibleText associated with this Component. Note: If this text should also include hypertext links, this method should return an AccessibleHypertext object.
getAccessibleValue() Gets the AccessibleValue associated with this object.
getLocale() Gets the locale of the component.
removePropertyChangeListener(PropertyChange
Listener listener)
Removes a PropertyChangeListener from the listener list.
setAccessibleDescription(String description) Sets the accessible description of this object.
setAccessibleName(String name) Sets the localized accessible name of this object.
setAccessibleParent(Accessible parent) Sets the accessible Parent of this object.

6.2.1 Basic accessible information
This section describes:


6.2.1.1 AccessibleName
AccessibleName is simply the name of the object. Here are some general rules to follow for setting the AccessibleName:

  • ACCESSIBLE_name_PROPERTY as described in section 6.2.4 Property Change Notification

6.2.1.2 AccessibleDescription
AccessibleDescription is a text description of an object's purpose. For example, if you had a table in your application containing your current month's categorized cash flow, you should provide a text description using AccessibleDescription.

To write a class file that is accessible, follow these rules:

  • When you change the AccessibleDescription, be sure to fire the ACCESSIBLE_DESCRIPTION_PROPERTY as described in section 6.2.4 Property Change Notification.

If you need to use an existing Accessible class file to build an application, and the default AccessibleDescription does not accurately describe the function of the new object, set the new AccessibleDescription in the new class file.


6.2.1.3 AccessibleValue
Use AccessibleValue only for a specific set of object types, that provide a range of values and a current setting. Otherwise, return null for this value. Scroll bars, sliders, and progress bars, where the current value needs to be acquired, are examples of objects needing an AccessibleValue setting.

AccessibleValue supports the methods in Table 5.0.

For example, in a progress bar the ACCESSIBLE_VALUE_CHANGE event should be fired when the progress bar increases its current value. For more information about firing this property change, see section 6.2.4 Property Change Notification.

AccessibleValue Interface Methods
Method Description
getCurrentAccessibleValue() Gets the value of this object as a java.lang.Number.
getMaximumAccessibleValue() Gets the maximum value of this object as a java.lang.Number.
getMinimumAccessibleValue() Gets the minimum value of this object as a java.lang.Number.
setCurrentAccessibleValue(Number) Sets the current value of this object as a java.lang.Number.

Table 5.0 AccessibleValue Interface Methods


Important:
Whenever the current accessible value changes, you need to fire the ACCESSIBLE_VALUE_CHANGE property change in the AccessibleContext.


6.2.1.4 Locale
This is the current locale for which your component was written. See the Java 2 SDK for a more detailed description. Low-vision assistive technology uses this information to determine how to speak your application. When you extend either the AWT Component class or JComponent, to make your custom Component, you can return the Locale in AccessibleContext using the getLocale method in java.awt.Component.


6.2.1.5 AccessibleSelection
AccessibleSelection is a collection of the selected accessible children for your object. AccessibleSelection maintains an internal vector of selected items. The collection is referenced by an index from 0 to the n-1 selection. The n-1 selection is the last selected item and is where the user would have the current input focused. For example, if your object is a list box, this would maintain the collection of currently selected entries as proxied by your list box.

AccessibleSelection is an extremely important feature when supporting the Accessibility API. It allows assisitve technology to tell the user what is currently selected. AccessibleSelection would be applied to lists, menus, the list in a combo box, selected minimized windows inside a desktop manager window, and so on.

For more information about firing this property change, see section 6.2.4 Property Change Notification

AccessibleSelection supports the methods listed in Table 6.0.

AccessibleSelection Interface Methods
Method Description
addAccessibleSelection(int) Adds the selected item in the object to the object's selection.
clearAccessibleSelection() Clears the selection in the object, so that nothing in the object is selected.
getAccessibleSelection(int) Returns an Accessible object representing the selected item in the object.
getAccessibleSelectionCount() Returns the number of items currently selected.
isAccessibleChildSelected(int) Returns true if the current child of this object is selected. Otherwise, returns False.
removeAccessibleSelection(int) Removes the selected item in the object from the object's selection.
selectAllAccessibleSelection() Causes every selected item in the object to be selected if the object supports multiple selections.

Table 6.0 AccessibleSelection Interface Methods


Important:
When changes occur in the AccessibleSelection, you need tofire the ACCESSIBLE_SELECTION_PROPERTY property change event in theAccessibleContext.

For non-AccessibleText components, you also need to fire anACCESSIBLE_ACTIVE_DESCENDANT_PROPERTYproperty change event when the current ACTIVE child changes. This allows an assistive technology to process multiple selected items while keeping track of the current active selected item.


6.2.1.6 AccessibleComponent
AccessibleComponent is the accessible JDK component associated with this accessible object. AccessibleComponent defines a standard interface for assistive technologies to directly interact with an object's associated component. It provides a framework for modifying and querying standard component settings as well as asking questions about the component's children.
AccessibleComponent applies to objects that have an associated component, like the base components for a given GUI framework. An example is the JFC JComponent class.
AccessibleComponent supports the methods listed in Table 7.0.

AccessibleComponent Interface Methods
Method Description
addFocusListener(FocusListener) Adds the specified focus listener to receive focus events from this component.
contains(Point) Checks whether the specified point is within this object's bounds (the point's x and y coordinates are defined to be relative to the coordinate system of the object).
getAccessibleAt(Point) Returns the Accessible child, if one exists, contained at the local coordinate Point.
getBackground() Gets the background color.
getBounds() Get the object's bounds as a Rectangle object.
getCursor() Gets the Mouse Cursor.
getFont() Gets the Font.
getFontMetrics(Font) Gets the FontMetrics.
getForeground() Gets the foreground color.
getLocation() Gets the object's location relative to the parent as a point specifying the object's top-left corner in the screen's coordinate space.
getLocationOnScreen() Returns the object's Point location on the screen.
getSize() Returns the object's size as a Dimension object.
isEnabled() Determines if the object is enabled.
isFocusTraversable() Returns whether this object can accept focus or not.
isShowing() Determines if the component is showing.
isVisible() Determines if the component is visible.
removeFocusListener(FocusListener) Removes the specified focus listener so it no longer receives focus events from this component.
requestFocus() Requests focus for this object.
setBackground(Color) Sets the background color.
setBounds(Rectangle) Sets the object's bounds as a Rectangle object.
setCursor(Cursor) Sets the Mouse Cursor.
setEnabled(boolean) Sets the enabled state.
setFont(Font) Sets the Font.
setForeground(Color) Sets the foreground color.
setLocation(Point) Sets the object's location relative to the parent.
setSize(Dimension) Resizes the object so that it has width and height.
setVisible(boolean) Sets the visible state.

Table 7.0 AccessibleComponent Interface Methods

When you are programming the AccessibleContext, you will find that you can retrieve much of the AccessibleComponent information directly from the actual associated JDK awt.Component and JFC base javax.swing.JComponent class. In the case of JFC, the base JComponent class has an internal abstract class called AccessibleJComponent. AccessibleJComponent extends AccessibleAWTContainer which ultimately subclasses AccessibleContext and implements AccessibleComponent in java.awt.Component.

As a result, AccessibleJComponent already implements many of the methods needed to support needed to support AccessibleComponent because the information can be acquired directly from java.awt.Component. Also the property firing mechanism for accessibility property changes has already been implemented in AccessibleContext. Therefore, the code in AccessibleJComponent could be trivially placed in a non-JFC component, that extends awt.Component to help create a custom, non-JFC accessible component. See section 5 Building Custom Accessible Components.

The code snippets in Figure 8.0 appear in JComponent.java

 Class JComponent {
    protected AccessibleContext accessibleContext = null;
    /**
     * Get the AccessibleContext associated with this 
     * JComponent
     *
     * @return the AccessibleContext of this JComponent
     */
    public AccessibleContext getAccessibleContext() {
        return accessibleContext;
    }
    // Note: AccessibleAWTContainer subclasses 
AccessibleAWTComponent in java.awt.Container 
    // which extends AccessibleContext and implements 
AccessibleComponent in java.awt.Component.
    public abstract class AccessibleJComponent 
extends AccessibleAWTContainer {
    
/**
 * Though the class is abstract, this should be 
 called by
 * all sub-classes. 
 */
protected AccessibleJComponent() {
            // really if JDK1.3...
            super();
  
        }
protected ContainerListener accessibleContainerHandler 
= null;
    protected FocusListener accessibleFocusHandler 
= null;
        .
        .
        .
        // AccessibleContext methods
        //
        /**
         * Gets the accessible name of this object. This 
should almost never
         * return java.awt.Component.getName(), as that 
generally isn't
         * a localized name, and doesn't have meaning for the 
user.  If the
         * object is fundamentally a text object (such as a 
menu item), the
         * accessible name should be the text of the object 
(for example, 
         * "save").
         * If the object has a tooltip, the tooltip text 
may also be an
         * appropriate String to return.
         *
         * @return the localized name of the object -- can be 
null if this
         *         object does not have a name
         * @see AccessibleContext#setAccessibleName
         */
        public String getAccessibleName() {
    String name = accessibleName;
    // fallback to the titled border if it exists
    //
            if (name == null) {
name = getBorderTitle(getBorder());
            }
    // fallback to the label labeling us if it exists
    //
            if (name == null) {
Object o = getClientProperty(JLabel.LABELED
_BY_PROPERTY);
if (o instanceof Accessible) {
    AccessibleContext ac = ((Accessible)
o).getAccessibleContext();
    if (ac != null) {
name = ac.getAccessibleName();
    }
}
    }
    return name;
        }
        /**
         * Gets the accessible description of this object.
This should be
* a concise, localized description of what this 
object is - what
         * is its meaning to the user.  If the object has
a tooltip, the
         * tooltip text may be an appropriate string to
return, assuming
         * it contains a concise description of the 
object (instead of just
         * the name of the object - for example a "Save"
icon on a toolbar that
         * had "save" as the tooltip text shouldn't 
return the tooltip
         * text as the description, but something like
"Saves the current
         * text document" instead).
         * @return the localized description of the 
object -- can be null if
         * this object does not have a description
         * @see AccessibleContext#setAccessibleDescription
         */
        public String getAccessibleDescription() {
    String description = accessibleDescription;
    // fallback to the tool tip text if it exists
    //
            if (description == null) {
                try {
                    description = getToolTipText(null);
                } catch (Exception e) {
                }
            }
    // fallback to the label labeling us if it exists
    //
            if (description == null) {
Object o = getClientProperty(JLabel.LABELED_
BY_PROPERTY);
if (o instanceof Accessible) {
    AccessibleContext ac = ((Accessible) 
o).getAccessibleContext();
    if (ac != null) {
description = ac.getAccessible
Description();
    }
}
    }
    return description;
        }
        .
        .
        .
 }
}

Figure 8.0 Example Code found in JFC's JComponent for Supporting AccessibleComponent Information

The sample code in Figure 9.0 demonstrates the structure for building an accessible component when using the JFC JComponent as a base. Because the internal JComponent class, AccessibleJComponent, extends AccessibleContext, you automatically get the AccessibleComponent methods.

   class MyButton extends JComponent implements Accessible{
        String ButtonText;
     AccessibleContext GetAccessibleContext() {
        If accessibleContext != null 
           AccessibleContext == new MyAccessibleComponent();
     }
     class MyAccessibleButton extends AccessibleJComponent() {
       String AccessibleName();
       .
       .
       .
       getAccessibleName() {
          if (accessibleName == null)
             return ButtonText;
          else 
             return AccessibleName;
       }
     }
   }

Figure 9.0 Sample Code Demonstrating the Use of JComponent to Support Accessible Component

Although we have selected to show JComponent as the foundation for building an accessible component, you can also use the JDK Component class. Many of the methods such as getFont in AccessibleComponent can be acquired from java.awt.Component.


Important:
When building applications using JFC, it is recommended that you start from JComponent or another existing JFC component to build your new, custom Accessible component. When building non-JFC applications you should start by building off the java.awt.Component class or a descendant of it.


6.2.1.7 AccessibleText
AccessibleText is used for providing detailed access to complex and editable text documents and text fields. Examples of this are text edit fields, text areas, WYSIWYG web browser and word processing client areas, and mail program client areas. These areas often involve the use of a caret for entering text when they are in an editable state. AccessibleContext should return null for AccessibleText in the case of scroll bars, check boxes, and so on.

AccessibleText interface (Table 10) provides a mechanism for assistive technologies to gain access to documents by defining a character-indexed mechanism for traversing documents in your program. The predecessors of the Accessibility API relied on an Off-Screen model (text-database reconstruction) of the desktop to provide access to programs and documents. This was unreliable and often the biggest causes for delay in providing access to a new GUI-based windowing system. The AccessibleText approach is truly state-of-the-art in access technology and it is one that facilitates multi-modal access to applications by mainstream users.

AccessibleText Interface Methods
Method Description
getAfterIndex(int part, int index) Returns the String after a given index based on the part defined in 6.2.1.7.3.
getAtIndex(int part, int index) Returns the String at a given index based on the part defined in 6.2.1.7.3.
getBeforeIndex(int part, int index) Returns the String before a given index based on the part defined in 6.2.1.7.3.
getCaretPosition() Returns the zero-based offset of the caret.
getCharacterAttribute(int index) Returns the AttributeSet for a given character (at a given index).
getCharacterBounds(int index) Determines the bounding box of the character at the given index into the string.
getCharCount() Returns the number of characters (valid indicies).
getIndexAtPoint(Point) Given a point in local coordinates, returns the zero-based index of the character under that Point.
getSelectedText() Returns the portion of the text that is selected.
getSelectionEnd() Returns the end offset within the selected text.
getSelectionStart() Returns the start offset within the selected text.

Table 10.0 AccessibleText Interface Methods


6.2.1.7.1 Text attributes
To implement AccessibleText you will need to examine how you have built your document model. Most document models are designed based on how they handle paragraphs, runs of text with common properties, an embedded graphic, and so on. The HTML web page is the epitome of a complex document as it also allows the document to be interactive. In fact, a web browser may have to handle an embedded Java applet. The idea here is to convert your document to a text representation. To do this, you need to know more about the attribute set associated with each character and how the attribute set is used to embed complex components and icons.

When an assistive technology wishes to get the set of attributes for a given index, it will call the AccessibleText method getCharacterAttribute(int index) for the given character index. This returns an object of class AttributeSet that maintains a database of key/value pairs as defined in Table 3.0 for the StyleConstants class. To get the background color for a character index in your document it would issue the following set of calls:

   import javax.swing.text.StyleConstants;
   import javax.swing.text.AttributeSet;
   import javax.swing.accessibility.*;
   Color getColor(Accessible yourComponent, int index) {
      Color bg = null;
      AccessibleContext ac = yourComponent.getAccessible
  Context();
      AccessibleText    at = ac.getAccessibleText();
      // Get the Attribute Set
      AttributeSet aset = at.getCharacterAttribute
  (index); 
      // Get the background color
      bg = (Color) aSet.getAttribute
  (StyleConstants.Background);
     
      while (bg == null) {
         //No background color here: Check the Parent
         //Attribute Set
         aSet = (AttributeSet) aSet.getAttribute
 (StyleConstants.ResolveAttribute);
         if (aSet != null) {
            bg = (Color) aSet.getAttribute
(StyleConstants.Background);
            if (bg != null) 
               break;
         }
         else 
            break;   
      }
      /* When no background color exists in the */
      /* AttributeSet Tree, get the the color */
      /* from the accessible component */
      if (bg == null) {
         AccessibleComponent acx = ac.getAccessible
 Component();
         bg = acx.getBackground();
      }
      return bg; // return the background color
   }

Figure 11.0 Retrieving the Background Color from AccessibleText

Figure 11.0 shows how an assistive technology program will search the attribute set tree looking for the background color attribute. When it finds the information, it will stop the search. Otherwise, it will get the information from the AccessibleComponent. When storing runs of attributes in your attribute set, use AttributeSet. To make programming easy, Sun has provided you with a class called SimpleAttributeSet in the JFC. This supports the descendant AttributeSet interface for adding attributes to it called MutableAttributeSet. Like AttributeSet, MutableAttributeSet is a JFC interface.

If you wanted to create an HTML document, where the default colors were black on white. You would create your default attribute set as follows:

 SimpleAttributeSet DefaultAttributeSet;
 DefaultAttibuteSet.add(StyleConstants.Foreground,
 Color.black);
 DefaultAttibuteSet.add(StyleConstants.Background,
 Color.white);
 //Give the run a name
 LinkAttribute.Set.add(StyleConstants.NameAttribute, "");

If your browser which controlled the document drawing detected a hypertext link in the input stream, where the hypertext foreground color was to be blue and the text underlined, you would create an AttributeSet run and add it as follows:

 // Create an Attribute Set run with blue, 
 underlined
 // Foreground text
 SimpleAttributeSet LinkAttributeSet = New 
 SimpleAttributeSet();
 LinkAttributeSet.add(StyleConstants.Foreground, 
 Color.blue)
 LinkAttributeSet.add(StyleConstants.Underline, 
 new Boolean(true));
 //Give the run a name
 LinkAttribute.Set.add(StyleConstants.NameAttribute,
 "<LINK>");
 // Set the Resolving Parent, so the assistive 
 technology can determine the background color
 LinkAttributeSet.setResolveParent(DefaultAttributeSet);

Now, you simply have to store this AttributeSet with the specified run of text in your document, based on your document data model. When assistive technology goes to index the text in your document to grab the AttributeSet, you will be ready with the information. Furthermore, you will have the attribute information available to draw the run yourself.


6.2.1.7.2 Embedding objects
Your document may contain an "embedded" complex document or non-text object that identifies a special component to be handled by your application. For this, simply provide a blank character for the object's index position, reference the Component which draws it in the AttributeSet, just like attributes for font, foreground color, and so on. The Component referenced in the attributes needs to implement the Accessibility API. An example could be the inclusion of a JTable. Another example may be a JLabel containing a bit map. This design allows assistive technologies to scan or browse your document. If the user wishes to focus on the embedded object, he can focus and expand his view of the document to that component or ignore it entirely.

 // Create an Attribute Set run with blue, underlined
 // Foreground text
 SimpleAttributeSet TableAttributeSet = New SimpleAttributeSet
 ();
 TableAttributeSet.add(StyleConstants.ComponentAttribute, new 
 JTable());
 //Give the list of components a name
 TableAttributeSet.add(StyleConstants.ComponentElementName, 
 "Table of Contents");
 //Give the run a name
 TableAttribute.Set.add(StyleConstants.NameAttribute,
 "<TABLE>");
 //Set the Resolving Parent, so assistive technologies can 
 determine the background color
 LinkAttributeSet.setResolveParent(DefaultAttributeSet);

To embed icons, simply follow the same procedure for using a blank character to represent the indexed character for the icon. In the attribute, create a run, which sets the run AttributeSet information as follows:

Sample Attributes for Embedding Icons in Attribute Sets
Attribute Value
StyleConstants.NameAttribute "<IMG>"
StyleConstants.IconElementName URL String for the Icon
StyleConstants.IconAttribute (Icon)new ImageIcon(URL,

Description);

Table 12: Sample Attributes for Embedding Icons in Attribute Sets

Now that you know how to embed objects, the question is when to embed objects. To answer this question, put yourself in a blind user's shoes. This user wants to be able to read your document in a browsing fashion. When he runs across a new paragraph he may want to know that it is a new paragraph, but he does not want to deal with it like an embedded document. Consider embedded documents as document parts you may want to skip over in when casually browsing.

Examples of true embedded documents are tables, a Java applet used to show a MPEG video and so on. If the user wants to expand his view on this embedded object, he can ask his assistive technology to expand the view on that object. The object could be a text area in an HTML Form. In this case, the user could detect from the run that a text area exists and can choose to expand his view on the text area. The embedded object should have implemented Accessible and its AccessibleContext should support AccessibleText.


6.2.1.7.3 Referencing the indexed character string
As shown in section 6.2.1.7 AccessibleText, access to text, through the AccessibleText interface is based on a character index and the part of text you want to retrieve around that index. At a given character index, the assistive technology requests the corresponding word, character, or sentence based on the method and part definitions of AccessibleText.CHARACTER, AccessibleText.WORD, or AccessibleText.SENTENCE, respectively.


6.2.1.7.4 Caret position and SelectedText
The AccesibleText interface refers to offsets for these values (the character index for these items in your AccessibleText document). The definition of the Caret is obvious, but to avoid confusion, SelectedText is the text the user has highlighted often for cutting, pasting, and deleting.

Important:
If you are developing a new accessible text class (non-JFC), please remember to keyboard-enable selecting text. This is accomplished by the user holding the shift key down at the caret position and moving the arrow keys, pressing the PAGE-UP, END, HOME, or PAGE-DOWN in succession.

A good way to verify your keyboard accessibility is to unplug your mouse and try to navigate the text object yourself.


6.2.1.7.5 Property changes
The three property changes you must fire for AccessibleText are:

Your AccessibleText implementation should fire these changes from the firePropertyChange method in your implementation of AccessibleContext.

Important:
Do not fire ACCESSIBLE_VISIBLE_DATA_PROPERTY for AccessibleText Components. Use the ACCESSIBLE_TEXT_PROPERTY instead. Firing both will result in sending unneeded property change events to assistive technologies.

For a detailed description of firing these property changes see section 6.2.4 Property Change Notification.



6.2.2 Parent/Child information
The way assistive technologies gather and organize information about your program is by assembling the list of components making up your application from the parent/child hierarchy. A simplistic example of this is when an assistive technology program listens for a focus change. When this occurs, the assistive technology program would go up the parent tree, from the focused component, until it reaches the window frame. It then recursively enumerates all the visible and showing children making up the active program. The assistive technology program now has a list of all the components making up your application and it can organize them based on its representation of the screen. At this point, the assistive technology communicates with them individually through the Accessibility API. This is why it is important that you provide parent/child information for each of your objects.

Note: Many GUI components act as a proxy for their children. In this case, their children are specialized objects responsible for their rendering and all focus management and input is managed by the proxying parent component. As a result, these children cannot be enumerated using the standard JDK methods for enumerating children. To facilitate assistive technology access to your program it is important that you support the methods, listed in this section, for all GUI objects and that all GUI objects implement the Accessibility API. An example where a parent proxies for its children is the way a JFC JList component treats its list entries. Each entry is treated as an accessible child who is told to draw by the JList component.

This section describes the following methods:

Important:
Whenever an Accessible object adds or removes an AccessibleChild, it must fire an ACCESSIBLE_CHILD_PROPERTY change to notify an assistive technology when its Accessible children change. Furthermore, this information should be reflected in the AccessibleChildCount.


6.2.2.1 getAccessibleChild(n)
This function returns the nth immediate child that implements the Accessibility API.


6.2.2.2 getAccessibleChildCount()
getAccessibleChildCount returns the number of immediate children that implement the Accessibility API. If you had a list box with ten entries, you would have 10 accessible children.

6.2.2.3 getAccessibleParent()
AccessibleParent returns the parent object that implements the Accessibility API. If there is no Accessible parent this method should return null.


6.2.2.4 getAccessibleIndexInParent()
When implementing AccessibleContext, this method returns the index of the AccessibleContext in its parent's Accessible child list. An example is a list box. If your list box had 10 entries, the number of accessible children would be 10. The nth child of the list box would be the nth entry in the list box. When assistive technology queries the nth entry in the list box, the result should support the Accessibility API. When assistive technology asks for the AccessibleParent of the entry from its AccessibleContext, it should return the list box object.



6.2.3 Role and state information
Role and state information describes the unique features of an object. By defining an object's role you describe the object's generic function in the system independent of its class name. The object's role enables assistive technology to decide how to present the object and to tell the user what it is.

The state naturally describes the current state of the object. For example, if the object is a check box it may be in the "checked" state or if it is a text area it is important to know if it is in the "editable" state.

This section describes the following:


6.2.3.1 AccessibleRole
AccessibleRole is the basic role of an application component. The role describes the generic function of the component; such as "push button," "table," or "list."

In older windowing systems like Windows 3.x or Presentation Manager, assistive technology programs used to use the class name to provide the role information about a GUI object. This was often unusable because applications would subclass standard windowing components and give them obscure class names. By providing standard role information you can provide the user with familiar information about the object's function within your program. For example, if you sub-classed an AWT button class with a class called foobarpbutton, the role would still be AccessibleRole.PUSH_BUTTON.

This class provides a set of strongly typed constants enumerating common object roles. AccessibleRole is a descendant of AccessibleBundle See section 6.2.5.1 AccessibleBundle. Therefore, it inherits the toDisplayString(Locale) method allowing you to obtain the localized string based on a locale-independent key from a predefined AccessibleBundle containing the keys defined in this class.

A public constructor for this class has been purposely omitted and applications should use one of the constants from this class. If the constants in this class are not sufficient to describe the role of an object, a subclass should be generated from this class and it should provide constants in a similar manner.

The generic enumerated roles are largely based on classes provided in JFC's rich GUI component class library.

Table 13 contains a pre-defined set of AccessibleRoles and their brief descriptions:

Pre-Defined AccessibleRoles
AccessibleRole Description
ALERT An object used to alert the user, such as a warning message.
AWT_COMPONENT An AWT component, but nothing else is known about it.
CANVAS A Canvas object represents a blank rectangular area of the screen onto which to draw or from which the application can trap input events from the user. This is based on the AWT Canvas component.
Note: supported in Java 2 SDK 1.3 or later
CHECK_BOX A check box. In the generic sense, this is a choice that can be checked or unchecked and provides a separate indication of the current state.
COLOR_CHOOSER A dialog that only lets you choose a color.
Note: supported in Java 2 SDK 1.3 or later
COLUMN_HEADER The header for a column of data.
COMBO_BOX A combination of a text field and drop-down list.
DESKTOP_ICON An iconified internal frame in a DESKTOP_PANE.
DESKTOP_PANE This is normally used as the parent of internal frames to provide a pluggable desktop manager object to the internal frames or iconified internal frames.
DIALOG A dialog box.
DIRECTORY_PANE A generic container providing directory information.
FILE_CHOOSER A dialog box used to choose a file.
FILLER An object that fills up space in a user interface.
FRAME A window frame.
GLASS_PANE A transparent window container which does not contain a frame.
ICON A small fixed size picture, typically used to decorate components.
Note: supported in Java 2 SDK 1.3 or later
INTERNAL_FRAME A frame-like object that is clipped by a desktop pane or parent pane window. A familiar example would be the program group windows in the Windows 3.1tm Program Manager or an individual document frame in a multi-document application such as a word processor.
LABEL A display object used to show a short text string, an image, or both. A label does not react to input events.
LAYERED_PANE A specialized pane that allows its children to be drawn in layers, providing a form of stacking order. For example, you may have a stack of child Container windows where the layered pane would determine which layer in the stack would be drawn in the appropriate Z-order.
LIST An object containing a list of selectable items. This usually describes a list box.
LIST_ITEM An object that presents a list element.
Note: supported in Java 2 SDK 1.3 or later
MENU An object, that when selected, displays a vertical pop-up list of menu items.
MENU_BAR The top-level container of menu and menu items.
MENU_ITEM A Menu or Menu Bar entry.
OPTION_PANE A specialized pane whose primary use is inside a dialog.
PAGE_TAB A Tab in a Page Tab List.
PAGE_TAB_LIST A set of selectable notebook tabs. Each tab contains a graphic and/or text name.
PANEL A rectangular area in an application which controls the layout of its children.
PASSWORD_TEXT A text object used for passwords, or other places where the text contents are not shown widely to the user.
POPUP_MENU A modal list of menus, which can be popped to the highest Z-order of visibility.
PROGRESS_BAR An object which graphically depicts the progress of a desired operation in the form of a bar scale. For example, it would be used to the progress of an install program.
PUSH_BUTTON A simple push button.
RADIO_BUTTON An implementation of a radio button -- an item that can be selected or deselected, and which displays its state to the user.
ROOT_PANE This is a top-level container pane for an application whose definition is derived from the JFC root pane.
ROW_HEADER An object that defines a row label (like in a table or spreadsheet).
SCROLL_BAR A horizontal or vertical scroll bar used to scroll an area on the screen.
SCROLL_PANE A pane that allows horizontal or vertical scrolling of its contents through the use of optional horizontal and vertical scroll bars.
SEPARATOR An implementation of a Menu Separator.
SLIDER A control that lets the user select a value from a bounded interval.
SPLIT_PANE A glass pane divided into two equal areas with a separator.
SWING_COMPONENT A JFC component having no user-definable role.
TABLE A table of data consisting of row and column information.
TEXT A document or edit field containing only text.
TOGGLE_BUTTON A generic button which can be either locked on or off.
TOOL_BAR A bar of selectable button objects, each providing a unique function.
TOOL_TIP Text description.
TREE An object displaying a visible tree representation such as a file directory.
UNKNOWN An object having either no user-definable or provided AccessibleRole.
VIEWPORT An object which maintains the state of a screen transfer area from an off screen bitmap like the Xtm Windows System backing store.
WINDOW An object that is responsible for receiving user input from the native windowing system. This is usually a JDK window.

Table 13: Pre-Defined AccessibleRoles

Although it is possible to subclass AccessibleRole and extend it to add new objects, it is preferable that you use one of the predefined roles when supporting the AccessibleContext method getAccessibleRole and augment the role though the accessible description. If you need additional standard roles, you should submit your request to access@sun.com to augment the standard AccessibleRole list. For example, your program may use a thermometer object to display the temperature. An option would be to use the existing PROGRESS_BAR accessible role and set the AccessibleDescription to "Thermometer."


6.2.3.2 AccessibleState
Use AccessibleState to describe a particular state of a component. The actual state of the component is defined as an AccessibleStateSet, which is a collection of an object's AccessibleStates.

The constants in this class present a strongly typed enumeration of common object states. AccessibleState is a descendant of AccessibleBundle. See section 6.2.5.1 AccessibleBundle. Therefore, it inherits the toDisplayString(Locale) method. This allows you to obtain the localized string, based on a locale-independent key, from a predefined AccessibleBundle containing the keys defined in this class.

A public constructor for this class has been purposely omitted, and applications should use one of the constants from this class. If the constants in this class are not sufficient, create a subclass from this class, and provide constants in a similar manner.

The generic enumerated states that this class provides are largely based on classes provided in JFC's rich GUI component class library.

Pre-Defined AccessibleStates
AccessibleState Description
ACTIVE Indicates whether an application is active. Example: Top-level frames use ACTIVE to indicate that it or one of its children has focus. The ACTIVE state is also set for Accessible descendents found in objects, such as a list when a child is the current Active descendent. See ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY.
ARMED Indicates that the user input is currently directed to that object and it is "armed for selection." Example: a highlighted menu item or a pressed push button.
BUSY Indicates if the object is currently busy and it is not responding to user input. Example: an application displays the hourglass.
CHECKED Indicates whether an object is in the checked state. Example: radio buttons and check boxes.
COLLAPSED Indicates this object is collapsed, such as when a tree branch is collapsed.
EDITABLE Indicates whether a text or document area is in an editable state.
ENABLED Indicates if an object is enabled. An object that normally responds to user input and can be set to not respond to user input (disabled state) would support this state. Example: a menu item - this state would be removed if it was grayed out.
EXPANDABLE Indicates this object allows progressive disclosure of its children.
EXPANDED Indicates this object is expanded.
FOCUSABLE Indicates whether the object is capable of receiving input focus.
FOCUSED Indicates whether the current object has input focus.
HORIZONTAL Indicates whether the object is in a horizontal state. Examples: scroll bars, sliders, progress bars, and scroll panes.
ICONIFIED Indicates whether the frame object is in an iconified or minimized state.
MODAL A window's state such that when an application window is "modal," the user cannot switch to another window within the application until after the window is destroyed or set to non-modal. Example: dialog boxes.
MULTI_LINE Indicates this (text) object can contain multiple lines of text, such as a multi-line edit field.
MULTISELECTABLE Indicates whether the given container is in a state supporting selection of more than one of its Accessible Children. Example: a list box.
OPAQUE Indicates whether a component paints every pixel within its rectangular region. A non-opaque component paints only some of its pixels, allowing the pixels underneath it to "show through." A component that does not fully paint its pixels therefore provides a degree of transparency.
PRESSED Indicates whether the object is currently depressed. Example: a push button.
RESIZABLE Indicates whether the object is resizable. Example: a frame uses this.
SELECTABLE Indicates if the object is selectable. Example: a toggle button.
SELECTED Indicates if the object is currently selected. Example: a selected check box menu item.
SHOWING Equivalent to the isShowing state in the JDK component - indicates if the object is showing on the screen. Example: a pop-up menu. When it has not been popped up it is visible but not showing.
SINGLE_LINE Indicates this (text) object can contain only a single line of text, such as single-line edit field.
TRANSIENT Indicates that this object is transient. This also notifies an assistive technology to not add listeners to the object because it will never generate events. Examples of transient objects are those found in collective Swing components, such as lists, tables, and trees. In these cases, Accessible children are created by a single cell-renderer that creates transient accessible children for an assistive technology based on the child index.

When you create an Accessible object in response to a requested proxied "Accessible" child, and this child is only created to fulfill the request, you should include AccessibleState.TRANSIENT in the child's AccessibleStateSet. This tells the assistive technology to monitor its proxying parent for changes to its children, rather than the transient child. In the case of JFC, this is often done for cell renderer objects.

VERTICAL Indicates whether the object is in a vertical state. Examples: scroll bars, sliders, progress bars, and scroll panes.
VISIBLE Equivalent to the isVisible state in the JDK component - indicates if the object will be visible when "shown" on the screen.An object needs to be visible and showing to be displayed.

Table 14: Pre-Defined AccessibleStates

Note: Whenever a change in AccessibleState occurs in an object, you need to fire an appropriate property change in AccessibleContext.

AccessibleStateSet: AccessibleStateSet maintains a collection of the AccessibleState settings for a given Accessible object. It has methods for you to add or remove AccessibleStates to its collection. An assistive technology would query the current AccessibleStateSet to determine the state of an object.

It is important that you maintain the set of state information for each Accessible object. Examples of state information are "checked" for a check box, or "vertical" for a scroll bar. See the previous section for a more detailed description of the AccessibleState.

The AccessibleStateSet class supports the methods listed in Table 15.

AccessibleStateSet Methods
Method Description
add(AccessibleState) Adds a new state to the current state set if it is not already present.
addAll(AccessibleState[]) Adds an array of Accessible states to the existing state set.
clear() Removes all the states from the current state set.
contains(AccessibleState) Determines if the AccessibleState passed is in the state set.
remove(AccessibleState) Removes a state from the current state set.
toArray() Returns the current state set as an array of AccessibleState.
toString() Returns a localized String representing the current state set using the default locale.

Table 15: AccessibleStateSet Methods

To modify the state set, check to see if the AccessibleStateSet contains the AccessibleState. Then, add or remove the AccessibleState, as needed.

Important:
Whenever you add or remove states to the AccessibleStateSet, you must fire an ACCESSIBLE_STATE_PROPERTY change event in AccessibleContext, as described in section 6.2.4. Property Change Notification.



6.2.4 Property change notification
The Java Bean APIs ( Java's software component model ) support a common object-oriented feature called properties. Properties are specific attributes of an object. The Java bean API has added the ability for an object to notify registered listeners when one of its properties change. The Accessibility API has incorporated this feature to enable assistive technology to be notified when specific property data changes. This enables assistive technology programs to passively monitor your application. Property change notification is handled through your implementation of AccessibleContext. Assistive technology programs will register listeners with the AccessibleContext object you have written to monitor accessibility specific information. These familiar Java bean methods are used to manage property changes in the AccessibleContext:

firePropertyChange(String propertyName, Object oldValue,
Object newValue):

Fires the specified property change (propertyName) with the old
and new values to registered listeners.

addPropertyChangeListener(PropertyChangeListener listener):

Adds an object supporting the PropertyChangeListener
interface described in the Java bean package.

removePropertyChangeListener(PropertyChangeListener
listener):

Removes an object supporting the PropertyChangeListener interface
described in the Java bean package.

The following is a list of 17 Accessibility properties you must support:

  1. ACCESSIBLE_DESCRIPTION_PROPERTY: When a change in the accessible description occurs, you must fire this property change event to registered listeners. To fire this property change event, the following mechanism is required, where oldDescription and newDescription are of class String:
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_DESCRIPTION_PROPERTY,
    oldDescription, 
    newDescription);
      
  2. ACCESSIBLE_name_PROPERTY: When a change in the accessible name occurs, you must fire this property change event to registered listeners, where oldName and newName are of class String.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_name_PROPERTY, oldName, 
    newName);
    
  3. ACCESSIBLE_SELECTION_PROPERTY: When a change occurs to your AccessibleSelection collection object, you need to fire this property change event to registered listeners. Selection change event data, when implemented, usually involves complex collection objects and, as such, it is both inefficient and unnecessary for you to figure old and new values when firing the property change. To fire a selection property change, the following mechanism is required where selectedText is a string:
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY, 
    null, 
    selectedText);

    If the selection change involves a collection of selected items, usethe following mechanism:

    firePropertyChange(
    AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY,
    new Boolean(false), 
    new Boolean(true));
          

    Where a collection is involved, the assistive technology acquires the selection information from the AccessibleSelection information of the component that is generating the property change event.

  4. ACCESSIBLE_STATE_PROPERTY: When a change occurs to your AccessibleStateSet collection object, you need to fire this property change event to registered listeners. AccessibleState changes are basically State flag toggles. When firing this property value of the old or new value will be null if the respective value is off or the AccessibleState constant if the value is on. For example, if an entry field was switched to the Editable state, the property firing in the AccessibleContext should be implemented as follows:
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
    null,
    AccessibleState.EDITABLE);
          
  5. ACCESSIBLE_TEXT_PROPERTY: When a change occurs to the data in your AccessibleText object, you need to fire this property change event to registered listeners. Whenever the object making up your document change (text is replaced, added, or deleted, objects are embedded, etc.) you would fire this property change. You would not do so for attributes of the data. For example, changing the font would not result in a property change event.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_TEXT_PROPERTY,
    new Boolean(false), 
    new Boolean(true));
          
  6. ACCESSIBLE_VALUE_PROPERTY: When a change occurs to the current value in your AccessibleValue object, you need to fire this property change event to registered listeners. AccessibleValues are set for objects that support a value and value range setting components such as scroll bars, sliders, and progress bars.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_VALUE_PROPERTY,
    new Integer(oldValue), 
    new Integer(newValue));
          
  7. ACCESSIBLE_VISIBLE_DATA_PROPERTY: When a change occurs to the data in the visible portion of your object, you need to fire this property change event to registered listeners. This applies to the text changing in your checkbox, a change in your list box's data, and so on. This is an extremely important property, because many assistive technologies store the visible data information in their own data structures, to give their own "look and feel" of your program. For example, the Access Engine technology in IBM's SVK sorts its information in row/column format.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,
    new Boolean(false),
    new Boolean(true));
          

    This property change applies to all components except those that implement AccessibleText.

  8. ACCESSIBLE_CARET_PROPERTY: When a caret change occurs in Accessible objects supporting AccessibleText, this property should be fired when the caret changes position. The position old and new values passed should be an Integer object containing the old and new values for the character index for the caret.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_CARET_PROPERTY,
    new Integer(oldposition),
    new Integer(newposition));
    
  9. ACCESSIBLE_CHILD_PROPERTY: When a child is added or removed from an Accessible object, this Accessible object should fire property change. If an Accessible object is being added, the old value is null and the new value is the Accessible child. If an Accessible child is being removed, the old value is the Accessible child and the new value is null.

    Adding:

     
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_CHILD_PROPERTY,
    null,
    (Accessible) childadded); 
    

    Removing:

            
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_CHILD_PROPERTY,
    (Accessible) childremoved,
    null);
          
  10. ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY: A constant used to determine when the active descendant of a component has changed. The active descendant is used for objects such as list, tree, tab pane, and table, which might have transient children. When the active descendant has changed, the old value of the property change event is the Accessible representing the previous active child. The new value is the Accessible representing the current active child.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_ACTIVE_DESCENDANT
    _PROPERTY,
    (Accessible) previous active child,
    (Accessible) current active child);
    

    Important:
    In objects like lists, trees, and other complex objects, it is often possible to select multiple items. In these cases, theitems are often represented as highlighted text. It is either the currently Active child or the last one that had the user's focus that is considered the active descendant. The AccessibleState of this descendant should have its AccessibleStateSet include AccessibleState.ACTIVE. This is represented, graphically, on many systems as the moving dotted box around the list element you are currently operating on.

  11. ACCESSIBLE_TABLE_CAPTION_CHANGED_PROPERTY: Supported in Java 2 SDK 1.3 or later. When a table caption changes this property should be fired by the Accessible object to indicate that the table caption has changed. The old value in the PropertyChangeEvent will be an Accessible object representing the previous table caption and the new value will be an Accessible object representing the new table caption.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_TABLE_CAPTION
    _CHANGED_PROPERTY,
    (Accessible) previous caption,
    (Accessible) current caption);
    
  12. ACCESSIBLE_TABLE_COLUMN_DESCRIPTION
    _CHANGED_PROPERTY:
    Supported in Java 2 SDK 1.3 or later. When a table column description is changed this property should be fired by an Accessible component to indicate that the column description has changed. The old value in the PropertyChangeEvent will be null and the new value will be an Integer representing the column index.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_TABLE_COLUMN
    _DESCRIPTION_CHANGED_PROPERTY,
    null,
    new Integer(columnNumber));
    
  13. ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED_PROPERTY: Supported in Java 2 SDK 1.3 or later. When a table column header is changed this property should be fired by an Accessible component to indicate that the column header has changed. The old value in the PropertyChangeEvent will be null and the new value will be an AccessibleTableModelChange object representing the header change.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_TABLE_COLUMN
    _HEADER_CHANGED_PROPERTY,
    null,
    (AccessibleTableModelChange) ChangeToTableModel);
    
  14. ACCESSIBLE_TABLE_MODEL_CHANGED_PROPERTY: Supported in Java 2 SDK 1.3 or later. When the data stored in a table is changed this property should be fired by the Accessible component to indicate that table data has changed. The old value in the PropertyChangeEvent will be null and the new value will be an AccessibleTableModelChange object representing the table change.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_TABLE_MODEL
    _CHANGED_PROPERTY,
    null,
    (AccessibleTableModelChange) ChangeToTableModel);
    
  15. ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED
    _PROPERTY:
    Supported in Java 2 SDK 1.3 or later. When a table row description is changed this property should be fired by an Accessible component to indicate that the row description has changed. The old value in the PropertyChangeEvent will be null and the new value will be an Integer representing the row index.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_TABLE_ROW
    _DESCRIPTION_CHANGED_PROPERTY,
    null,
    new Integer(rowIndex));
    
  16. ACCESSIBLE_TABLE_ROW_HEADER_CHANGED_PROPERTY: Supported in Java 2 SDK 1.3 or later. When a table row header is changed this property should be fired by an Accessible component to indicate that the row header has changed. The old value in the PropertyChangeEvent will be null and the new value will be an AccessibleTableModelChange object representing the header change.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_TABLE_ROW
    _HEADER_CHANGED_PROPERTY,
    null,
    (AccessibleTableModelChange) ChangeToTableModel);
    
  17. ACCESSIBLE_TABLE_SUMMARY_CHANGED_PROPERTY: Supported in Java 2 SDK 1.3 or later. When a table summary is changed this property should be fired by an Accessible component to indicate that the summary has changed. The old value in the PropertyChangeEvent will be an Accessible representing the previous AccessibleTable summary and the new value will be an Accessible object representing the new table summary.
    firePropertyChange(
    AccessibleContext.ACCESSIBLE_TABLE_SUMMARY
    _CHANGED_PROPERTY,
    (Accessible) oldSummary,
    (Accessible) newSummary);
    


6.2.5 National language information

This section describes the following two class files, which come with the Accessibility API to allow support of localized Role and State information:

Normally, you should not need to extend or modify these files. You should use the standard Accessible Role and State definitions defined in the Accessibility API. If however, you need to have additional Roles or States, consider the following:

We strongly recommend:


6.2.5.1 AccessibleBundle
As stated earlier, AccessibleRole and AccessibleState are descendants of AccessibleBundle. AccessibleBundle supports the methods listed in Table 16.

The source for this class is in the javax.accessibility package source included in the JFC.

AccessibleBundle Methods
Method Description
toDisplayString() Returns the localized String describing the key using the default locale.
toDisplayString(Locale) Obtains the key as a localized string. See the JDK for a detailed description of Locale.
toDisplayString(String ResourceBundleName, Locale) Obtains the key as a localized string, based on the fully-qualified resource bundle file name and the Locale.
toString() Gets the localized string describing the key using the default locale.

Table 16: AccessibleBundle Methods


6.2.5.2 AccessibleResourceBundle
This contains all the key/localized (translated) string information for each AccessibleRole and AccessibleState. The source for AccessibleResourceBundle is located in the javax.accessibility package source included in the JFC.



6.2.6 AccessibleAction
It is often difficult for people with disabilities to navigate an application. For example, it is difficult to impossible for blind computer users to use a mouse. It is also difficult for a sighted user to determine the hot spots on an image map found on a web page.

Voice navigation systems, initially used by mobility impaired users, convert voice commands to actions. The right way to implement voice control of a GUI, is not by simulating keyboard and mouse actions because there is no visual indication of the actions available, and the simulation can be difficult.

For these reasons, the AccessibleAction object was created. AccessibleAction contains a collection of description/action entries to allow assistive technologies to select and perform a given object's action(s).

Note: For objects that have no action, like a label or title bar, AccessibleContext would return null for the AccessibleAction.

The AccessibleAction interface you would implement is described in Table 17.

AccessibleAction Methods
Method Description
doAccessibleAction(int) Performs the specified action on the object.
getAccessibleActionCount() Returns the number of accessible actions available in this object. If there is more than one, the first one is the "default" action.
getAccessibleActionDescription(int) Returns a description of the specified action of the object.

Table 17: AccessibleAction Methods

An example of AccessibleAction for a tree element might be:


Important:
If you have a component or component element that can beactivated by the mouse or keyboard, you must provide an AccessibleActionfor it, otherwise it is not accessible.



6.2.7 AccessibleTable
This Interface, supported in Java 2 SDK 1.3 or later, is used to describe a user-interface component that presents data in a two-dimensional table format. This interface was designed to support W3C Web Content Accessibility Guidelines for accessible HTML tables as well as common 2-dimensional data representations in standard software applications such as spreadsheets. Before this interface was created, no standard interface for tables was provided and assistive technologies required intimate knowledge of a table's API to provide more comprehensive access to it. Therefore, it is important that you implement this interface on any 2-dimensional table representation of data in your application. If you are using SDK 1.3 and a JTable, this interface is already implemented for you. Table 17A describes the methods for Interface AccessibleTable.

Interface AccessibleTable
Method Description
getAccessibleAt(int r, int c) Returns the child at a specified row and column in the table. This child must implement interface Accessible.
getAccessibleCaption() returns the table Caption. The caption must implement interface Accessible
getAccessibleColumnCount() Returns the number of columns in the table in the form of an int.
getAccessibleColumnDescription(int c) Returns the description text of the specified column in the table. Column numbers are zero based.
getAccessibleColumnExtentAt(int r, int c) Returns the number of columns occupied by the Accessible at a specified row and column in the table. Rows and columns are zero based.
getAccessibleColumnHeader() Returns an AccessibleTable representing the column headers
setAccessibleColumnHeader(AccessibleTable at) Sets the column headers in the form of an AccessibleTable
getAccessibleRowCount() Returns the number of rows in the table.
getAccessibleRowDescription(int row) Gets the description for a given row in the form of an Accessible object. Row numbers are zero based.
getAccessibleRowExtentAt(int r, int c) The number of rows occupied by the Accessible at a given specified (row, column). This is also known as the row span.
getAccessibleRowHeader() Returns an AccessibleTable representing the row headers.
getAccessibleSummary() Returns an Accessible representing the table summary.
getSelectedAccessibleColumns() Returns an array of int representing the list of columns selected. Each column number is zero based.
getSelectedAccessibleColumns() Returns an array of int representing the list of columns selected. Each column number is zero based.
getSelectedAccessibleRows() Returns an array of int representing the list of rows selected. Each row number is zero based.
isAccessibleColumnSelected(int c) Returns a boolean to indicate if the specified column is selected. Column numbers are zero based.
isAccessibleRowSelected(int r) Returns a boolean to indicate if the specified row is selected. Row numbers are zero based.
isAccessibleSelected(int r, int c) Returns a boolean to indicate if the Accessible object at the specified row and column is selected. Row and column numbers are zero based.
setAccessibleCaption(Accessible a) Sets the caption in the form of an Accessible object.
setAccessibleColumnDescription(int c, Accessible a) Sets the Description for a given column. Column numbers are zero based. The description is in the form of an Accessible object.
setAccessibleColumnHeader(AccessibleTable table) Sets the column headers in the form of an AccessibleTable. This allows you to change all the column headers and once.
setAccessibleRowDescription(int r, Accessible a) Sets the Description for a given row. Row numbers are zero based. The description is in the form of an Accessible object.
setAccessibleRowHeader(AccessibleTable table) Sets the row headers in the form of an AccessibleTable. This allows you to change all the row headers and once.
setAccessibleSummary(Accessible a) Sets the summary in the form of an Accessible object.

Table 17A: Interface AccessibleTable


6.2.7.1 AccessibleTable events
Accessible tables, like accessible text objects can change dynamically. In order for you to write your application so that an assistive technology can adapt to it, you will need to notify an assistive technology of these changes. To do this, you will need to support the following change event notifications in your accessible table component: For row and column description changes, fire the following events in your AccessibleContext implementation:

For row and column header changes, fire the following events in your AccessibleContext implementation:

For table caption changes, fire the ACCESSIBLE_TABLE_CAPTION_CHANGED_PROPERTY.

For table summary changes, fire the ACCESSIBLE_TABLE_SUMMARY_CHANGED_PROPERTY.

The ACCESSIBLE_TABLE_MODEL_CHANGED_PROPERTY should only be fired when the actual table data changes, either through an update, delete, or insertion to the table model. This event should not be fired with any of the other table change events as this would negatively impact performance. Header and table data provide change information through an AccessibleTableModelChange interface described in Table 17B. Using this mechanism, your accessible table will indicate whether the information changed was caused by an update, deletion, or insertion with the respective start and end row and column information.

For table model changes that are visible to the user, you should also fire the ACCESSIBLE_VISIBLE_DATA_PROPERTY. Assistive technologies, for performance reasons, need to target what they present to the visible area of the screen. By indicating that the data changing is visible or not, you successfully allow ATs to improve performance.

AccessibleSelection does not fit well into the AccessibleTable interface. An appropriate way to provide selection information is set the state of each accessible child that is selected to AccessibleState.SELECTED and to fire ACCESSIBLE_STATE_PROPERTY events on behalf of all the accessible children in your table component when the selected state of any child changes. It will be up to the assistive technology to ask each accessible cell what its state is. A cell AccessibleStateSet containing AccessibleState.SELECTED indicates the child is selected to an assistive technology.

In addition to selecting multiple rows and columns you may also support a currently active cell. Active cells are supported in JTable by using the arrow keys to navigate from cell to cell. Whenever the currently active cell changes you must also fire a ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY event.

AccessibleTableModelChange
Property Description
Pre-Defined Types:
DELETE Identifies the deletion of rows and/or columns.
INSERT Identifies the insertion of rows and/or columns.
UPDATE Identifies a change to existing data.
Methods:
getFirstColumn() Returns the first column that changed.
getFirstRow() Returns the first column that changed.
getLastColumn() Returns the last column that changed.
getLastRow() Returns the last row that changed.
getType() Gets the event type. The should be one of the pre-defined events in this interface.

Table 17B AccessibleTableModelChange


6.2.8 AccessibleRelation and AccessibleRelationSet
Class AccessibleRelation, supported in Java 2 SDK 1.3 or later, describes a relationship between the object that implements the AccessibleRelation and one or more other objects. The actual relations that an object has with other objects are defined as an AccessibleRelationSet, which is a composed set of AccessibleRelations.

This is one of the most powerful additions to the Java Accessibility API in Java 1.3. It provides a engineered mechanism that allows the components to express true semantics. Prior to Java 1.3, you would need to perform JFC specific associations such as JLabel's setLabelFor method. This not only limited you to JFC but it also limited the scope of relationships you were able to define.

Table 17D shows AccessibleRelation properties, events, methods, and constructors.

AccessibleRelation
Property Description
Pre-Defined Relationships:
CONTROLLED_BY Indicates an object is controlled by one or more target objects.
CONTROLLER_FOR Indicates an object is a controller for one or more target objects.
LABEL_FOR Indicates an object is a label for one or more target objects.
LABELED_BY Indicates an object is a labeled by one or more target objects.
MEMBER_OF Indicates an object is a member of a group of one or more target objects.
Property Change Events:
CONTROLLED_BY_PROPERTY Identifies that the target object that is doing the controlling has changed.
CONTROLLER_FOR_PROPERTY Identifies that the controller for the target object has changed.
LABEL_FOR_PROPERTY Identifies that the target group for the label has changed.
LABELED_BY_PROPERTY Identifies that the objects that are doing the labeling have changed.
MEMBER_OF_PROPERTY Identifies that group membership has changed.
Methods:
getKey() Returns the key for this relation in the form of a String.
getTarget() Returns an array containing the target objects for this relation.
setTarget(Object target) Sets the target object for this relation.
setTarget(Object[] targets) Sets the target objects for this relation.
Constructors:
AccessibleRelation(String key) Create a new AccessibleRelation using the given locale independent key.
AccessibleRelation(String key, Object target) Creates a new AccessibleRelation using the given locale independent key.
AccessibleRelation(String key, Object[] targets) Creates a new AccessibleRelation using the given locale independent key.

Table 17D: AccessibleRelation

The toDisplayString method allows you to obtain the localized string for a locale independent key from a predefined ResourceBundle for the keys defined in this class.

The constants in this class present a strongly typed enumeration of common object roles. A public constructor for this class has been purposely omitted and applications should use one of the constants from this class. If the constants in this class are not sufficient to describe the role of an object, a subclass should be generated from this class and it should provide constants in a similar manner.

The Java Accessibility API also allows for a collection of AccessibleRelations. When implementing accessible context, provide this collection through the collection class AccessibleRelationSet which was also introduced in Java SDK 1.3. Table 17E shows the AccessibleRelationSet class methods and constructors.

AccessibleRelationSet
Property Description
Methods:
add(AccessibleRelation relation) Adds a new relation to the current relation set if it is not already present.
addAll(AccessibleRelation[] relation) Adds all of the relations to the existing relation set.
clear() Removes all the relations from the current relation set.
contains(String key) Returns whether the relation set contains a relation that matches the specified key.
get(String key) Returns the AccessibleRelation that matches the specified key.
remove(AccessibleRelation relation) Removes the AccessibleRelation from the relation set.
size() Returns the number of relations in the relation set.
toArray() Returns the current relation set as an array of AccessibleRelations
toString() Creates a localized String representing all the relations in the set using the default locale.
Constructors:
AccessibleRelationSet() Create a new AccessibleRelation using the given locale independent key.
AccessibleRelationSet(AccessibleRelation[] relations) Creates a new relation with the initial set of relations contained in the array of relations passed in.

Table 17E: AccessibleRelationSet


6.2.9 AccessibleIcon
AccessibleIcon, supported in Java 2 SDK 1.3 or later should be implemented on any Accessible object which includes an icon, if the information is not already provide in text and the text is accessible through the Accessibility API. Icons are often used to provide additional information to the user as well as to add visual appeal to the program. An example is to indicating a warning through the use of an exclamation mark icon in a message dialog. Table 17F show the AccessibleIcon class interface.

AccessibleIcon
AccessibleIcon Description
Methods:
getAccessibleIconDescription() Gets the description of the icon in the form of a String.
getAccessibleIconHeight() Returns the height of the icon in the form of an int.
getAccessibleIconWidth() Returns the width of the icon in the form of an int.
setAccessibleIconDescription(String description) Sets the icon's description.

Table 17F: AccessibleIcon


6.2.10 AccessibleHypertext
Many applications implement hypertext-type interfaces to create richly linked documents. Some of the most fundamental applications for text are help systems. In a help system, a specific piece of text or an image is visibly augmented to indicate that if you select that area, you will access more information about that topic. This concept is expanded to the Web, where images and text in web pages link you to documents on either your machine or another machine.

AccessibleHypertext is a Java interface extension to AccessibleText that enables you to provide a document interface that facilitates access to hyperlinks. If you have an application component that contains Hypertext, you must implement AccessibleHypertext on that component. Because AccessibleHypertext extends AccessibleText, only the added methods for AccessibleHypertext are described in Table 18.

AccessibleHypertext Methods
Method Description
getLink(int) Returns the nth AccessibleHyperlink of this hypertext document.
getLinkCount() Returns the number of links within this document.
getLinkIndex(int) Returns the index into an internally stored array of AccessibleHyperlink objects based on the AccessibleText document character index. If no link exists at this character index, the result returned is -1.

Table 18: AccessibleHypertext Methods

By providing the AccessibilityHypertext interface, you are enabling a disabled user to:

The accessible hyperlink that this interface returns is described in section 6.2.11 AccessibleHyperlink


6.2.11 AccessibleHyperlink
An AccessibleHyperlink defines a link or collection of links. It is an abstract Java class that extends AccessibleAction . Because it extends AccessibleAction , it provides a mechanism for describing each link element and how to activate the element. Like AccessibleAction , each link is referenced through a zero-based index (0 through n-1). This is particularly important for image maps found on web pages. On a web page, an image map might contain clickable hot areas that act as hyperlinks to other documents. AccessibleHyperlink is described in Table 19.

AccessibleHyperlink Methods
Method Description
isValid() This indicates whether the link is still valid with respect to the AccessibleHypertext it references. This method returns true if the link is valid and false if it is not. A link is invalid (return false) if the underlying text changed, such as when a link is followed.
getAccessible ActionCount() Returns the number of accessible actions available in this link. For HTML image maps, this equals the number of links for a given image map. If there is more than one, the first is not considered the "default" action. Typically, links have one Accessible action.
doAccessible Action(int) Performs the action specifed by index passed for this link.
getAccessible ActionDescription(int) Returns a String description for the indexed action. The description should be set to the anchoring text. In the case of an HTML link like <A href=http://www.ibm.com/sns> IBM Human Ability and Accessibility Center Home Page</A>, the value returned should be "IBM Human Ability and Accessibility Center Home Page". If this were an image, for example, <a href=http://www.ibm.com /sns/rich.html> <img src http://www.ibm.com/sns /images/Schwerdtfeger, Rsmalloval.jpg alt="a picture of Rich"> </A>, the result returned would be the ALT text "a picture of Rich".
getAccessible ActionObject(int) Gets an object that represents the link action for the given link. Using the example from the previous method for a text link, you would want to return new java.net.URL (http://www.ibm.com/sns).
getAccessible ActionAchor() Returns an object that represents the link anchor, as appropriate for that link. For example, from the image map example in getAccessibleDescription, this would return ImageIcon(phillricho.gif, "Phill and Rich's Picture").
getStartIndex() Gets the character index within the hypertext document at which this link begins.
getStopIndex() Gets the character index within the hypertext document at which this link ends.

Table 19: AccessibleHyperlink Methods