XAccessibleEventBroadcaster

From Apache OpenOffice Wiki
Jump to: navigation, search



Most accessible objects need to broadcast events that describe changes of its internal state or visual appearance - this can be done with the com.sun.star.accessibility.XAccessibleEventBroadcasterinterface. If you want to be informed of such changes, you can register a listener with the addEventListener() function, or remove it with removeEventListener().

Documentation caution.png Be sure to cast an object reference to the XAccessibleEventBroadcaster interface before calling these functions, because there are other broadcaster interfaces with functions of the same name.

The SSR registers the event listener in separate threads. The major work is done by a method called traverseTree() that takes an accessible context and traverses the whole tree rooted in this object.

  public long traverseTree (XAccessibleContext xRoot) {
 </source>
After casting the context reference to a reference of the <idls>com.sun.star.accessibility.XAccessibleEventBroadcaster</idls> interface, it either adds or removes the listener <code>maListener</code> at the accessibility object.
 <source lang="java">
      long nNodeCount = 0;
      if (xRoot != null) {
          // Register the root node.
          XAccessibleEventBroadcaster xBroadcaster =
              (XAccessibleEventBroadcaster) UnoRuntime.queryInterface (
                  XAccessibleEventBroadcaster.class, 
                  xRoot);
          if (xBroadcaster != null) {
              if (mbRegister)
                  xBroadcaster.addEventListener (maListener);
              else
                  xBroadcaster.removeEventListener (maListener);
              nNodeCount += 1;
          }

Once the given object is handled, the traversing of the tree continues by calling this method recursively for every child.

          try {
              int nChildCount = xRoot.getAccessibleChildCount();
              for (int i=0; i<nChildCount; i++) {
                  XAccessible xChild = xRoot.getAccessibleChild (i);
                  if (xChild != null)
                      nNodeCount += traverseTree (xChild.getAccessibleContext());
              }
          }

Because the iteration over the direct children of the given accessible context may take a while, there is the possibility that some children do not exist anymore. It is therefore important to catch IndexOutOfBoundsException and DisposedException exceptions. Note that this is not a perfect solution, because children that are added to the given object are not handled properly. A better algorithm would listen to events of the new and removed children of the object to which it was recently registered:

          catch (com.sun.star.lang.IndexOutOfBoundsException aException) {
              // The set of children has changed since our last call to
              // getAccesibleChildCount(). Don't try any further on this
              // sub-tree.
          }
          catch (com.sun.star.lang.DisposedException aException) {
              // The child has been destroyed since our last call to
              // getAccesibleChildCount(). That is OK. Don't try any
              // further on this sub-tree.
          }
      }
      return nNodeCount;
  }

This method keeps track of how many objects it has added to the listener. This number is used in the run() method to write an informative message.

  public void run () {
      System.out.println ("starting registration");
      long nNodeCount = traverseTree (mxRoot);
      System.out.println ("ending registration");
      if (mbShowMessages) {
          if (!mbRegister)
              MessageArea.print ("un");
          MessageArea.println ("registered at " + nNodeCount 
              + " objects in accessibility tree of " + mxRoot.getAccessibleName());
      }
  }
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages