About Active Accessibility Support

This article provides an overview of Microsoft Active Accessibility SDK support provided by the MSHTML component of Windows Internet Explorer.

• Prerequisites and Requirements
• Accessibility Aid Background
• Active Accessibility in Internet Explorer 4.01 and Later
• Accessible HTML Elements
  • Making Nonaccessible Elements Accessible
• Accessibility Behaviors
• Accessible HTML Events
• Accessible Objects and Child Elements in an HTML Document
• Accessibility Hierarchy
• Accessible Object Properties
• Hierarchical Navigation
• Logical Navigation
• Hit Testing
• Accessing the Internet Explorer Object Associated with an Accessible Object
• Performance Tips
• Related topics

Accessibility aids are applications that help people with disabilities use computers. Active Accessibility enables accessibility aids to communicate with the operating system and other applications through a common interface. The Active Accessibility API supports the integration of accessibility aids with accessibility-aware applications.

There are two types of accessibility aids. One type magnifies information on a screen or provides audio interpretations of text and other visual elements. These accessibility aids benefit users who have limited vision or are blind. The other type includes hardware and software tools that support users who have limited dexterity, enabling them to use different keyboard driver software and alternative input devices—something other than a keyboard or a mouse.

Active Accessibility supports HTML through the MSHTML dynamic-link library that is included with Microsoft Internet Explorer 4.01 and later.

The Windows Software Development Kit (SDK) in the MSDN Online Library contains an overview of Active Accessibility, as well as the complete API reference. This Active Accessibility API reference documents the IAccessible interface and Active Accessibility events, as well as the rest of the Active Accessibility object model. Samples and tutorials are also included in the Microsoft Windows Software Development Kit (SDK).

Prerequisites and Requirements

This documentation assumes that you are familiar with Microsoft Win32 programming. You should also be familiar with Component Object Model (COM) programming.

To compile C/C++ programs that use the functionality provided by Active Accessibility, be sure that the Oleacc.h header file is in the include directory of your compiler. Because the interface to the accessible objects implements the IDispatch interface, Active Accessibility methods also can be implemented by Microsoft Visual Basic-based applications.

Accessibility Aid Background

Supporting Active Accessibility in your applications enables everyone to use your software, including an estimated 50,000,000 users with disabilities.

Before the introduction of Active Accessibility, accessibility aid developers had to use cryptic hook mechanisms or creatively work around the operating system in an attempt to obtain the information they needed. Generally, the developers succeeded, but their applications relied on implementation details that might change with each version of the operating system.

Using COM technology, Active Accessibility provides a way to create high-performance, reliable tools—enabling applications and accessibility aids to work together in helping users with special needs. Active Accessibility provides a comprehensive object model that includes the interfaces, libraries, and other elements that eliminate the need for unreliable workarounds.

Active Accessibility in Internet Explorer 4.01 and Later

The MSHTML component in Internet Explorer 4.01 supports the Microsoft Active Accessibility Proxy for HTML, or HTML Proxy. The HTML Proxy communicates with MSHTML through object model interfaces and events to provide an accessible representation of the content of a webpage.

The MSHTML component in Microsoft Internet Explorer 5 and later exposes a native implementation of Active Accessibility, replacing the HTML Proxy. Native implementation of Active Accessibility has resulted in significant performance gains, particularly with larger webpages. This implementation is also more robust when compared with the HTML Proxy implementation. Internet Explorer 5 and later provides these gains in performance and stability.

Accessible HTML Elements

Applications support Active Accessibility by exposing their user interface (UI) elements to client applications. These UI elements are presented to client applications in the form of accessible objects. Accessible objects maintain pieces of information, called properties, that describe the object's appearance, nature, and purpose. The IAccessible interface extends methods that enable an accessibility aid client to retrieve these properties. Using the information that these properties provide, accessibility aids can obtain information valuable to the user, and can convey it to the user as needed. MSHTML supports Active Accessibility by exposing HTML elements to client accessibility aids.

Some HTML elements—images, text, and links—are accessible, and some are not. Being accessible means that each instance of that element in an HTML document has an accessible representation of its own in the document's accessibility hierarchy.

Making Nonaccessible Elements Accessible

Elements that are not accessible are ignored and excluded from the document's accessibility hierarchy. These elements are treated as breaking points for the text stream that represents the data in the HTML document. They are treated as children of the element that contains them.

By themselves, accessible elements do not provide a complete solution to authoring accessible webpages. With Internet Explorer 5, any element that has a tabIndex property with a value greater than zero can be considered accessible. Microsoft Internet Explorer 5.01 and later extends this functionality. If the tabIndex property is set, regardless of its value, the element will be included in the accessibility hierarchy.

MSHTML allows the user to press the TAB key to move to elements on the page that can receive focus. MSHTML sends out the appropriate EVENT_OBJECT_FOCUS event. An Active Accessibility client can use AccessibleObjectFromEvent to get information about the child element that was focused.

Accessibility Behaviors

When an accessible object is requested for an element, if the element has an element behavior, the application first checks to determine whether the behavior has implemented accessibility support. If the behavior has accessibility support, accessibility queries are delegated to the behavior. However, when the behavior returns an error code this is sent to the client. If the behavior returns an E_NOTIMPL error code Active Accessibility tries to substitute another element.

Accessible HTML Events

MSHTML fires certain accessibility events as a result of object model events. The following table shows these events and their corresponding Active Accessibility counterparts.

If an accessibility client starts after MSHTML has started, these events enable the client to connect to the Active Accessibility implementation for MSHTML and start exposing content. Each event contains a window handle and a reference value, indicating the window and the element in the window for which the event is being fired. For the window itself, the unique identifier is zero. For all other elements, the reference contains the element's unique identifier, even though all events contained the same window handle when they fired. Later, the client application calls back to the Active Accessibility system components with the window handle and the reference number. Active Accessibility then communicates the unique identifier of that element to the MSHTML implementation.

Accessible Objects and Child Elements in an HTML Document

MSHTML is the component of Internet Explorer that parses an HTML file and renders the webpage to the user's display. In addition to exposing the object model that represents the HTML elements on a webpage, MSHTML exposes accessible objects through the Active Accessibility IAccessible interface.

This section discusses the relationship between HTML elements and their respective accessible objects.

Accessibility Hierarchy

The MSHTML component of Internet Explorer exposes accessible HTML elements as a hierarchy of accessible objects. Each accessible object implements the IAccessible interface and provides information about itself and its child elements. The following conditions determine the accessibility hierarchy exposed by MSHTML.

• HTML elements that support Active Accessibility are included in the accessibility hierarchy and are exposed as accessible objects.
• HTML elements are made accessible by setting the tabIndex attribute to a value greater than zero. Note   For Internet Explorer 5.01 and later, the attribute may be set to any value.
• Nonaccessible HTML elements are excluded from the accessibility hierarchy.
• Text contained within HTML elements is exposed as one or more child elements. Child elements do not implement the IAccessible interface and are accessed through the parent accessible object.
• Scoped HTML elements consist of start and end tags (for example, <div>...</div>) and have a parent-child relationship with their content. This content can include accessible elements, nonaccessible elements, and/or text.
• Scoped HTML elements that are nonaccessible, such as strong and span, create additional child elements for any contained text. Any custom tags that are not part of the HTML standard also create child elements.
• Accessible HTML elements that are invisible are included in the accessibility hierarchy. See About Invisible Objects for more information.

The following HTML example shows how nonaccessible HTML elements determine the way in which contained text is used to create child elements.

<html><body>Here is some <strong>bold text</strong></body></html>

The strong element is a nonaccessible element and is used to distinguish a portion of the text. The resulting accessibility hierarchy consists of an accessible object representing the body element and two child elements. The accessibility hierarchy is as follows.

body (accessible object)
 + "Here is some " (child element)
 + "bold text" (child element)

Accessible Object Properties

Each accessible object provides additional information through descriptive properties, as defined by the IAccessible interface. The value of some of these properties depends on the attributes used in the HTML element or user selection and focus. The property, returned from the IAccessible::get_accRole method, describes the user interface role of an accessible object. The following table lists the values returned by MSHTML for each HTML element.

For more information about descriptive properties and the role constants, see the Microsoft Active Accessibility SDK documentation.

Note  To explore the available values of descriptive properties for each element, use the Internet Explorer tool provided with the Active Accessibility Software development kit (SDK).

Hierarchical Navigation

An accessibility aid can navigate the MSHTML accessibility hierarchy by calling the IAccessible::get_accParent, IAccessible::get_accChild, and IAccessible::get_accChildCount methods. For tools and samples that navigate an accessibility hierarchy, see the Microsoft Active Accessibility SDK.

Note  MSHTML does not currently implement the IEnumVariant as an alternative way of accessing collections of accessible objects.

Logical Navigation

Applications can use Active Accessibility to move the user focus between accessible objects in response to user actions. For example, an accessibility aid might enable the user to tab between controls by using an input device. An accessibility aid navigates between accessible objects by calling the IAccessible::accNavigate method. MSHTML supports the following navigation constants.

Hit Testing

Applications can use Active Accessibility to identify the accessible objects and child elements at a given screen location. For example, an accessibility aid can improve visibility by magnifying the area under the cursor. There are two approaches to this technique, which is known as hit testing:

• Call AccessibleObjectFromPoint to obtain an IAccessible interface for the lowest-level accessible object at a given point.

• Call IAccessible::accHitTest to test whether an accessible object or child element is hit. The following identifiers are returned by the MSHTML implementation of IAccessible::accHitTest.

  VARIANT type	Value	Location
  VT_I4	CHILD_SELF	Within the accessible object, but not within any child element or accessible object.
  VT_I4	ID of child	Within a child element.
  VT_DISPATCH	IDispatch interface of accessible object	Within a child accessible object.
  VT_EMPTY	None	Outside the accessible object.

   

  The IAccessible::accHitTest method should be called on each child object interface pointer that is returned until CHILD_SELF or a child identifier is returned. If the identifier is a value of CHILD_SELF, the accessible object was hit; otherwise, a child element specified by the child identifier was hit.

Accessing the Internet Explorer Object Associated with an Accessible Object

1. Step 1:

   Acquire an IAccessible pointer to an element within the page or the accessible window of the document. For example, get the IAccessible interface of any object coming from the window class named "Internet Explorer_Server".

2. Step 2:

   Get an IServiceProvider interface pointer for the accessible object you obtained.

   HRESULT hr;
   hr = pAcc->QueryInterface(IID_IServiceProvider, (void **)&pSP);
   

3. Step 3:

   The object obtained by steps 1 and 2 can be an element or a window. In either case, use the following code to access an Internet Explorer object model object.

   HRESULT hr;
   IHTMLWindow2 * pWindow;
   IHTMLElement * pElement;
   hr = pSP->QueryService(IID_IHTMLWindow2, IID_IHTMLWindow2, 
      (void **)&pWindow);
   if (FAILED(hr))
      hr = pSP->QueryService(IID_IHTMLElement, IID_IHTMLElement, 
      (void **)&pElement);
   
   // Release the Service Provider interface pointer.
   pSP->Release();
   
   if (SUCCEEDED(hr))
   {
      // Either a window or an element pointer was returned.
      assert( pWindow || pElement);
      ....
      code here...
      // Release the pointers.
      if (pElement)
         pElement->Release();
      if (pWindow)
         pWindow->Release();
   }
   

In the preceding sample, the IServiceProvider::QueryService calls use the same IID values for the service GUID (first parameter) and the interface IID (second parameter). If IServiceProvider::QueryService returns a window and there is an IID_IHTMLWindow2, process the IID as a QueryInterface call to the window. You can request whatever interface you want in the IID. If the object implements the interface, you will obtain a pointer. The first GUID is used to filter objects so that the caller can determine what kind of object was obtained—an element or a window. This direct delegation saves the application time. If the application has already checked the role property on the IAccessible and found it to be a window object that requires an IUnknown or IHTMLWindow3, not an IHTMLWindow2, the call should pass IID_IUnknown or IID_IHTMLWindow3 as the second parameter.

Performance Tips

You can use the following suggested tips to improve performance in your accessibility aid:

• Consider using a second thread to handle the EVENT_OBJECT_CREATE event. This enables the accessibility aid to present its user interface without waiting for the server to build the accessibility hierarchy.
• When calling the IAccessible::accHitTest method, consider caching information retrieved from hit testing to avoid multiple visits to the accessibility hierarchy.
• Prevent unnecessary memory and resource usage by releasing all IDispatch interface pointers returned by Active Accessibility methods.
• Consider releasing all resources relating to the current window when your accessibility aid receives the EVENT_OBJECT_DESTROY event.
• Ignore accessible objects that are not visible. You can check the current state of an accessible object by calling IAccessible::get_accState. The object is invisible if the state is STATE_SYSTEM_INVISIBLE or STATE_SYSTEM_OFFSCREEN. MSHTML fires the EVENT_OBJECT_STATECHANGE event when an element's visibility is changed through script, but not if the user resized the window. For more information, see About Invisible Objects.
• Consider using Internet Explorer 5, which has native Active Accessibility support and provides better performance.

In Microsoft Internet Explorer 6 and later, the pvarState parameter of the IAccessible::get_accState property receives SYSTEM_STATE_OFFSCREEN when an object is invisible because of scrolling.

Related topics

Microsoft Active Accessibility