25.6 The Accessibility Utility Classes | Graphic Java 2: Mastering the Jfc, By Geary, 3Rd Edition, Volume 2: Swing

So far, we've seen how the Accessibility APIs help make Swing and AWT components easier to interface with assistive technologies. However, we haven't seen what's available on the other side of the contract. In reality, there are several classes that help assistive technologies interface with the JVM on startup, communicate with accessibility-friendly components, and capture and interpret various system events. These classes are called the accessibility utility classes. They are not part of Swing; instead, they exist as a separate package, com.sun.java.accessibility.util, which is distributed by Sun. (You can download this package from http://java.sun.com/products/jfc/.) The utility classes are crucial to assistive technology developers who wish to create specialized solutions that can communicate with any accessibility-friendly application.

Specifically, the accessibility utility classes can provide assistive technologies with:

A list of the top-level windows of all Java applications currently executing under that virtual machine
Support for locating the window that has input focus
Support for locating the current mouse position
Registration for listening for when top-level windows appear and disappear
The ability to register listeners for and insert events into the windowing event queue

For the purposes of this chapter, we will discuss only the central classes in the Accessibility Utilities API. We begin with the class that allows assistive technologies to bridge the gap in the application's component: EventQueueMonitor.

25.6.1 The EventQueueMonitor Class

The EventQueueMonitor class is, in effect, a gateway to the system event queue. This class provides the central functionality for any assistive technology to capture and interpret system events, monitor the mouse position, and locate components related to screen position. EventQueueMonitor is a subclass of the AWT EventQueue class. This allows it to masquerade as the system event queue for the current JVM. Recall that the system event queue has its own thread, inserting and removing windowing events as necessary. With the EventQueueMonitor class, an application can register listeners for and post events to the system event queue thread a critical task for assistive technologies.

To do this in JDK 1.1,^[1] the EventQueueMonitor must replace the traditional system event queue at startup.

^[1] In JDK 1.2 and higher, the loading of the event queue monitor is not necessary.

Currently, Java allows this to occur only if the following property is set in the awt.properties file:

AWT.EventQueueClass=com.sun.java.accessibility.util.EventQueueMonitor

The class listed must be relative to the current value of the CLASSPATH environment variable. If successfully located, Java instantiates this class (invoking its constructor) and uses it for the windowing event queue.

Some ports of the Java 1.1.x virtual machine do not allow the replacement of the windowing event queue through the awt.properties file. While the Windows and Solaris versions of the JDK follow closely to the reference specification put out by Sun Microsystems for the virtual machine, others may not. If you experience problems with accessibility on your specific port of the JVM, contact the organization that created the port and request that they support this capability. Alternatively, use a newer JVM.

Upon startup, the EventQueueMonitor class also seeks out any assistive technologies by looking for the following entry in the awt.properties file:

#JDK 1.1 AWT.assistive_technologies=com.xxx.SpeechRecognition,com.xxx.Brailer

In JDK 1.2 and higher, you make a similar addition to accessibility.properties:

#JDK 1.2 assistive_technologies=com.xxx.SpeechRecognition,com.xxx.Brailer

Again, the comma-separated list of classes must be relative to the CLASSPATH. When these classes are found, the EventQueueMonitor class instantiates each of them in its own thread.

Note that the EventQueueMonitor class consists almost entirely of static methods. Because there can be only one system event queue per virtual machine, this allows assistive technologies to call upon its methods and access graphical events from any location. If you need to access the EventQueueMonitor object itself, you can always get at it through the Toolkit.getSystemEventQueue( ) method; however, this is rarely necessary.

25.6.1.1 Constructor

public EventQueueMonitor( ): This default constructor is used to create a new instance of an EventQueueMonitor. The JVM invokes this at startup; it shouldn't be invoked by the user.

25.6.1.2 Initialization

In JDK 1.2 and higher, assistive technologies must not register for events before the GUI is ready. These methods allow you to find out when the GUI is ready. (They don't exist in the 1.1 version of accessibility.) As we show in the AssistiveExample class later in this chapter, assistive technologies typically call isGUIInitialized( ); add themselves as a GUIInitializedListener if the GUI isn't initialized; and implement the guiInitialized method (required by the GUIInitializedListener interface), which is called when the GUI is ready. (Although this looks like a typical event registration pattern, no events are actually involved.)

public static void addGUIInitializedListener(GUIInitializedListener c)
public static void removeGUIInitializedListener(GUIInitializedListener c): These methods add or remove a listener from the list of classes that are notified when the GUI subsystem of the JVM is ready to interface with assistive technologies. You should not attempt to register for any GUI events before this has occurred.
public static boolean isGUIInitialized( ): Return a boolean indicating whether the GUI subsystem of the JVM is ready to interface with assistive technologies. You can check this in the constructor of your assistive technology class and, if it is false, register to be notified when it is safe to interface using the addGUIInitializedListener( ) method.

25.6.1.3 Methods

public static void addTopLevelWindowListener(TopLevelWindowListener l): Register a listener method to be invoked if a top-level window is created in the current virtual machine.
public static Accessible getAccessibleAt(Point p): Return the object implementing the Accessible interface that is directly below the point passed in, or null if such an object does not exist. If there is a component available that does not implement the Accessible interface, this method attempts to locate a translator object.
public static Point getCurrentMousePosition( ): Return the current position of the mouse in screen coordinates.
public static Window[] getTopLevelWindows( ): Return an array of each of the top-level windows in the current virtual machine.
public static Window getTopLevelWindowWithFocus( ): Return a reference to the top-level window that has the focus.
protected static void maybeLoadAssistiveTechnologies( ): This protected method performs the task of loading and instantiating any assistive technologies referenced in the awt.properties file in the current thread. If the current virtual machine is JDK 1.2 or greater, this method returns without loading any classes; with JDK 1.2, the Toolkit class has inherited this responsibility.
public void postEvent(AWTEvent theEvent): Queue an AWTEvent to be dispatched in the system event queue.
public static void removeTopLevelWindowListener(TopLevelWindowListener l): Remove a listener method from the top-level window event list.
protected static void queueWindowEvent(WindowEvent e): This protected method queues a specific WindowEvent to be dispatched in the system event queue.

25.6.2 The AWTEventMonitor Class

The EventQueueMonitor works with two other classes to allow assistive technologies to monitor specific events. AWTEventMonitor is one of those classes. This class contains a series of protected listener arrays and allows applications to register listeners for any and all AWT events that pass through the event queue. This is done through static methods inside the class that can be called from anywhere.

25.6.2.1 Constructor

public AWTEventMonitor( ): The default constructor. There is no need for the programmer to invoke it.

25.6.2.2 Methods

public static addActionListener(ActionListener l)
public static removeActionListener(ActionListener l): Add or remove a listener for AWT ActionEvents to or from the monitor.
public static addAdjustmentListener(AdjustmentListener l)
public static removeAdjustmentListener(AdjustmentListener l): Add or remove a listener for AWT AdjustmentEvents to or from the monitor.
public static addComponentListener(ComponentListener l)
public static removeComponentListener(ComponentListener l): Add or remove a listener for AWT ComponentEvents to or from the monitor.
public static addContainerListener(ContainerListener l)
public static removeContainerListener(ContainerListener l): Add or remove a listener for AWT ContainerEvents to or from the monitor.
public static addFocusListener(FocusListener l)
public static removeFocusListener(FocusListener l): Add or remove a listener for AWT FocusEvents to or from the monitor.
public static addItemListener(ItemListener l)
public static removeItemListener(ItemListener l): Add or remove a listener for AWT ItemEvents to or from the monitor.
public static addKeyListener(KeyListener l)
public static removeKeyListener(KeyListener l): Add or remove a listener for AWT KeyEvents to or from the monitor.
public static addMouseListener(MouseListener l)
public static removeMouseListener(MouseListener l): Add or remove a listener for AWT MouseEvents to or from the monitor.
public static addMouseMotionListener(MouseMotionListener l)
public static removeMouseMotionListener(MouseMotionListener l): Add or remove a listener for AWT MouseMotionEvents to or from the monitor.
public static addTextListener(TextListener l)
public static removeTextListener(TextListener l): Add or remove a listener for AWT TextEvents to or from the monitor.
public static addWindowListener(WindowListener l)
public static removeWindowListener(WindowListener l): Add or remove a listener for AWT WindowEvents to or from the monitor.
protected static getComponentWithFocus( ): Return the component that currently has the keyboard focus.

25.6.3 The SwingEventMonitor Class

The SwingEventMonitor extends the AWTEventMonitor class and provides event registration for all Swing events. This class contains a series of protected listener arrays and allows applications to register listeners for any and all AWT and Swing events that pass through the event queue. Note that SwingEventMonitor contains all the functionality of AWTEventMonitor; use this class to gain access to both types of windowing events.

25.6.3.1 Constructor

public SwingEventMonitor( ): The default constructor. There is no need for the programmer to invoke it.

25.6.3.2 Methods

public static addAncestorListener(AncestorListener l)
public static removeAncestorListener(AncestorListener l): Add or remove a listener for Swing AncestorEvents.
public static addCaretListener(CaretListener l)
public static removeCaretListener(CaretListener l): Add or remove a listener for Swing CaretEvents.
public static addCellEditorListener(CellEditorListener l)
public static removeCellEditorListener(CellEditorListener l): Add or remove a listener for Swing CellEditorEvents.
public static addChangeListener(ChangeListener l)
public static removeChangeListener(ChangeListener l): Add or remove a listener for Swing ChangeEvents.
public static addColumnModelListener(TableColumnModelListener l)
public static removeColumnModelListener(TableColumnModelListener l): Add or remove a listener for Swing TableColumnModelEvents.
public static addDocumentListener(DocumentListener l)
public static removeDocumentListener(DocumentListener l): Add or remove a listener for Swing DocumentEvents.
public static addListDataListener(ListDataListener l)
public static removeListDataListener(ListDataListener l): Add or remove a listener for Swing ListDataEvents.
public static addListSelectionListener(ListSelectionListener l)
public static removeListSelectionListener(ListSelectionListener l): Add or remove a listener for Swing ListSelectionEvents.
public static addMenuListener(MenuListener l)
public static removeMenuListener(MenuListener l): Add or remove a listener for Swing MenuEvents.
public static addPopupMenuListener(PopupMenuListener l)
public static removePopupMenuListener(PopupMenuListener l): Add or remove a listener for Swing PopupMenuEvents.
public static addPropertyChangeListener(PropertyChangeListener l)
public static removePropertyChangeListener(PropertyChangeListener l): Add or remove a listener for PropertyChangeEvents.
public static addTableModelListener(TableModelListener l)
public static removeTableModelListener(TableModelListener l): Add or remove a listener for Swing TableModelEvents.
public static addTreeExpansionListener(TreeExpansionListener l)
public static removeTreeExpansionListener(TreeExpansionListener l): Add or remove a listener for Swing TreeExpansionEvents.
public static addTreeModelListener(TreeModelListener l)
public static removeTreeModelListener(TreeModelListener l): Add or remove a listener for Swing TreeModelEvents.
public static addTreeSelectionListener(TreeSelectionListener l)
public static removeTreeSelectionListener(TreeSelectionListener l): Add or remove a listener for Swing TreeSelectionEvents.
public static addUndoableEditListener(UndoableEditListener l)
public static removeUndoableEditListener(UndoableEditListener l): Add or remove a listener for Swing UndoableEditEvents.
public static addVetoableChangeListener(VetoableChangeListener l)
public static removeVetoableChangeListener(VetoableChangeListener l): Add or remove a listener for VetoableChangeEvents.

25.6.4 The TopLevelWindowListener Interface

This is a simple listener that assistive technologies can implement and register with the addTopLevelWindowListener( ) and removeTopLevelWindowListener( ) methods of the EventQueueMonitor class if they want to receive notification when a top-level window is created or destroyed. The interface contains two methods.

25.6.4.1 Methods

public abstract void topLevelWindowCreated(Window w): Invoked when a top-level window has been created.
public abstract void topLevelWindowDestroyed(Window w): Invoked when a top-level window has been destroyed.

25.6.5 The GUIInitializedListener Interface

GUIInitializedListener is a simple interface added in the 1.2 Accessibility package. This interface contains a single method, guiInitialized( ), which is called via the EventQueueMonitor when the GUI subsystem of the JVM is ready to have assistive technologies interface with it (i.e., register event listeners for components).

25.6.5.1 Method

public void guiInitialized( ): Invoked by the EventQueueMonitor when the GUI subsystem has completed initializing itself and is ready to interface with assistive technologies.

This interface is necessary because the GUI subsystem for JDK 1.2 and higher may not be ready to deal with outside technologies by the time the assistive technology is loaded into the virtual machine. Hence, you should always check in the constructor of your assistive technology class to see if the GUI is initialized (using the static method EventQueueMonitor.isGUIInitialized( )). If it isn't, register a class that implements this interface with the EventQueueMonitor.

When the GUI is ready, it invokes this method, and the assistive technology can complete its initialization. (See the example at the end of the chapter for the code to do this.)