Table of Contents

• Acknowledgments
• Notices
• 1.0 Executive Summary
• 2.0 Introduction
• • 2.1 Disability Issues
  • 2.2 Why Java for Accessibility?
• 3.0 Essential Accessibility Programming Practices
• • 3.1 Making the Keyboard Accessible (Mouseless Operation)
  • 3.2 Using Images, Audio, and Video
  • 3.3 Providing Focus
  • 3.4 Using Alerts and Dialogs
  • 3.5 Using AWT and Native Windowing Invocations
• 4.0 Java Foundation Classes (JFC) - A Foundation for Accessibility
• • 4.1 Why Use the JFC?
• 5.0 Using JFC to Build Accessible Applications
• • 5.1 Setting up the JFC Development Environment
  • 5.2 Using the JFC Components Unmodified
  • 5.3 Enhancing JTextComponents
  • • 5.3.1 AttributeSet, MutableAttributeSet, and StyleConstants Classes
  • 5.4 Changing Data Models and Cell Renderers
  • 5.5 Creating New Components Based on the JFC
  • 5.6 Preparing for Future JFC Accessibility Features
• 6.0 The Accessibility API
• • 6.1 Interface Accessible
  • • 6.1.1 Interfaces
    • 6.1.2 Using Interface Accessible
  • 6.2 AccessibleContext
  • • 6.2.1 Basic Accessible Information
    • 6.2.1.1 AccessibleName
    • 6.2.1.2 AccessibleDescription
    • 6.2.1.3 AccessibleValue
    • 6.2.1.4 Locale
    • 6.2.1.5 AccessibleSelection
    • 6.2.1.6 AccessibleComponent
    • 6.2.1.7 AccessibleText
    • 6.2.1.7.1 Text Attributes
    • 6.2.1.7.2 Embedding Objects
    • 6.2.1.7.3 Referencing the Indexed Character String
    • 6.2.1.7.4 Caret Position and SelectedText
    • 6.2.1.7.5 Property Changes
    • 6.2.2 Parent/Child Information
    • 6.2.2.1 getAccessibleChild(n)
    • 6.2.2.2 getAccessibleChildCount()
    • 6.2.2.3 getAccessibleParent()
    • 6.2.2.4 getAccessibleIndexInParent()
    • 6.2.3 Role and State Information
    • 6.2.3.1 AccessibleRole
    • 6.2.3.2 AccessibleState
    • 6.2.4 Property Change Notification
    • 6.2.5 National Language Information
    • 6.2.5.1 AccessibleBundle
    • 6.2.5.2 AccessibleResourceBundle
    • 6.2.6 Miscellaneous Information
    • 6.2.6.1 AccessibleAction
    • 6.2.6.2 AccessibleTable
    • 6.2.6.3 AccessibleLayout
  • 6.3 Hints, Tips, Pointers, and Words of Wisdom
  • • 6.3.1 Managing Children
    • 6.3.2 Peered Objects
    • 6.3.3 Menus
    • 6.3.4 Text Components
    • 6.3.5 Keyboard Enabling
• 7.0 Java Development Tool Designers
• 8.0 Testing for Accessibility
• 9.0 Online Information and Help
• 10.0 Future Discussions
• 11.0 Appendix
• • 11.1 Keyboard Binding
  • • 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
  • 11.2 Accessibility References
  • 11.3 Trademarks
  • 11.4 Feedback

Acknowledgments

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:

• Sun Accessibility Group
• Sun Swing team
• Trace Research and Development Center at the University of Wisconsin - Madison
• Adaptive Technology Resource Centre at the University of Toronto
• IBM corporation.

I would like to especially thank Earl Johnson for driving the Java^tm 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!

Notices

THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

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 Java^tm. 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:

• Programs that provide only mouse input (impossible for people who are blind or who use voice control);
• Programs that use audio-only messages (individuals who are deaf cannot hear the messages - this also applies to people who have systems that do not have sound capability);
• Operating systems that define Ctrl+Alt+Del to reboot the system (try doing this with only one hand).

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:

• Keyboard alternatives to the mouse (mouseless operation),
• Text descriptions of graphics and video,
• To know which object has focus and when the focus changes,
• To know the default action and how to take that action,
• Online documentation,
• Screen magnification,
• High color contrast

Users who are deaf or hard of hearing need:

• A visual indication of any sound,
• Text captioning of multimedia presentations,
• Text description of significant audio

Users who are mobility impaired need:

• Voice or assistive device input instead of keyboard or mouse input,
• Ways to "get around" multiple key inputs,
• Online documentation

Users who have multiple disabilities need:

• Combinations of solutions; for example, speech output and voice input that do not conflict

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 Java^tm 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.

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:

• Visual indication of sound and audio cues (Example: Visual message as well as a sound beep when notifying the user)
• Text captioning of the voice track in audio and video content (Example: Provide visual text captioning when playing audio files)
• Descriptive graphics for significant audio (Example: Provide a visual graphic for a progress indication done with sound)
• Descriptive text for significant video (Example: Provide a visual text description of what's happening in a tutorial's video segment)

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.

FIGURE 1.0 JFC ARCHITECTURE

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:

• Quickly develop accessible applications that can be made multi-modal accessible without changing the "look and feel" of your application.
• Write an accessible application, which is accessible independent of the operating system and windowing environment.

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:

• Setting up the JFC Development Environment
• Using the JFC Components Unmodified
• Enhancing JTextComponents
• Changing Data Models and Cell Renderers
• Creating New Components Based on the JFC
• Preparing for Future JFC Accessibility Features

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:

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:

• Provide Descriptive Component Text: Set the Accessible Description on all components (See section 6.2.1.2). Hint: Some, JFC Components use the tool tip for this information in the absence of your setting an accessible description. So if you have already set the tool tip text your task may be complete.
• Describe Icons and Graphics:
• • For JLabels and JButton classes which contain only images, set the AccessibleName (see section 6.2.1.1).
  • Whenever you use a JFC setIcon method, use a JFC ImageIcon. Whenever you use a JFC ImageIcon, use its setDescription method to help blind users. ImageIcon's are used in a variety of components ranging from JFC buttons to labels. You must also remember to do this with images inserted into a JTextComponent or JFC components sub-classed from JTextComponent.
• Label Components: When a JLabel is used to label another component, call its setLabelFor method to set the component it is labeling. This can be null if this does not label a Component. If the displayedMnemonic property is set and the labelFor property is also set, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.
• Enable Keyboard Access:
• • Set Mnemonics on Components: Mnemonics are keyboard equivalents for component activation. Whenever you have a component, which supports a setMnemonic method, you should set the mnemonic to a unique key sequence to activate the object. Currently the JFC does not have an accelerator to bring you to the menubar (F10). It is important that you always set the mnemonic for the first JMenuBar entry to allow a disabled user to get there using the keyboard.
  • Set Keyboard Accelerators in Menus: JMenuItem components provide a setAccelerator method to allow you to set a keyboard accelerator key to allow the user to activate a menu item without going through the menu. When possible it is a good, but not mandatory practice, to provide keyboard accelerators.
  • Keyboard Activation of Child JFrames or JInternalFrames: If you build a Java application or applet, which manages child frames, you should provide a keyboard equivalent to allow the user to cycle the focus to each child frame or allow the user to access these frames from a main menu.
• Group Objects Inside Named Panels: It is important for you to logically group components and assign that grouping a name. This facilitates navigation of your application. You can accomplish this by adding components to JPanels and setting the AccessibleName on the JPanel. If you use a JPanel with a JFC TitledBorder, there is no reason to set the accessible name as the JFC will do it for you.
• Set the Focus: Make sure that some component in your application has the input focus at all times. When keyboard enabling your application, this should take care of itself. Most of the JFC components implement focus setting to support keyboard navigation.

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:

• Maintaining the Accessible and AccessibleText interfaces support in JTextComponents.
• Standardizing attributes using the swing AttributeSet and StyleConstants classes for each indexed character.

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.

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 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 <H1> may be the string "<H1>." 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.

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:

• Basic Accessible Information
• • AccessibleName
  • AccessibleDescription
  • AccessibleValue
  • Locale
  • AccessibleSelection
  • AccessibleComponent
  • AccessibleText
• Parent/Child Information
• • AccessibleChild
  • AccessibleChildCount
  • AccessibleParent
  • AccessibleIndexInParent
• Role and State Information
• • AccessibleRole
  • AccessibleState
  • AccessibleStateSet
• Property Change Notification
• National Language Information
• • AccessibleBundle
  • AccessibleResourceBundle
• Miscellaneous Information
• • AccessibleAction
  • AccessibleTable

6.2.1 Basic Accessible Information

This section contains a description of the following:

• AccessibleName
• AccessibleDescription
• AccessibleValue
• Locale
• AccessibleSelection
• AccessibleComponent
• AccessibleText

6.2.1.1 AccessibleName

AccessibleName is the simply the name of the object.

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

• As a general default, when creating your accessible Component, the getAccessibleName method should return the text that appears on the screen for simple classes. Examples of these simple classes are labels, push buttons, check boxes, menu items, simple tab pane entries, and spin buttons. If this component is to be re-used by someone else, you should allow setAccessibleName to override the default.
• For complex classes which contain a collection of components (children), such as list boxes, tab panes, combo boxes, menus, and so on, you can return null unless the application developer explicitly uses the setAccessibleName method. The application developer may have an explicit function for your component and would need to set the name himself. For example, the application developer may configure your combo box to contain the months of the year in which case he would set the AccessibleName to months.
• When you change the AccessibleName, be sure to fire the ACCESSIBLE_NAME_PROPERTY as described in section 6.2.4.

6.2.1.2 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,.

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

Figure 5.0 AccessibleValue Interface Methods

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.

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

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

Figure 6.0 AccessibleSelection Interface Methods
 

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

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

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
               getAccessibleComponent() {
            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) {
            JComponent.this.setFont(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();
            JComponent.this.setEnabled(b);
            if (b != old) {
                if (accessibleContext != null) {
                    if (b) {
                        accessibleContext.firePropertyChange(
                                AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
                                null, AccessibleState.ENABLED);
                    } else {
 accessibleContext.firePropertyChange(
 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
                                AccessibleState.ENABLED, null);
                    }
                }
            }
        }
      
        public String getAccessibleDescription() {
            if (accessibleDescription != null) {
                return accessibleDescription;
            } else {
                try {
                    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();
    .
    .
    .
    getAccessibleName() {
         if (AccessibileName == 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.

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

Figure 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 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 =
               yourComponent.getAccessibleContext();
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.getAccessibleComponent();
   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
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,"

");
// Set the Resolving Parent, so the ATV program can determine the background color
LinkAttributeSet.setResolveParent(DefaultAttributeSet);

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.

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 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();
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 the ATV program 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:

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.

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

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.

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:

• ACCESSIBLE_TEXT_PROPERTY (text data changes)
• ACCESSIBLE_SELECTION_PROPERTY (highlighting text)
• ACCESSIBLE_CARET_PROPERTY (caret moves)

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

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:

• AccessibleChild
• AccessibleChildCount
• AccessibleParent
• AccessibleIndexInParent

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 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
• AccessibleState
• AccessibleStateSet

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, 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:

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

6.2.3.2

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.

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.

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:

firePropertyChange(
      AccessibleContext.ACCESSIBLE_DESCRIPTION_PROPERTY,
      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.

firePropertyChange(
      AccessibleContext.ACCESSIBLE_NAME_PROPERTY,
      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:

firePropertyChange(
      AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY,
      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:

firePropertyChange(
      AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
      null,
      AccessibleState.EDITABLE);

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));

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));

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.

firePropertyChange(
      AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,
      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.

firePropertyChange(
      AccessibleContext.ACCESSIBLE_CARETPROPERTY,
      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:

• AccessibleBundle
• AccessibleResourceBundle

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:

• Do not create your own AccessibleRole and AccessibleState information for your application. Use those provided for by Sun.
• If you have a need to add additional Role and State information, make a request to the Sun Accessibility group for incorporation in a later release of the Sun Java Accessibility API.

6.2.5.1 AccessibleBundle

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

Figure 16: AccessibleBundle Methods

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

6.2.5.2 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
• AccessibleTable
• AccessibleLayout

6.2.6.1 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:

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:

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

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

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 Windows^tm or OS/2^tm, 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.

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:

• Make sure the keyboard bindings you select do not conflict with system keyboard mappings of the underlying operating system. For example, CTRL+ALT+DEL may cause you to reboot or offer a shutdown option on some systems.
• Make sure the keyboard bindings you select do not interfere with the reserved mobility access keyboard modifiers for your operating system. See the Appendix section on Reserved Key Mappings for Mobility Access Features.

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

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.

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

Tivoli^tm 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 Microsystems^tm, Java^tm, 100%Pure Java^tm, and Solaris^tm 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.

Ó Copyright IBM^Ò

Corporation 1998

- End of Document -