In this chapter:

• Java 2 Accessibility API overview
• Following accessibility guidelines
• Accessibility support for custom components

When developing an application, it is important to keep in mind that many of it's users may be disabled to some degree. Disabilities can range anywhere from poor vision to blindness, hearing impared to deafness, or a physical inability to use a standard input device such as a mouse or keyboard. Many of these users may often rely on special devices plugged into the computer to help offset specific disabilities. Some of these devices can substitute printed text with audio output, ease keyboard input or point-and-click functionality, perform large scale screen magnification, etc. To do their job correctly, most of these devices need to find connection points within applications, and substitute some of the original functionality with accessible variations.

Java offers sets of classes and interfaces to provide the needed connection points for such special devices. These are referred to as assistive technologies, and are normally packages in a JAR archive. Java loads assistive technologies when the VM is started by looking for special entries in a file called accessibility.properties located in the jdk1.2\jre\lib directory. We will discuss how to use this file below.

Fortunately, Swing provides an extremely rich API for accessibility needs. If we use Swing "as is", there are only a few simple things we need to do in order to provide an accessible interface for assistive technologies:

Throughout this book we have adhered to most of these rules without explicitly being aware that we were also building accessible-compliant applications. Let's review a bit more about the association of labels with components. Consider the following code:

    JPanel p = new JPanel();
    p.add(new JLabel("IP address:"));
    JTextField user = new JTextField();
    p.add(user);

To make this code accessible we would need to associate the label with the text field above as follows:

    JPanel p = new JPanel();
    JLabel lbl = new JLabel("IP address:");
    lbl.setDisplayedMnemonic('n');
    p.add(lbl);
    JTextField user = new JTextField();
    user.setToolTipText("IP address");
    lbl.setLabelFor(user);
    p.add(user);

This interface declares methods to perform one or more accessible actions, retrieve descriptions of these actions, and find out exactly how many actions have been exposed to assistive technologies.

This interface should be supported by any accessible component that is rendered to a graphical context. It provides the standard mechanism for an assistive technology to determine and assign certain aspects of the graphical representation of that component. Most methods will call the corresponding component’s methods where applicable. (Note that no painting methods are members of this interface because we are expected to define our own look-and-feel if a more customized view is desired.)

This interface provides standard mechanisms for determining and manipulating hyperlinks with an assistive technology. Normally only text components will provide implementations of this interface, however, any other component supporting hypertext may do the same.

This interface should be implemented by any accessible component that has selectable children, whether individually or in groups, such as trees, tables, lists, tabbed panes, menu bars, etc.

This interface should be implemented by any accessible text component, and is intended to provide access to that component’s document content and attributes (where applicable).

This interface should be implemented by any accessible component that supports a numerical value (e.g. a scroll bar). It is intended to be used by an assistive technology to determine and assign current, minimum, and maximum values.

In order to provide accessibility compliance between an application and an assistive technology, we cannot just rely on our use of the accessibility package. We also require support for locating the objects that implement accessibility functionality, as well as support for loading assistive technologies into the Java virtual machine and tracking all events sent to the system event queue. For these reasons, Sun provides the Java Accessibility Utilities which can be downloaded from the JavaSoft web site. Along with utility classes to perform these services, a set of sample applications is included which can be used to test and debug accessible Java programs. These applications are capable of linking with the system event queue and displaying information about selected types of events.

The Java Accessibility Utilities package is an assistive technology itself. To install it we must place the jaccess.jar and jaccess-examples.jar files into our jdk1.2\jre\lib\ext directory.

To use one of its assistive-technology examples, we need to include a string such as the following in our accessibility.properties file:

assistive_technologies=Explorer

This will cause the Explorer utility to start each time we start a new JVM. (Note that if this file does not already exits we must create it ourselves.) In the examples below we assume that you have enabled the Explorer utility, and it is shown in the corresponding example figures.

Let's take a look at how the guidelines for writing an accessible application can be fully adhered to in one of our previous examples: the FTP Client application from chapter 13. As you will see, only minor changes need to be made for full compliance.

<<file figure24-1.gif>>

// Unchanged imports from section 13.5

public class Access1 extends JFrame 
{
  // Unchanged code from section 13.5

  public Access1()
  {
    super("FTP Client [Accessible]");
    getContentPane().setLayout(new BorderLayout());
    
    JPanel p = new JPanel();
    p.setLayout(new DialogLayout2(10, 5));
    p.setBorder(new EmptyBorder(5, 5, 5, 5));

    JLabel lbl = new JLabel("User name:");
    lbl.setDisplayedMnemonic('n');
    p.add(lbl);
    m_txtUser = new JTextField("anonymous");
    m_txtUser.setToolTipText("User name");
    p.add(m_txtUser);
    lbl.setLabelFor(m_txtUser);

    lbl = new JLabel("Password:");
    lbl.setDisplayedMnemonic('p');
    p.add(lbl);
    m_txtPassword = new JPasswordField();
    m_txtPassword.setToolTipText("Password");
    p.add(m_txtPassword);
    lbl.setLabelFor(m_txtPassword);

    lbl = new JLabel("URL:");
    lbl.setDisplayedMnemonic('u');
    p.add(lbl);
    m_txtURL = new JTextField();
    m_txtURL.setToolTipText("URL");
    p.add(m_txtURL);
    lbl.setLabelFor(m_txtURL);

    lbl = new JLabel("File:");
    lbl.setDisplayedMnemonic('l');
    p.add(lbl);
    m_txtFile = new JTextField();
    m_txtFile.setToolTipText("File");
    p.add(m_txtFile);
    lbl.setLabelFor(m_txtFile);

    // Unchanged code from section 13.5

    p.add(new DialogSeparator());
    m_btPut = new JButton("Put");
    m_btPut.setToolTipText("Upload file");
    // Unchanged code from section 13.5
    p.add(m_btPut);

    m_btGet = new JButton("Get");
    m_btGet.setToolTipText("Download file");
    // Unchanged code from section 13.5
    p.add(m_btGet);

    m_btFile = new JButton("File");
    m_btFile.setToolTipText("Select file");
    // Unchanged code from section 13.5
    p.add(m_btFile);

    m_btClose = new JButton("Close");
    m_btClose.setToolTipText("Quit application");
    // Unchanged code from section 13.5
    p.add(m_btClose);

    // Unchanged from section 13.5

At this point you can compile and execute this example. Figure 24.1 shows our FTP Client application and the Explorer accessible utility displaying events generating by that application. Unfortunately we cannot implement actual support for disabled users because no real assistive technologies are currently available.

<<file figure24-2.gif>>

import javax.accessibility.*;

public class Access2 extends JDialog
{
  // added mnemonics and tooltip text to all relevant components
  // ...this class is used to set up a font dialog and has been
  // extracted from code in chapter 20. It requires little 
  // presentation or explanation here.

  public static void main(String argv[]) {
    GraphicsEnvironment ge = GraphicsEnvironment.
      getLocalGraphicsEnvironment();
    m_fontNames = ge.getAvailableFontFamilyNames();
    m_fontSizes = new String[] {"8", "9", "10", "11", "12", "14",
      "16", "18", "20", "22", "24", "26", "28", "36", "48", "72"};

    Access2 dlg = new Access2(new JFrame());
    SimpleAttributeSet a = new SimpleAttributeSet();
    StyleConstants.setFontFamily(a, "Monospaced");
    StyleConstants.setFontSize(a, 12);
    dlg.setAttributes(a);
    dlg.show();
  }
}

class OpenList extends JPanel implements ListSelectionListener, ActionListener
{
  protected JLabel m_title;
  protected JTextField m_text;
  protected JList m_list;
  protected JScrollPane m_scroll;

  public OpenList(String[] data, String title)
  {
    setLayout(null);
    m_title = new OpenListLabel(title, JLabel.LEFT);
    add(m_title);
    m_text = new OpenListText();
    m_text.addActionListener(this);
    m_title.setLabelFor(m_text);
    add(m_text);
    m_list = new OpenListList(data);
    m_list.setVisibleRowCount(4);
    m_list.addListSelectionListener(this);
    m_scroll = new JScrollPane(m_list);
    add(m_scroll);
  }

  public OpenList(String title, int numCols) {
    setLayout(null);
    m_title = new OpenListLabel(title, JLabel.LEFT);
    add(m_title);
    m_text = new OpenListText(numCols);
    m_text.addActionListener(this);
    m_title.setLabelFor(m_text);
    add(m_text);
    m_list = new OpenListList();
    m_list.setVisibleRowCount(4);
    m_list.addListSelectionListener(this);
    m_scroll = new JScrollPane(m_list);
    add(m_scroll);
  }

  public void setToolTipText(String text) {
    super.setToolTipText(text);
    m_title.setToolTipText(text);
    m_text.setToolTipText(text);
    m_list.setToolTipText(text);
  }

  public void setDisplayedMnemonic(char ch) {
    m_title.setDisplayedMnemonic(ch);
  }

  public AccessibleContext getAccessibleContext() {
    if (accessibleContext == null)
      accessibleContext = new AccessibleOpenList();
    return accessibleContext;
  }

  // Unchanged code from section 20.9

  class OpenListLabel extends JLabel {
    public OpenListLabel(String text, int alignment) {
      super(text, alignment);
    }

    public AccessibleContext getAccessibleContext() {
      return OpenList.this.getAccessibleContext();
    }
  }

  class OpenListText extends JTextField
  {
    public OpenListText() {}

    public OpenListText(int numCols) {
      super(numCols);
    }

    public AccessibleContext getAccessibleContext() {
      return OpenList.this.getAccessibleContext();
    }
  }

  class OpenListList extends JList
  {
    public OpenListList() {}

    public OpenListList(String[] data) { super(data); }

    public AccessibleContext getAccessibleContext() {
      return OpenList.this.getAccessibleContext();
    }
  }

  protected class AccessibleOpenList extends AccessibleJComponent 
  {
    public String getAccessibleName() {
      if (accessibleName != null)
        return accessibleName;
      return m_title.getText();
    }

    public AccessibleRole getAccessibleRole() {
      return AccessibleRole.LIST;
    }
  }
}