MSHTML Accessibility Features

Microsoft® Active Accessibility™ is based on the Component Object Model (COM), which defines a common way for applications and operating systems to communicate. Using Active Accessibility, applications, referred to as servers, provide information about the content of the computer screen that is within their control. Accessibility aids use Active Accessibility to obtain information about the user interface of other applications and the operating system.

Any application that uses Active Accessibility to gain information about objects is considered a client. Typically, clients are accessibility aids, such as screen readers, screen enlargement utilities for low-vision users, and speech recognition utilities. However, Active Accessibility provides technology useful to many types of applications - for example, applications that automate or provide visual/audio response to user interaction.

To implement an Active Accessibility client, you obtain an accessible applications IAccessible interface and call its methods.

This article describes how Active Accessibility works with Microsoft® Internet Explorer 4.01 and later. It supplements the information provided in the Active Accessibility SDK , which contains important information, utilities and samples.

Accessible Objects and Child Elements in an HTML Document

Accessible 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 accessibilty hierarchy exposed by MSHTML:

HTML tags that support Active Accessibility are included in the accessibility hierarchy. A list of the accessible HTML tags supported by Internet Explorer 4.01 and later can be found in DHTML Accessibility.
HTML elements can be made accessible by setting the TABINDEX attribute to greater than zero.
Nonaccessible HTML tags are excluded from the accessibility hierarchy.
Contained text is exposed as one or more child elements.
Scoped HTML tags, which consist of start and end tags, have a parent relationship with their contained content, which can include accessible tags, nonaccessible tags and/or text.
Scoped HTML tags that are non-accessible, such as B and SPAN, cause additional child elements to be created for their contained text. Any custom tags not part of the HTML standard also create child elements.

The following HTML example demonstrates how non-accessible HTML tags affect how contained text is used to create child elements.

<HTML><BODY>Here is some <B>bold text</B></BODY></HTML>

The B element is not an accessible element but has been used by the author 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 is dependent on attributes used in the HTML tag, or user selection and focus.

The values returned from IAccessible::get_accRole and IAccessible::get_accDefaultAction are independent of attributes and user interaction, and are listed here for each element.

Element	Role	Default action
document	ROLE_SYSTEM_CLIENT	none
A	ROLE_SYSTEM_LINK	jump
AREA	ROLE_SYSTEM_LINK	jump
BODY	ROLE_SYSTEM_PANE	none
BUTTON INPUT TYPE=BUTTON INPUT TYPE=RESET INPUT TYPE=SUBMIT	ROLE_SYSTEM_PUSHBUTTON	press
FRAME/IFRAME	ROLE_SYSTEM_CLIENT	none
IMG	ROLE_SYSTEM_GRAPHIC ROLE_SYSTEM_ANIMATION	jump (parent is anchor)
INPUT TYPE=CHECKBOX	ROLE_SYSTEM_CHECKBOX	check uncheck
INPUT TYPE=IMAGE	ROLE_SYSTEM_PUSHBUTTON	press
INPUT TYPE=PASSWORD	ROLE_SYSTEM_TEXT	none
INPUT TYPE=RADIO	ROLE_SYSTEM_RADIO	select
MARQUEE	ROLE_SYSTEM_ANIMATION	none
OBJECT APPLET EMBED	ROLE_SYSTEM_CLIENT (depends on embedded content)	select
SELECT	ROLE_SYSTEM_COMBOBOX ROLE_SYSTEM_DROPLIST ROLE_SYSTEM_LIST	select
TABLE	ROLE_SYSTEM_TABLE	none
TD TH	ROLE_SYSTEM_CELL	none
TEXTAREA INPUT TYPE=TEXT INPUT TYPE=TEXTAREA	ROLE_SYSTEM_TEXT	none
TextRange	ROLE_SYSTEM_TEXT (read-only)	jump (parent is anchor)

For more information about the descriptive properties available from accessible objects created by MSHTML, please refer to the Active Accessibility SDK documentation. Consider using the Accessible Explorer utility, provided with the Active Accessibility SDK, to explore the values returned by each element.

Hierarchical Navigation

An Active Accessibility client can traverse the MSHTML accessibility hierarchy by calling IAccessible::get_accParent, IAccessible::get_accChild, and IAccessible::get_accChildCount. For tools and samples that traverse an accessibility hierarchy, please refer to the Active Accessibility SDK .

MSHTML does not currently implement the IEnumVARIANT interface that is used by some Active Accessibility servers to provide an alternative way of exposing collections of accessible objects.

Logical Navigation

Active Accessibility enables applications to programmatically move the user focus between accessible objects in response to user actions. An Active Accessibility client navigates between accessible objects by calling IAccessible::accNavigate. MSHTML provides support for the following navigation constants:

NAVDIR_FIRSTCHILD	Navigate to the first child of this accessible object.
NAVDIR_LASTCHILD	Navigate to the last child of this accessible object.
NAVDIR_NEXT	Navigate to the next accessible object.
NAVDIR_PREVIOUS	Navigate to the previous accessible object.

Hit Testing and Screen Location

Active Accessibility enables identification of the accessible HTML element at a given point on the screen.

There are two approaches to hit testing:

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

Call IAccessibility::accHitTest to test if an accessible object or child element was hit. The following pvarID values are passed by the MSHTML implementation of accHitTest:

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

IAccessibility::accHitTest uses a single-step hit testing mechanism, so this method must be called on each child object interface pointer that is returned, until CHILD_SELF or a child ID is returned. If the ID is CHILD_SELF, this accessible object is at the specified location; otherwise, it is a child element specified by the child ID.

Accessing the HTML Document

If the Active Accessibility client requires additional information about an HTML page, it can access HTML elements through the DHTML Object Model. This is done by sending the WM_HTML_GETOBJECT window message to an Internet Explorer window that has the class name of "Internet Explorer_Server". The result returned by this message can then be passed to the Active Accessibility ObjectFromLresult function to obtain a marshalled IHTMLDocument2 interface pointer for the contained document.

The following C++ code demonstrates how to obtain the IHTMLDocument2 interface for the document of the top-most window in Internet Explorer.

#include <mshtml.h>
...
void GetIHTMLDocument2(IHTMLDocument2** ppDoc) 
{
    *ppDoc = NULL;

    // Register WM_HTML_GETOBJECT message
    UINT nMsg = RegisterWindowMessage( _T("WM_HTML_GETOBJECT") );

    // Load the Active Accessibility library
    HINSTANCE hInst = LoadLibrary( _T("OLEACC.DLL") );
    if ( hInst != NULL )
    {
        HRESULT (STDAPICALLTYPE* pfObjectFromLresult)
                (LRESULT, REFIID, WPARAM, void**);

        pfObjectFromLresult = (LPOBJECTFROMLRESULT)
                              GetProcAddress( hInst, _T("ObjectFromLresult") );
        if ( pfObjectFromLresult != NULL )
        {
            // Locate the top-level Internet Explorer window
            // Note: May be more than one instance running
            HWND hWnd = FindWindow( _T("IEFrame"), NULL );
            if ( hWnd != NULL )
            {
                HWND hWndChild=NULL;

                // Locate the child document window
                // Note: May be more than one if using frames
                hWndChild = FindWindowEx( hWnd, NULL,
                                          _T("Shell DocObject View"), NULL );
                if ( hWndChild )
                    hWndChild = FindWindowEx( hWndChild, NULL,
                                              _T("Internet Explorer_Server"), NULL );
                if ( hWndChild )
                {
                    LRESULT lRes;
            
                    // Send WM_HTML_GETOBJECT to document window
                    SendMessageTimeout( hWndChild, nMsg, 0L, 0L,
                                        SMTO_ABORTIFHUNG, 1000, (DWORD*)&lRes );

                    HRESULT hr = (*pfObjectFromLresult)
                                 ( lRes, IID_IHTMLDocument, 0, (void**)ppDoc );
                } // else document not ready
            } // else Internet Explorer is not running
        }
        FreeLibrary( hInst );
    } // else Active Accessibility is not installed
}

This sample code assumes that CoInitialize has been called in the client application.

Note that FindWindow will find the first occurrence of a window, so consider allowing for multiple instances of Internet Explorer. Also, for pages which contain frames, there will be multiple documents so consider traversing the window hierarchy to find all document windows.

Performance Tips and Tricks

The following suggestions may improve performance in your Active Accessibility client.

Consider using a second thread to wait for the EVENT_OBJECT_CREATE event to be fired. This enables the Active Accessibility client to present its user interface without waiting for the server to build the accessibility hierarchy.
Consider caching information retrieved from hit testing, when calling IAccessible::accHitTest, to avoid multiple visits to the accessibility hierarchy.
Remember to release all IDispatch interface pointers returned by Active Accessibility methods.
When your Active Accessibility client receives the EVENT_OBJECT_DESTROY event it can release all resources relating to the current window.
Nonvisible HTML elements are included in the accessibility hierarchy. 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. MSHTML fires the EVENT_OBJECT_STATECHANGE event when an element's visibility is changed through script, but not if the change resulted from a user resizing the window.
Consider using Internet Explorer 5, which uses native Active Accessibility support to provide better performance.