1998 Conference Proceedings

Go back to article. 

[opened accessibility door]

IBM Guidelines for Writing Accessible Applications Using 100% Pure Javatm

Version 1.0
Copyright IBM Corporation 1998
The most current version of these guidelines is maintained at:

February 15, 1998

Document Owner:
Richard S. Schwerdtfeger
Lead Architect, IBM Special Needs Systems
e-mail: schwer@us.ibm.com

Richard S. Schwerdtfeger, IBM

Technical Editors:
Phill Jenkins, IBM
Frances Hayden, IBM
Dr. James W. Thatcher, IBM

Table of Contents


The Java Accessibility API is a broad effort that includes contributions from a number of groups. We in the IBM Special Needs Systems  group would like to thank the people in the following groups for contributing to and supporting the Java Accessibility API effort:

I would like to especially thank Earl Johnson for driving the Javatm accessibility effort at Sun and for reviewing these guidelines. There are few companies, like IBM, who have so strongly supported people with special needs. Sun Microsystems is one of those companies. Earl Johnson is the driving force behind Sun's accessibility efforts. Thank you Earl!



All statements regarding future intent are subject to change or withdrawal without notice and represent goals and objectives only.

Information in this document about non-IBM products was obtained from the suppliers of these products, published announcement material, or other publicly available sources.

The information contained in this document represents the current views of IBM on the issues discussed as of date of publication. IBM cannot guarantee the accuracy of any information after the date of publication.

 1.0 Executive Summary

Application developers should consider the special needs of disabled users when they are developing software programs in Javatm. In these guidelines, we discuss the following topics:

  1. Essential accessibility programming practices that, if used, make applications easy for disabled people to use.
  2. The Java Foundation Classes (JFC) and their implementation of accessibility methods in the user interface components (application developers should take advantage of this easy way to incorporate accessibility into their designs).
  3. The Java Accessibility API (if developers choose to create components themselves, they should implement this API).

These topics are covered in detail with supporting rationale, citing specific Java code, and giving examples where appropriate.

These guidelines highlight the Java accessibility features and give you and your team guidance for creating accessible Java-based software. This is the industry's first set of 100% Pure Java application development guidelines for accessibility. The guidelines are designed to be interactive, online, and updated easily. The guidelines document can be printed, but the online version at the IBM Special Needs Systems Web site http://www.austin.ibm.com/sns/access.html  will be continually updated and will be more helpful because of hyperlinks pointing to supporting information.

 2.0 Introduction

When you are writing a Java application, try to imagine that a disabled person might end up using your product. Imagine someone who can not use her hands or her eyes -- that means she can not use a mouse, type on a keyboard, see a screen, or read a User's Guide. If she can not successfully use the computer then she might not be able to keep her job.

Over the years, disabled users and Access Technology Vendors (ATVs) have invented incredibly clever work-arounds for these problems. Voice input replaced the mouse; mouth sticks and switches replaced the keyboard; text-to-speech synthesis replaced the screen; online books replaced printed books.

Lest you think only hardware is inaccessible, think again. Software has its share of problems too. Operating systems and application programs often include unintentional roadblocks to people who have disabilities. Some examples:

The following section discusses issues in detail to lead to a better understanding of how to make an accessible Java solution.

 2.1 Disability Issues

You can build accessibility into Java software and make it easier for ATV software to access. Try to keep in mind these issues about what disabled users need:

Users who are blind or who have low vision need:

Users who are deaf or hard of hearing need:

Users who are mobility impaired need:

Users who have multiple disabilities need:

 2.2 Why Java for Accessibility?

Java was first developed for use in small appliances. It has since evolved into a language that enables applications to run on multiple operating systems and hardware platforms. Because it will run virtually everywhere it was enthusiastically adopted for Web and Internet applications.

Traditional graphical user interface (GUI) based operating systems now need to support legacy software that is not object-oriented. This introduces inconsistency in the ability to provide accessibility information and therefore leads to reverse-engineered access solutions, which are not always accurate.

Java is object-oriented from the ground up. This provides a mechanism for application components to export accessibility information about themselves to assistive technologies.

Java's characteristics and these factors make it ideal for developing industry standards for accessible solutions.

The software engineers at Sun and IBM who are developing Javatm technology are well aware of accessibility issues. They are consulting with disabled customers, business, education, and rehabilitation experts in the computer accessibility community, and conducting extensive reviews and beta testing of their code. As a result, many accessibility features are already built into Java and even more features are expected.

If you exploit the Java accessibility features when you develop software, you win in three ways. First, the features are easy enough to incorporate that you won't expend lots of development resource. Second, your software will be universally accessible; customers of all abilities will be able to work with it. Third, features that are designed specifically for disabled users often make the product more usable for able-bodied users as well. For example, if you "keyboard-enable" your application so that it is easier for blind users to read with their screen readers, it will be easier for people who use voice control software as well.

Access Technology Vendors (ATVs) are winners too. If you implement your application using the Java accessibility features, ATVs will have a much easier time making their products work with yours.

 3.0 Essential Accessibility Programming Practices

In this section, you will find a list of specific practices that are absolutely essential for making your Java applications accessible.

 3.1 Making the Keyboard Accessible (Mouseless Operation)

Mouse usage fundamentally depends on visual feedback of the location of the mouse pointer on the screen. Therefore, blind users, who may depend on the software for employment, can not use a mouse. Another example is when the window or program controls like the tool bar, menus, or buttons are beyond the visible screen display and therefore not accessible to the mouse. Other examples include automated software, test cases and voice-activated software that navigate the application programmatically simulating keyboard events.

Accessible software includes keyboard equivalents for all action or functions of the application (i.e. keyboard equivalents for all mouse actions including, but not limited to, buttons, scroll windows, text-entry fields and pop-up menus). The application must provide pull-down menu equivalents for icon functions (menu, tool, and format bar) and insure keyboard access to these pull-down menus. Traditional "usable" software insures the opposite is also provided – visible pull-down menu equivalents for all short-cut keys.


The application must not interfere with existing accessibility features built into the operating system, such as Sticky Keys, Slow Keys, and Repeat Keys. 

It's easy to check if keyboard access is available in an application - have the test team use the product without the mouse.

Please refer to the sample keyboard bindings in Section 11.1 for example key mappings to navigate in and out of applications and to Section 6.3.5 for tips on keyboard enabling your application.

 3.2 Using Images, Audio, and Video

When using multimedia in your application, you need to incorporate the following functionality:

 3.3 Providing Focus

Access devices and software, as well as disabled users, need to know where keyboard input focus is directed in an application. It is imperative that you always give input focus to the object on which you want the user to operate. For example, consider the situation where an application brings up its own custom dialog and you have a blind user at the helm:

The first thing the blind user wants to do is use the ATV screen reader program to speak what object he is on. When he hears nothing, the blind user may start typing keys to hear where he is or if the application will respond. When nothing speaks, his only resort may be to use the mouse, which is very difficult to use if he can not see where to click. In order to make your application accessible, please provide keyboard-input focus.

 3.4 Using Alerts and Dialogs

Dialogs and Alerts should be built based on the Java accessibility development methodology described in these guidelines. Dialogs and Alerts often require special system features to maintain the modality of those windows. It is recommended that you build these application features from JFC components such as JDialog. These components are made to work with ATV software so that ATV software can track the user's input focus. While other mechanisms may appear to work visually they may not be programmatically accessible.

 3.5 Using AWT and Native Windowing Invocations

To date, most Java AWT (Abstract Window Toolkit) components resort to a process called "peering." This means that AWT components such as dialogs, buttons, menus, and File Dialogs use the native windowing system to do the drawing and much of the component state management. This means that most accessibility information is lost to ATV software.

The new Java Accessibility API has not been implemented in the AWT library. We recommend that you develop Java applications using the methodology outlined in these guidelines.

 4.0 Java Foundation Classes (JFC) - A Foundation for Accessibility

In February of 1997, Sun Microsystems and IBM began a collaboration to solve the problem of access-enabling software as applications are being developed. Their goal was to develop accessibility API which application developers could implement on Java class libraries to make them accessible. Sun wrote the Accessibility API and implemented it on their Java Foundation Classes. IBM Special Needs Systems helped define and implement the API, and tested the JFC implementation with IBM's emerging Java Screen Reader technology.

[block diagram of JFC structure]


JFC includes the Swing components. Swing is an enhancement of - not a replacement for - the Abstract Windowing Toolkit (AWT) which you are probably familiar with in JDK 1.1. An important difference between Swing and AWT is that Swing creates its components using pluggable "Look & Feel" (L&F) modules that don't make any use of native code.

As shown in the figure above, Swing sits atop of part (but not all) of the AWT components. Swing sits on a number of the APIs that implement the various parts of AWT: including Java2D, Drag-and-Drop, and the Accessibility API. Sun has announced plans for all of these to be integrated into JDK 1.2

The Sun accessibility group also added a new mechanism to the JFC called the Multiplexed UI (an extension to the JFC L&F) which allows developers and ATVs to add alternative user interfaces to the JFC component library when a Java Virtual Machine (JVM) starts. The purpose of this feature was to make "direct accessibility" for the disabled user possible because ATV’s (or you) can add audio, Braille, or any other alternative user interface to your application. You can imagine that the Multiplexed UI also makes multi-modal access features (such as hands-free voice access to applications used by disabled and non-disabled people alike) possible for very little development effort.

 4.1 Why Use the JFC?

These two features of the JFC - the "already-implemented" Accessibility API and the Multiplexed UI - are the reasons that we urge you to use the JFC to build your applications.

The JFC allows you to:

If you choose to create your own class library, you can (and should) implement the Java Accessibility API on your class library components.

To build an accessible application with the least amount of effort on your part, we recommend you proceed as follows:

  1. Wherever possible, use JFC components to build your application as described in section 5.0
  2. When the rich class library in the JFC does not have a component which meets your needs, create your hybrid component from the JFC JComponent class and implement the Accessibility API on it as described in Section 6.0. The JFC comes with source and you have lots of examples on which to base your implementation.
  3. If 1 and 2 do not meet your needs, implement the Accessibility API on your class library or component.
  4. Use an accessibility tool to test your application for accessibility. Note: The IBM Java-based Screen Reader emerging technology is currently in development.

 5.0 Using JFC to Build Accessible Applications

If you are a typical engineer and take a glance through this text, you'll find it is easier to use the JFC than to implement the Accessibility API. Make it easy on yourself and use the JFC!

This section discusses how you use the JFC to build your accessible Java application. It is broken down as follows:

 5.1 Setting up the JFC Development Environment

The first step toward writing accessible Java applications is to download and install the following software development kits:

Software URL
Java Development Kit 1.1.2 or better http://java.sun.com/products/jdk/1.1/index.html 
JFC/Swing 1.0 http://developer.javasoft.com/developer/index.html 
FIGURE 2.0 URL’s for the JDK and JFC

To download the files, simply register on the site, log in and download the Swing files (the JFC is included in the Swing class library). Note: Sun has announced that the JDK 1.2 will have Swing integrated into it so you will not have to perform separate downloads. Although the early access release of JFC 0.7 for JDK 1.1.x included the Accessibility API, it did not include Java2D nor Drag-and-Drop.

 5.2 Using the JFC Components Unmodified

The JFC is an extremely rich class library, which has implemented both keyboard accessibility as well as the accessibility API. If you use it as is, there are only a few simple things you need to do:

In short, these simple programming functions allow you to meet essential accessibility programming requirements. The rest is taken care of by the JFC!

 5.3Enhancing JTextComponents

JTextComponent is a class with an extendable document model. Each element within the document model need only support a common element interface. The element could be anything from another JFC component to simple text. Furthermore, the document model itself has a pre-defined interface. This design allows you to embed documents within documents, insert other complex components, and so on.

What enables an access program, like a blind screen reader product, to decipher this is:

Unless you modify the JTextComponent, AccessibleText implementation, AccessibleText will still allow an ATV program to read your basic document. Applications can break the accessibility of documents by improperly implementing the AttributeSet and its attribute elements.

 5.3.1 AttributeSet, MutableAttributeSet, and StyleConstants Classes

AttributeSet, MutableAttributeSet are JFC classes, which define an interface to an attribute set. StyleContants defines a common set of attributes for the attribute set. Without a known set of attributes, an ATV program just will not  know what to do with your document, much the same way that component technology fails without a set of standards.

In implementing your AttributeSet for document elements, it is important that you define attributes using those pre-defined in the StyleConstants class. The following list of Key/Value pairs should be used.

StyleConstant Attribute Keys Class Definition for the Value
Background Color
Bold Boolean
ComponentAttribute  Component or JComponent that must implement Accessible
ComponentElementName String
FirstLineIndent Float
FontFamily String
FontSize Integer
Foreground Color
IconAttribute ImageIcon
IconElementName String
Italic Boolean
LeftIndent Float
LineSpacing Float
NameAttribute String
ResolveAttribute AttributeSet
RightIndent  Right
SpaceAbove Float
SpaceBelow Float
TabSet TabSet
Underline Boolean

FIGURE 3.0 AttributeSet Key/Value Pairs Defined in StyleConstants.java

If you are converting an existing program to JFC, the AttributeSet and MutableAttribute interfaces should allow you to convert your existing document structure to a JFC implementation. These interfaces provide for text runs, and embedded components. It is StyeConstants.java’s provision for embedded components that allows you to embed components in your document elements; you can add things like spreadsheets, and tables. Furthermore; you can define your own user interface using JFC to give whatever look you want to your document and the JFC comes with source to show you different implementations other than plain text areas.


It is essential that when you add components to your document model they implement the Accessible Interface. If you use standard JFC components, they already do.


It is helpful if you name the set of attributes as they pertain to specific sets within your document. For example, if you were building a web browser, the NameAttribute for <h2> may be the string "<h2>." This can help an ATV program tailor itself for your application. For example, a blind access program could be designed to speak the HTML tags of a web browser.


 5.4 Changing Data Models and Cell Renderers

The root component class is called JComponent and is a descendant of the AWT container class. JComponent is the root class of almost all JFC classes.

The design of each component is based on the Model-View-Controller (MVC) architecture. Each component is broken into three parts called the model or "data" portion of the component, the UI or "look and feel" portion (also called the view), and the controller portion, which manipulates the components. Implementation of the Accessibility API is triggered from the "data portion" of each JFC component. This enables you to implement an accessible application without affecting its "look and feel."

When developing your application using the JFC it is important that you avoid modifying or replacing the "data" portion of each component with your own. You run the risk of improperly implementing methods that are required to support the data interfaces and this could break the accessibility features of the component.

Another JFC concept introduced is a cell renderer. A cell renderer is an interface used by a JFC component to define a component drawing object within a list of elements. For example, the JFC uses ListCellRenderers for JList elements and TableCellRenderers for JTable elements. For a given cell renderer a method is provided to return a Component configured for a given element, like getListCellRendererComponent in the JList component.

If you change the cell renderer for a JFC component, make sure that it implements Accessible. If you implement your cell renderer on an existing JFC component, you can configure your cell renderer for the given element and reuse an already accessible component. An example of this is JList’s use of JLabel for its cell-rendered children.

 5.5 Creating New Components Based on the JFC

If you need to build completely new components, use JComponent because you pick up Accessibility information and methods from its internal abstract class AccessibleJComponent.

To complete the implementation of the Accessibility API on your JComponent you will need to follow the guidelines in section 6.0.

 5.6 Preparing for Future JFC Accessibility Features

One of the features lacking in the first Java Accessibility API is its support for Tables. An AccessibleTable interface is now under review. Its first implementation will be on JTable. If possible, it is recommended that when using tables in your application, you use the JTable class provided in the JFC. When the AccesibleTable interface is implemented, your application should be able to pick up the table accessibility information.

Other interfaces being reviewed are AccessibleLabel, which provides a pre-defined interface to the setLabelFor method mentioned previously, and an AccessibleDocument interface for advanced dyslexic and mobility impaired access. Watch the IBM and Sun web sites for announcements about these.

 6.0 The Accessibility API

The Accessibility API is a set of interfaces and classes designed by the Sun Microsystems Accessibility Group, IBM Special Needs Systems, Trace Research and Development Center of the University of Wisconsin at Madison, and other leading accessibility organizations.

The Accessibility API defines a common signature, which can be implemented on application components, giving them a known signature to allow ATV software to extract the Accessibility information from your application.

The Accessibility API is now shipped with the JFC package and can be found in the com.sun.java.accessibility package. It is scheduled to be included in JDK 1.2.

 6.1 Interface Accessible

This section covers what a Java interface is and how it is used 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 ATV program can examine if an object is an instance of a particular interface using the instanceof operator. The first interface we will describe will tell us whether an object has implemented the basic Accessibility API.

 6.1.2 Using Interface Accessible

Accessible is an interface, which you need to apply to your class file to allow an ATV program to know if you have implemented the Accessibility API. Figure 4.0 shows how you would implement Accessible on your own custom component.

import com.sun.java.awt;
import com.sun.java.accessibility;

class MyButton implements Accessible extends Component{
     AccessibleContext getAccessibleContext() {
Figure 4.0 Implementation of Accessible

Accessible’s function is to provide a method, which returns the AccessibleContext. The AccessibleContext provides the most basic accessibility information needed for any component.

The object returned by getAccessibleContext() will also implement more detailed Accessibility information based on the role of the GUI class being used. Some of the methods defined by AccessibleContext will return a null value since they really do not apply. For example, there is no reason to implement the AccessibleText interface on a scroll bar.

The way you would maintain the AccessibleContext is to keep an internal class inside your GUI class file, which keeps track of the accessibility information. When asked to provide the AccessibleContext, you would 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. Figure 3.1 shows a table of the methods it supports and their descriptions.

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.
getAccessibleIndexInParent() Gets the 0-based index of this object in its accessible parent.
getAccessibleName() Gets the accessibleName property of this object.
getAccessibleParent() Gets the Accessible parent of this object.
getAccessibleRole() Get the role of this object.
getAccessibleSelection() Gets the AccessibleSelection associated with this object.
getAccessibleStateSet() Get the state set of this object.
getAccessibleText() Gets the AccessibleText associated with this Component. 
getAccessibleValue() Gets the AccessibleValue associated with this object. 
getLocale() Gets the locale of the component. 
removePropertyChangeListener(PropertyChangeListener 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.
Figure 3.1 AccessibleContext Abstract Class Methods

ATV software can make especially good use of AccessibleContext. For example, by querying AccessibleContext, an ATV program can know about and announce changes in a text field.

This section will help you implementing AccessibleContext in your library and is divided as follows:

 6.2.1 Basic Accessible Information

This section contains a description of the following: AccessibleName

AccessibleName is the simply the name of the object.

Here are some general rules to follow for setting the AccessibleName: AccessibleDescription

AccessibleDescription is a text description of an object's purpose. For example, if the object were a web page link containing an image you would want to set this to the Universal Resource Locator (URL) String of the target.

If your task is to write a class file and make it accessible, you should follow these rules:

If your task is to use an existing Accessible class file to build an application and the default accessible description does not accurately describe the function of the Accessible object, you should set the accessible description in that class file,. AccessibleValue

AccessibleValue is used only for a specific set of object types, which provide a range of values and a current setting. Otherwise, you would 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 listed Figure 5.0.

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.
Figure 5.0 AccessibleValue Interface Methods

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

In a progress bar, this would happen when the progress bar increases its current value. For more information on firing this property change, see section 6.2.4. Locale

This is the current locale for which your component was written. See the JDK for a more detailed description of Locale. Low-Vision ATV programs use this information in determining 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. 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 where the user would have his current input focused. For example, if your object were 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 an ATV program 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.

AccessibleSelection supports the methods listed in Figure 6.0.

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.
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.
Figure 6.0 AccessibleSelection Interface Methods

When changes occur in the AccessibleSelection, you need to fire the ACCESSIBLE_SELECTION_PROPERTY property change event in the AccessibleContext.

For more information on firing this property change, see section 6.2.4. AccessibleComponent

AccessibleComponent is the Accessible JDK component associated with this accessible object. AccessibleComponent defines a standard interface for ATV programs 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 a 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 Figure 7.0.

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.
Figure 7.0 AccessibleComponent Interface Methods

When you are programming the AccessibleContext, you will find that much of this information can be retrieved directly from the actual associated JDK or JFC component. In the case of JFC, the base JComponent class has an internal abstract class called AccessibleJComponent. AccessibleJComponent has many of the methods needed to support AccessibleComponent since the information can be acquired directly from JComponent. 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;

     public abstract class AccessibleJComponent extends AccessibleContext
     implements Serializable, AccessibleComponent 
   {   /**
       * Get the AccessibleComponent associated with 
       * this object if one exists. Otherwise return
       * null.
       public AccessibleComponent
             return this;

       * Get the Font of this object.
       * @return the Font,if supported, for the object;
       *   otherwise, null
       public Font getFont() 
           return JComponent.this.getFont();

       * Set the Font of this object.
       * @param f the new Font for the object
       public void setFont(Font f) 

       * Set the enabled state of the object.
       * @param b if true, enables this object;
       * otherwise, disables it 
       public void setEnabled(boolean b) 
           boolean old = JComponent.this.isEnabled();
           if (b != old) 
             if (accessibleContext != null) 
               if (b) 
                           null, AccessibleState.ENABLED);
                           AccessibleState.ENABLED, null);

       public String getAccessibleDescription() 
          if (accessibleDescription != null) 
            return accessibleDescription;
              String ttt = getToolTipText(null);
              if (ttt != null) 
                return ttt;
            catch (Exception e) 
          return null;
Figure 8.0 Example Code found in JFC’s JComponent for Supporting AccessibleComponent Information

A quick perusal of the sample code in Figure 9.0 will demonstrate the structure for building an Accessible component when using the JFC JComponent as a base. Since the internal JComponent class, AccessibleJComponent, extends AccessibleContext, you automatically up 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();
      if (AccessibileName == null)
          return ButtonText;
          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.


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 JDK Component class or a descendant of it. 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 (Figure 10.0) provides a mechanism for ATV programs 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 program 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.


Method Description
getAfterIndex(int part, int index)  Returns the String after a given index based on the part defined in
getAtIndex(int part, int index)  Returns the String at a given index based on the part defined in
getBeforeIndex(int part, int index) Returns the String before a given index based on the part defined in
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.
Figure 10.0 AccessibleText Interface Methods 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 ATV program 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 Figure 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 com.sun.java.swing.text.StyleConstants;
import com.sun.java.swing.text.AttributeSet;
import com.sun.java.swing.accessibility.*;

Color getColor(Accessible yourComponent, int index) {
        Color bg = null;
AccessibleContext ac =
AccessibleText at = ac.getAccessibleText();

// Get the Attribute Set
AttributeSet aset = at.getCharacterAttribute(index); 

// Get the background color
bg = (Color)

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) 
/* When no background color exists in the */
/* AttributeSet Tree, get the the color */
/* from the accessible component */

if (bg == null) {
   AccessibleComponent acx = 
   bg = acx.getBackground();
return bg; // return the background color

Figure 11.0 Retrieving the Background Color from AccessibleText

Examining Figure 11.0 we can see how an ATV 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 life easy, the Sun folks have 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

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();
                     new Boolean(true));
//Give the run a name

// Set the Resolving Parent, so the ATV program can determine the background color

Now, you simply have to store this Attribute set with the specified run of text in your document, based on your document data model. When an ATV program 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. 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 an ATV program 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();
                      new JTable());
//Give the list of components a name
TableAttributeSet.add(StyleConstants.ComponentElementName, "Table of Contents");

//Give the run a name

//Set the Resolving Parent, so the ATV program can determine the background color

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:

Attribute Value
StyleConstants.NameAttribute "<IMG>"
StyleConstants.IconElementName URL String for the Icon
StyleConstants.IconAttribute (Icon)new ImageIcon(URL,


Figure 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 Java screen reading application to expand the view on that Component. The Component 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. Referencing the Indexed Character String

The AccessibleText interface refers to an index and a String return identified by the part parameter in Figure 10. The index is a character-based index to your document. Where the integer part is indicated, it is one of AccessibleText.CHARACTER, AccessibleText.WORD, or AccessibleText.SENTENCE. When the Accessible text method specifies the part, the caller is asking you to return the character, word, or sentence around the given character index as specified by the method. 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.


If you are developing a new accessible text class (non-JFC), please remember to keyboard-enable selecting text. This 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. 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.


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 ATV software.


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

 6.2.2 Parent/Child Information

The way ATV programs 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 ATV program listens for a focus change. When this occurs, the ATV 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 ATV 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 ATV program 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 ATV 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: getAccessibleChild(n)

This function returns the nth immediate child that implements the Accessibility API. 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. getAccessibleParent()

AccessibleParent returns the parent object that implements the Accessibility API. If there is no Accessible parent this method should return null. 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 the ATV program queries the nth entry in the list box, the result should support the Accessibility API. When the ATV program 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 an ATV program 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: 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, ATV 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). It therefore 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.

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

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.
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.
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.
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.
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.
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, eachproviding 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.
Figure 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 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 PROGRESS_BAR accessible role and set the AccessibleDescription to "Thermometer." AccessibleState

AccessibleState is used 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). It therefore 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, a subclass should be generated from this class and it should provide constants in a similar manner.

The generic enumerated states, provided by this class, are largely based on classes provided in JFC’s rich GUI component class library.


AccessibleState Description
ACTIVE  Indicates whether an application is active. Example: top-level frames use it to indicate that it or one of its children has focus.
ARMED  Indicates that the user input is currently directed to that object and it is "armed for selection." Examples: 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.
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.
Figure 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 ATV program 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 checkbox, or "vertical" for a scroll bar. See the previous section for a more detailed description of the accessible state.

The AccessibleStateSet class supports the methods listed in Figure 15.

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.
Figure 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.


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.

 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 ATV software to be notified when specific property data changes. This enables ATV programs to passively monitor your application. Property change notification is handled through your implementation of AccessibleContext. ATV 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 Accessibility properties you must support:

ACCESSIBLE_DESCRIPTION_PROPERTY: When a change in the accessible description occurs, you must fire this property change event to registered listeners. To fire the this property change event, the following mechanism is required:

      oldDescription, newDescription);
Where, old and new descriptions are of class String.


ACCESSIBLE_NAME_PROPERTY: When a change in the accessible name occurs, you must fire this property change event to registered listeners.

      oldName, newName);
Where, old and new Names are of class String.

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:

      null, selectedText);
Where SelectedText is a String.

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:

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.
      new Boolean(false), new Boolean(true));
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.
      new Integer(oldValue), new Integer(newValue));
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 access programs store the visible data information in their own data structures, to give their own "look and feel" of your program. For example, IBM's Java-based Screen Reader sorts its information in row/column format.
      new Boolean(false), new Boolean(true));
This property change applies to all components except those that implement AccessibleText.

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.

      new Integer(oldposition),
      new Integer(newposition));

 6.2.5 National Language Information

This section describes the following two class files, which come with the Accessibility API to allow it to support 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: AccessibleBundle

As stated earlier, AccessibleRole and AccessibleState are descendants of AccessibleBundle. AccessibleBundle supports the methods listed in Figure 16.
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.
Figure 16: AccessibleBundle Methods

The source for this class is in the com.sun.java.accessibility package source included in the JFC. AccessibleResourceBundle

This contains all the key/localized string information for each AccessibleRole and AccessibleState.

The source for this class is in the com.sun.java.accessibility package source included in the JFC.

 6.2.6 Miscellaneous Information

The following are specialized interfaces that defy categorization. This section describes: 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. For these reasons, the AccessibleAction object was created. AccessibleAction contains a collection of description/action entries to allow an ATV program 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 as follows:

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.
Figure 17: AccessibleAction Methods

Implementation of AccessibleAction is extremely important for web browser development. The following AccessibleAction description/action pairs could be used to navigate an image map:

Description Action
"URL:http://www.ibm.com/sns" Browser loads: IBM SNS Web page
"URL:http://developer.javasoft.com" Browser loads: Sun Java Developer Web page


If you have a Component or component element which can only be activated by the mouse, you must provide an AccessibleAction for it, otherwise it is inaccessible. AccessibleTable

This interface is still under review and subject to change to support new HTML web accessibility guidelines and table designs.

Since this is subject to change, the definition for this interface is not covered. It should be noted that JFC JTables support the current version of the Accessibility API. AccessibleLayout

This interface is still under development. Its purpose will be to indicate the proper layout of child components.

In the interim, when you add components to containers, add them in the logical order as they should be read on the screen (independent of the way the way you have to add them based on the layout). For example, if you were using an AWT border layout you could add components as follows:

public class BorderTest extends Frame implements Accessible{
     public BorderTest () {
          AccessiblePanel p = new AccessiblePanel();
          p.setLayout(new BorderLayout();
          p.add(new MyAccessibleButton("Left");
          p.add(new MyAcessibleButton("Bottom");
          p.add(new MyAcessibleButton("Right");
          p.add(new MyAcessibleButton("Top");
          add("North", p);
     AccessibleContext getAccesibleContext() {
Child enumeration in Java enumerates the children in the order that you added them. By merely changing the order in which you add the components, you can enable the access program to read the components in the appropriate order as shown in the following sample code, and still accomplish the same visual effect:
p.add(new MyAcessibleButton("Top");
p.add(new MyAccessibleButton("Left");
p.add(new MyAcessibleButton("Right");
p.add(new MyAcessibleButton("Bottom");

 6.3 Hints, Tips, Pointers, and Words of Wisdom

When determining how to implement code, it is always good to see how someone else accomplished the task. The JFC now comes complete with source. Since the JFC has implemented the Accessibility API, in most cases, this is an excellent place to start. Furthermore, it also includes the Accessibility API source. See Figure 16 for some excellent examples to look at.

JFC Component Type of Example
JList Example of a Proxying component for a list of Accessible Children.
JTextComponent, JEditorPane Examples of AccessibleText and AccessibleText implementation for presenting HTML text.
JLabel Simple implemenation of the Accessibibility API.
JProgressBar  Implementation of AccessibleValue.
JComponent AccessibleJComponent internal class implementation of the AccessibleContext abstract class.
Figure 16: Example Accessibility API Implementations

The next two sections are problem areas you are likely to run into when trying to make application components accessible:


 6.3.1 Managing Children

Proxied objects are lightweight objects whose placement, drawing directives, and response to input are guided by a parent object. An example is the JFC implementation of cell renderers for list box. In a JFC list box, each list entry is created through the use of a singe ListCellRenderer. The JList component tells it where to draw, when to "appear" selected, and so on. The JList component does not care what the cell renderer draws in it as long as it does what it is told. The cell render does not receive focus from the windowing system, even though JList may ask it to appear focused. If you are familiar with X Window System programming, you should recognize these lightweight objects as similar to "gadgets."

Parents, who do not proxy for their children, need only worry about keyboard navigation to the children and providing the list of children.

Here are some basic rules to follow when making managing children:

 6.3.2 Peered Objects

Peered objects translate to GUI objects in the underlying operating system. For example, most AWT components fall into this category. If you were trying to make a peered object accessible, I would suggest that you step back, raise the ball and punt.

In most instances, the data does not reside on the Java side of the wall. In the case of Windowstm or OS/2tm, it would likely mean that you’d need to provide numerous methods to get the data back to the Java side of the fence from the native DLL. This may be simple for small items like labels and buttons, but if you wanted to deal with things like file dialogs and WYSIWIG documents, you are looking at a major uphill climb.

Use JFC.

 6.3.3 Menus

Menus are usually the most specialized part of a GUI application due to performance issues and constant access by the user. They are often the most distinguishing features of a GUI environment. This means they are usually treated as a special case item by ATV software. If you decide to use a new menuing system, you probably will no longer work with ATV software.


USE JFC menu components. ATV software will be familiar with it.

 6.3.4 Text Components

Using JFC JTextComponents is ideal, but implementing AccessibleText on components like these is a minimum. This is especially important for editable text areas.

 6.3.5 Keyboard Enabling

The Appendix contains keyboard bindings for the Java Foundation Classes to be used as a foundation for keyboard enabling your application. When keyboard enabling your application, you should follow these rules of the road:

 7.0 Java Development Tool Designers

[This section is TBD in a later release.]

 8.0 Testing for Accessibility

[This section is TBD in a later release. It will include information on how to test your application using assistive technology.]

 9.0 Online Information and Help

When developing documentation for your application in HTML please follow the Web accessibility guidelines found on the IBM Special Needs Systems web site at http://www.austin.ibm.com/sns/access.html  The official guidelines are published by the World Wide Web Consortium (W3C) at http://www.w3.org/WAI 

 10.0 Future Discussions 

This section is intended as a heads-up on what is coming. Java is still new and the following areas of accessibility need to be addressed in future issues:

 11.0 Appendix

This appendix contains the following sections:
  1. Keyboard bindings
  2. Accessibility References
  3. Trademarks

 11.1 Keyboard Bindings

These bindings will be partially implemented, at a minimum, by JFC/Swing 1.0 in the early 1998 time frame. As you'll see, there are a couple components with ? next to them, these bindings may get modified. This section will change if/when this happens. This list is also under review by IBM Special Needs Systems and other industry experts such as the Trace Research and Development Center.

 11.1.1 JFC Keyboard Bindings for Windows95/NT Components 

 11.1.2 Difference Evaluation: JFC Keyboard Bindings for Windows95/NT and CDE/Motif 

 11.1.3 Reserved Key Mappings for Mobility Access Features 

Keyboard Mappings Mobility Access Feature
5 consecutive clicks of Shift key On/Off for StickyKeys
Shift key held down for 8 seconds On/Off for SlowKeys and RepeatKeys
6 consecutive clicks of Control key On/Off for screen reader numeric keypad
6 consecutive clicks of Alt key Future Access use

 11.2 Accessibility References

"What is Accessible Software":
Dr. James Thatcher, IBM. http://www.austin.ibm.com/sns/software.html 
"Making the GUI Talk":
Richard S. Schwerdtfeger, IBM. ftp://ftp.software.ibm.com/sns/sr-os2/sr2doc/guitalk.txt  Off-Screen Model Technology and GUI Screen Readers
"Towards Accessible Human-Computer Interaction":
Eric Bergman, Earl Johnson, Sun Micrososytems. http://www.sun.com/tech/access/updt.HCI.advance.html 
"Accessibility Quick Reference Guide":
Sun Microsystems. http://www.sun.com/tech/access/access.quick.ref.html 
"Java Development Kit":
Sun Microsystems. http://java.sun.com/products/jdk/1.1/index.html 
"Java Foundation Class":
Sun Microsystems. http://developer.javasoft.com 

 11.3 Trademarks 

IBMÒ, OS/2Ò, AIXÒ, AS/400Ò, Screen ReaderÒ, and Visual AgeÒ are trademarks or registered trademarks of International Business Machines Corporation in the United States and/or other countries.

Lotustm is a trademark of Lotus Development Corporation in the United States and/or other countries.

Tivolitm is a trademark of Tivoli Systems Inc. in the United States and/or other countries.

MicrosoftÒ, WindowsÒ, Windows95Ò, and WindowsNTÒ are registered trademarks of Microsoft Corporation.

Sun Microsystemstm, Javatm, 100%Pure Javatm, and Solaristm are trademarks of Sun Microsystems Inc.

Other company, product, and service names may be trademark or service marks of others.

 11.4 Feedback

Please e-mail feedback to IBM Special Needs Systems at: snsinfo@us.ibm.com 

Go back to article. 

Reprinted with author(s) permission. Author(s) retain copyright.