AccessibleChildren 函数 (oleacc.h)

检索可访问容器对象中每个子级的子 ID 或 IDispatch

语法

HRESULT AccessibleChildren(
  [in]  IAccessible *paccContainer,
  [in]  LONG        iChildStart,
  [in]  LONG        cChildren,
  [out] VARIANT     *rgvarChildren,
  [out] LONG        *pcObtained
);

参数

[in] paccContainer

类型: IAccessible*

指向容器对象的 IAccessible 接口的指针。

[in] iChildStart

类型: LONG

指定检索到的第一个子级的从零开始的索引。 此参数是索引,而不是子 ID,通常设置为零 (0) 。

[in] cChildren

类型: LONG

指定要检索的子级数。 若要检索当前子级的数量,应用程序会调用 IAccessible::get_accChildCount

[out] rgvarChildren

类型: VARIANT*

指向 VARIANT 结构的数组的指针,该数组接收有关容器的子级的信息。 如果数组元素的 vt 成员VT_I4,则该元素的 lVal 成员是子 ID。 如果数组元素的 vt 成员VT_DISPATCH,则该元素的 pdispVal 成员是子对象的 IDispatch 接口的地址。

[out] pcObtained

类型: LONG*

接收由 AccessibleChildren 函数填充的 rgvarChildren 数组中的元素数的变量的地址。 此值与 cChildren 参数的值相同;但是,如果请求的子级多于现有子级,此值将小于 cChildren 的值。

返回值

类型: STDAPI

如果成功,则返回 S_OK。

如果未成功,则返回以下代码之一或另一个标准 COM 错误代码

返回代码 说明
E_INVALIDARG
自变量无效。
S_FALSE
函数成功,但 rgvarChildren 数组中的元素少于 cChildren 中请求的子元素。

注解

若要检索有关容器中所有子项的信息, iChildStart 参数必须为零 (0) ,并且 cChildren 必须是 IAccessible::get_accChildCount 返回的值。

调用此函数以获取有关用户界面元素的子级的信息时,建议客户端获取有关所有子元素的信息。 例如, iChildStart 必须为零 (0 ) ,cChildren 必须是 IAccessible::get_accChildCount 返回的值。

如果为元素返回子 ID,则容器必须提供有关子元素的信息。 为了获取有关 元素的信息,客户端使用容器的 IAccessible 接口指针,并在调用 IAccessible 属性时指定获取的子 ID。

客户端必须为此函数检索的任何 IDispatch 接口调用 IUnknown::Release 方法,并在不再需要该数组时释放它。

示例

以下示例函数在传入的元素下方显示元素树的视图。 每个元素的名称和角色由用户定义函数打印,此处未显示这些函数。


HRESULT WalkTreeWithAccessibleChildren(IAccessible* pAcc, int depth)
{
    HRESULT hr;
    long childCount;
    long returnCount;

    if (!pAcc)
    {
        return E_INVALIDARG;
    }
    hr = pAcc->get_accChildCount(&childCount);
    if (FAILED(hr))
    {
        return hr;
    };
    if (childCount == 0)
    {
        return S_FALSE;
    }
    VARIANT* pArray = new VARIANT[childCount];
    hr = AccessibleChildren(pAcc, 0L, childCount, pArray, &returnCount);
    if (FAILED(hr))
    {
        return hr;
    };

    // Iterate through children.
    for (int x = 0; x < returnCount; x++)
    {
        VARIANT vtChild = pArray[x];
        // If it's an accessible object, get the IAccessible, and recurse.
        if (vtChild.vt == VT_DISPATCH)
        {
            IDispatch* pDisp = vtChild.pdispVal;
            IAccessible* pChild = NULL;
            hr = pDisp->QueryInterface(IID_IAccessible, (void**) &pChild);
            if (hr == S_OK)
            {
                for (int y = 0; y < depth; y++)
                {
                    printf("  ");
                }
                PrintName(pChild, CHILDID_SELF);
                printf("(Object) ");
                PrintRole(pChild, CHILDID_SELF);
                WalkTreeWithAccessibleChildren(pChild, depth + 1);
                pChild->Release();
            }
            pDisp->Release();
        }
        // Else it's a child element so we have to call accNavigate on the parent,
        //   and we do not recurse because child elements can't have children.
        else
        {
            for (int y = 0; y < depth; y++)
            {
                printf("  ");
            }
            PrintName(pAcc, vtChild.lVal);
            printf("(Child element) ");
            PrintRole(pAcc, vtChild.lVal);
        }
    }
    delete[] pArray;
    return S_OK;
}

要求

要求
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 oleacc.h
Library Oleacc.lib
DLL Oleacc.dll
可再发行组件 具有 SP6 及更高版本和 Windows 95 的 Windows NT 4.0 上的 Active Accessibility 1.3 RDK

另请参阅

IAccessible

IDispatch

VARIANT