How Child IDs Are Used in Parameters
This topic describes input parameters, output parameters, and special cases for interpreting child IDs returned from IAccessible methods.
Many of the Active Accessibility functions and most of the IAccessible properties take a VARIANT 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.
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.
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 childID||Call IAccessible::get_accChild using the childID 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 childID that the call returned.
Before you can use a VARIANT parameter, you must initialize it by calling the VariantInit COM function. When finished with the structure, call VariantClear to free the memory reserved for that VARIANT.
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.