Edit

How Child IDs Are Used in Parameters

  • Article

This topic describes input parameters, output parameters, and special cases for interpreting child IDs returned from IAccessible methods.

Input Parameters

Many of the Microsoft Active Accessibility functions and most of the IAccessible properties take a VARIANT structure as an input parameter. For most of the IAccessible properties, this parameter allows client developers to specify whether they want information about the object itself or about one of the object's simple elements.

Microsoft Active Accessibility provides the constant CHILDID_SELF to indicate that information is needed about the object itself. To obtain information about a simple element, client developers specify its child ID in the VARIANT parameter.

When initializing a VARIANT parameter, be sure to specify VT_I4 in the vt member in addition to specifying the child ID value (or CHILDID_SELF) in the lVal member.

For example, to get the name of an object, and not one of the object's child elements, initialize the VARIANT for the first parameter of IAccessible::get_accName ( CHILDID_SELF in the lVal member and VT_I4 in the vt member), and then call IAccessible::get_accName.

Output Parameters

Several IAccessible functions and methods have a VARIANT* output parameter that contains a child ID or an IDispatch interface pointer to a child object. There are different steps that a client must take depending on whether they receive a VT_I4 child ID (simple element) or an IDispatch interface pointer with CHILDID_SELF (full object). Following these steps will provide an IAccessible interface pointer and child ID that together allow clients to use the IAccessible methods and properties. These steps apply to the IAccessible::accHitTest, get_accFocus, and get_accSelection methods. They also apply to the AccessibleObjectFromEvent, AccessibleObjectFromPoint, and AccessibleObjectFromWindow client functions.

The following table lists the possible result returned and the required post-processing steps so that clients will have an IAccessible interface pointer and child ID.

Result returned Post-processing for the return value
IDispatch interface pointer This is a full object.Call QueryInterface to access the IAccessible interface pointer.
Use the IAccessible interface pointer with CHILDID_SELF to access IAccessible methods and properties.
VT_I4 child ID Call IAccessible::get_accChild using the child ID to see if you have an IDispatch interface pointer.If you get an IDispatch interface pointer, use it with CHILDID_SELF to access IAccessible interface methods and properties.
If the call to get_accChild fails, you have a simple element. Use the original IAccessible interface pointer (the one you used in your call to the method or function mentioned above) with the VT_I4 child ID that the call returned.

Before you can use a VARIANT parameter, you must initialize it by calling the VariantInit Component Object Model (COM) function. When finished with the structure, call VariantClear to free the memory reserved for that VARIANT.

Special Cases

There are exceptions to the guidelines in the above table, such as when a child ID is returned by the IAccessible::accHitTest method. Servers must return an IDispatch interface if the child is an accessible object. If a child ID is returned by IAccessible::accHitTest, the child is a simple element.

In addition, there are special cases for accNavigate. For more information, see IAccessible::accNavigate and Spatial and Logical Navigation.

Conceptual

IDispatch Interface

VARIANT Structure