Using AccessibleObjectFromPoint

[This is preliminary documentation and subject to change.]

Accessibility aids can use the AccessibleObjectFromPoint function to retrieve the address of an object's IAccessible interface. This function accepts three parameters that describe a point on the screen, and two output variables used to state the call's result. The first parameter, ptScreen, is a POINT structure that describes the x- and y-coordinates of the on-screen location to be tested. The second parameter, ppacc, is the address of a variable that will contain an IAccessible interface pointer. The last parameter, pvarChild, is the address of a VARIANT structure that will contain a value that describes the call's result. The vt member is always set to VT_I4, which means that the lVal member contains the value you need. Since it's possible that the item at the point you specified was over a simple element, the value in lVal tells you whether the retrieved interface pointer belongs to an object at the specified point, or to a simple element's parent object. If lVal is nonzero, then the function retrieved an interface pointer to a simple element's parent object; if lVal is zero, then the retrieved interface belongs to the object itself.

AccessibleObjectFromPoint increases the an object's reference count, and must have a corresponding Release(); . Even though an object's reference count is greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Word does with its objects when it quits: As with usual OLE Automation objects, Word will quit and Active Accessibility will CoDisconnect the object so that if anyone tries to access it cross-process after the application quits, OLE will return an error. A reference count on a Active Accessibility object does not reference count the application.

The following code fragment provides an example of how to use the AccessibleObjectFromPoint function.

// For this example, assume that the g_szName variable 
// is defined as a global LPTSTR variable.

// Get the current cursor location.
POINT ptCursor
GetCursorPos(&ptCursor);

// Setup variables for interface pointers and return value.
IUnknown*    punk    = NULL;
IAccessible* pOleAcc = NULL;
HRESULT      hr;
VARIANT      varChild;

// See if there is an accessible object under the cursor.
hr = AccessibleObjectFromPoint(ptCursor, &pOleAcc, &varChild);
if (SUCCEDED(hr)) 
{
    // Query on the object's name.
    BSTR bstrName = NULL;
    hr = pOleAcc->get_accName(varChild, &bstrName);

    // If a name was returned without error,
    // convert it to an OLE Unicode string.
    if (bstrName && SUCCEDED(hr)) 
    {
        WideCharToMultiByte(CP_ACP, 0, bstrName,-1, g_szName,
            cchName, NULL, NULL);
        SysFreeString(bstrName);
    }
}