AccessibleObjectFromEvent

Article
03/28/2008

The AccessibleObjectFromEvent function retrieves the address of the IAccessible interface for the object that generated the event. The event is the one that the client's event hook function is currently processing.

For more information about COM parameter attributes, allocating memory, and freeing memory, see Definitions of Parameter Attributes.

STDAPI AccessibleObjectFromEvent(
HWNDhwnd,DWORDdwObjectID,DWORDdwChildID,IAccessible** ppacc,VARIANT* pvarChild);

Parameters

hwnd
[in] Specifies the window handle to the window that generated the event. This value must be the window handle sent to the event hook function.
dwObjectID
[in] Specifies the object ID of the object that generated the event. This value must be the object ID sent to the event hook function.
dwChildID
[in] Specifies whether an object or one of the object's children generated the event. If dwChildID is CHILDID_SELF, the object triggered the event. If not, dwChildID is the child ID of the element that triggered the event. This value must be the child ID sent to the event hook function.
ppacc
[out] Address of a pointer variable that receives the address of an IAccessible interface for either the object that generated the event or for the parent of the element that generated the event.
pvarChild
[out] Address of a VARIANT structure that specifies the child ID that can be used to access information about the UI element.

Return Values

If successful, returns S_OK.

If not successful, returns the following or another standard COM error code.

Error	Description
E_INVALIDARG	An argument is invalid.

Remarks

Clients call this function within an event hook function to obtain an IAccessible interface pointer to either the object that generated the event or to the parent of the element that generated the event. The parameters sent to the WinEventProc callback function must be used for this function's hwnd, dwObjectID, and dwChildID parameters.

This function retrieves the lowest-level accessible object in the object hierarchy that is associated with an event. If the element that generated the event is not an accessible object (that is, does not support IAccessible), then the function retrieves the IAccessible interface of the parent object. The parent object must provide information about the child element through the IAccessible interface.

As with other IAccessible methods and functions, clients might receive errors for IAccessible interface pointers because of a user action. For more information, see Receiving Errors for IAccessible Interface Pointers.

This function fails if called in response to EVENT_OBJECT_CREATE because the object is not fully initialized. Similarly, clients should not call this in response to EVENT_OBJECT_DESTROY because the object is no longer available and cannot respond. Clients watch for EVENT_OBJECT_SHOW and EVENT_OBJECT_HIDE events rather than for EVENT_OBJECT_CREATE and EVENT_OBJECT_DESTROY.

Example

The following example code shows this method being called in a WinEventProc event handler.

void CALLBACK HandleWinEvent(HWINEVENTHOOK hook, DWORD event, HWND hwnd, 
                             LONG idObject, LONG idChild, 
                             DWORD dwEventThread, DWORD dwmsEventTime)
{
    IAccessible* pAcc = NULL;
    VARIANT varChild;
    HRESULT hr = AccessibleObjectFromEvent(hwnd, idObject, idChild, &pAcc;, &varChild;);  
    if ((hr == S_OK) && (pAcc != NULL))
    {
        // Do something with the accessible object, then release it.        
        // ... 
        pAcc->Release();
    }
}

Requirements

**  Windows NT/2000/XP/Server 2003:** Included in Windows 2000 and later.
**  Windows 95/98/Me:** Included in Windows 98 and later.
**  Redistributable:** Requires Active Accessibility 1.3 RDK on Windows NT 4.0 SP6 and Windows 95.
**  Header:** Declared in Oleacc.h.
**  Library:** Use Oleacc.lib.