AccessibleObjectFromEvent function (oleacc.h)

Article
10/13/2021

Retrieves the address of the IAccessible interface for the object that generated the event that is currently being processed by the client's event hook function.

Syntax

HRESULT AccessibleObjectFromEvent(
  [in]  HWND        hwnd,
  [in]  DWORD       dwId,
  [in]  DWORD       dwChildId,
  [out] IAccessible **ppacc,
  [out] VARIANT     *pvarChild
);

Parameters

[in] hwnd

Type: HWND

Specifies the window handle of the window that generated the event. This value must be the window handle that is sent to the event hook function.

[in] dwId

Type: DWORD

Specifies the object ID of the object that generated the event. This value must be the object ID that is sent to the event hook function.

[in] dwChildId

Type: DWORD

Specifies whether the event was triggered by an object or one of its child elements. If the object triggered the event, dwChildID is CHILDID_SELF. If a child element triggered the event, dwChildID is the element's child ID. This value must be the child ID that is sent to the event hook function.

[out] ppacc

Type: IAccessible**

Address of a pointer variable that receives the address of an IAccessible interface. The interface is either for the object that generated the event, or for the parent of the element that generated the event.

[out] pvarChild

Type: VARIANT*

Address of a VARIANT structure that specifies the child ID that can be used to access information about the UI element.

Return value

Type: STDAPI

If successful, returns S_OK.

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

Return code	Description
E_INVALIDARG	An argument is not valid.

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.

Examples

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

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	oleacc.h
Library	Oleacc.lib
DLL	Oleacc.dll
Redistributable	Active Accessibility 1.3 RDK on Windows NT 4.0 with SP6 and later and Windows 95