XAccessibleEventListener

OpenOffice.org Developer's Guide

Accessibility

< Previous Section

Next Section >

• Overview
• Bridges
• Accessibility Tree
• Content Information
• Listeners and Broadcasters
• Implementing Accessible Objects
• Using the Accessibility API

• A Simple Screen Reader

• Features
• Class Overview
• Putting the Accessibility Interfaces to Work

• XAccessibleContext
• XAccessibleComponent
• XAccessibleExtendedComponent
• XAccessibleText
• XAccessibleEditableText
• XAccessibleTable
• XAccessibleEventBroadcaster
• XAccessibleEventListener
• XAccessibleSelection
• XAccessibleRelationSet
• XAccessibleStateSet
• XAccessibleValue
• XAccessibleImage
• XAccessibleAction
• XAccessibleKeyBinding
• XAccessibleHypertext
• XAccessibleHyperlink

< Previous Page

Next Page >

The interface com.sun.star.accessibility.XAccessibleEventListener is the counterpart to the accessible event broadcaster, and is called for every change of any accessible object at which it has been registered. The notifyEvent() function is called with an com.sun.star.accessibility.AccessibleEventObject structure. That structure comprises four fields: the EventId field, which is one of the com.sun.star.accessibility.AccessibleEventId constants, describes the type of the event. The object that sent the event is referenced from the Source field. The OldValue and NewValue fields contain event type specific values that contain the changed value before and after the modification took place. The type of content that is expected in the OldValue and NewValue fields is explained together with the AccessibleEventId event types.

The notifyEvent() method of the EventHandler class is not called directly from the accessibility objects. There is an instance of the EventListenerProxy class in between. That class simply forwards the events at the right time and is therefore not explained in more detail here.

  public void notifyEvent (com.sun.star.accessibility.AccessibleEventObject aEvent) {

The one event type that is covered here is the CHILD event, which is sent when a new accessibility object has been created, or an existing one has been removed.

      // Guard against disposed objects.
      try {
          switch (aEvent.EventId) {
              case AccessibleEventId.CHILD:
                  handleChildEvent (
                      objectToContext (aEvent.OldValue),
                      objectToContext (aEvent.NewValue));
                  break;

The handling of the rest of the event types is omitted here to keep this explanation simple.

Again, it is important to guard against the possibility of events arriving after the object they were sent for has been destroyed. For this simple tool, it is sufficient to silently ignore the resulting exception.

          }   
      }
      catch (com.sun.star.lang.DisposedException e) {
      }
  }

Before showing you the actual handling of child events, you can look at the objectToContext() method that is used to convert the OldValue and NewValue fields of the event structure from UNO Anys to XAccessibleContext references. It takes a weakness of the accessibility API IDL specification into account: the type of the content of the Source field is not explicitly stated. As a result, it contains references to both the XAccessible and the XAccessibleContext interfaces. To cope with this, the conversion method first uses the com.sun.star.uno.AnyConverter class to retrieve an XAccessible reference from the event source.

  private XAccessibleContext objectToContext (Object aObject) {
      XAccessibleContext xContext = null;
      XAccessible xAccessible = null;
      try {
          xAccessible = (XAccessible)AnyConverter.toObject(
              new Type(XAccessible.class), aObject);
      }
      catch (com.sun.star.lang.IllegalArgumentException e) {
      }

If that was successful, the accessible context from the object is returned.

      if (xAccessible != null)
          xContext = xAccessible.getAccessibleContext();

If retrieving an XAccessible reference from the event's source field failed, this is repeated directly with the XAccessibleContext interface.

      else
          try {
              xContext = (XAccessibleContext)AnyConverter.toObject(
                  new Type(XAccessibleContext.class), aObject);
          }
          catch (com.sun.star.lang.IllegalArgumentException e) {
          }
      return xContext;
  }

Handling the child event itself is comparably simple: create a new RegistrationThread object that adds (or removes) the listener to the object and all of its children.

  private void handleChildEvent (XAccessibleContext aOldChild, XAccessibleContext aNewChild) {
      if (aOldChild != null)
          // Remove event listener from the child and all of its descendants.
          new RegistrationThread (maListenerProxy, aOldChild, false, false);
      else if (aNewChild != null)
          // Add event listener to the new child and all of its descendants.
          new RegistrationThread (maListenerProxy, aNewChild, true, false);
  }

Content on this page is licensed under the Public Documentation License (PDL).