XAccessibleContext

From Apache OpenOffice Wiki
Jump to: navigation, search



com.sun.star.accessibility.XAccessibleContext is the central interface of the accessibility API. In addition to the hierarchy information described previously, it provides access to some important information. The functions getAccessibleRole(), getAccessibleName() and getAccessibleDescription() return descriptions of the object in increasing detail:

Role

The role classifies all accessibility objects into a handful of different classes. Most roles are taken from the Java accessibility API, such as PUSH_BUTTON, RADIO_BUTTON, SCROLL_BAR or TEXT. Some have been defined for the accessibility API so that, in addition to GUI elements, documents can be made accessible. These roles are DOCUMENT for document windows or views, PARAGRAPH for text sections, or SHAPE for graphical objects. Roles are described in the com.sun.star.accessibility.AccessibleRole constants group.

Name

Names allow you to distinguish between objects with the same role. For example, the buttons at the bottom of a dialog all have the role PUSH_BUTTON. Their names may be "OK", "Cancel" or "Help". Where necessary, names are made unique with respect to the object's siblings. Names for shapes can be "Rectangle 0", "Ellipse 1", "Rectangle 2", or "Curve 3".

Description

To further describe the purpose of accessibility objects, description strings are provided. Descriptions of shapes can contain their style and some properties whose values differ from that style. If you have changed the color of a rectangle to red, its description may look like "Rectangle with style=default and color=red".

Names and descriptions are strings localized according to the locale returned by getLocale().

Two functions of the interface have not been mentioned so far. The function getAccessibleRelationSet() returns the set of relations defined for an accessibility object. Likewise getAccessibleStateSet() returns a set of states that are active for an object.

Path in the SSR

The showParents() method from the TextualDisplay class of the SSR displays the path from a given object to the root of the accessibility tree by printing each object's accessible name indented relative to its father.

  private String showParents (XAccessibleContext xContext) {
 </source>
The method first obtains references to all the objects that belong to this path.
 <source lang="java">
  Vector aPathToRoot = new Vector();
  while (xContext != null) {
      aPathToRoot.add (xContext);
      // Go up the hierarchy one level to the object's parent.
      try {
          XAccessible xParent = xContext.getAccessibleParent();
          if (xParent != null)
              xContext = xParent.getAccessibleContext();
          else
              xContext = null;
      }
      catch (Exception e) {
          System.err.println ("caught exception " + e + " while getting path to root");
      }
  }

This is done in two steps. First, a call to the getAccessibleParent() method to get the parent of the object and thereby moving to the previous level in the accessibility tree. Second, from the returned XAccessible reference, the accessible context is retrieved by calling getAccessibleContext(). This is repeated until an object is reached that has no parent and getAccessibleParent() returns null.

The path of the accessibility tree is now printed by appending text to the msTextContext member variable, which later is displayed in a JtextArea widget. To cope with accessibility objects that return an empty name, the role of these objects is used to represent them. Note how the indentation string is updated after every object by appending the msIndentation member.

      String sIndentation = new String ();
      for (int i=aPathToRoot.size()-1; i>=0; i--) {
          XAccessibleContext xParentContext = (XAccessibleContext)aPathToRoot.get(i);
          String sParentName = xParentContext.getAccessibleName();
          if (sParentName.length() == 0)
              sParentName = "<unnamed> / Role " 
                  + NameProvider.getRoleName(xParentContext.getAccessibleRole());
          msTextContent += sIndentation + sParentName + "\n";
          sIndentation += msIndentation;
      }

The indentation is returned so that further output can be properly aligned.

      return sIndentation;
  }
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages