Función AccessibleChildren (oleacc.h)

Recupera el identificador secundario o IDispatch de cada elemento secundario dentro de un objeto contenedor accesible.

Sintaxis

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

Parámetros

[in] paccContainer

Tipo: IAccessible*

Puntero a la interfaz IAccessible del objeto contenedor.

[in] iChildStart

Tipo: LONG

Especifica el índice de base cero del primer elemento secundario que se recupera. Este parámetro es un índice, no un identificador secundario, y normalmente se establece en cero (0).

[in] cChildren

Tipo: LONG

Especifica el número de elementos secundarios que se van a recuperar. Para recuperar el número actual de elementos secundarios, una aplicación llama a IAccessible::get_accChildCount.

[out] rgvarChildren

Tipo: VARIANT*

Puntero a una matriz de estructuras VARIANT que recibe información sobre los elementos secundarios del contenedor. Si el miembro vt de un elemento de matriz es VT_I4, el miembro lVal de ese elemento es el identificador secundario. Si el miembro vt de un elemento de matriz es VT_DISPATCH, el miembro pdispVal de ese elemento es la dirección de la interfaz IDispatch del objeto secundario.

[out] pcObtained

Tipo: LONG*

Dirección de una variable que recibe el número de elementos de la matriz rgvarChildren rellenada por la función AccessibleChildren . Este valor es el mismo que el del parámetro cChildren ; Sin embargo, si solicita más elementos secundarios de los que existen, este valor será menor que el de cChildren.

Valor devuelto

Tipo: STDAPI

Si se ejecuta correctamente, devuelve S_OK.

Si no se ejecuta correctamente, devuelve uno de los siguientes u otro código de error COM estándar.

Código devuelto	Descripción
E_INVALIDARG	Un argumento no es válido.
S_FALSE	La función se realizó correctamente, pero hay menos elementos en la matriz rgvarChildren que los elementos secundarios solicitados en cChildren.

Comentarios

Para recuperar información sobre todos los elementos secundarios de un contenedor, el parámetro iChildStart debe ser cero (0) y cChildren debe ser el valor devuelto por IAccessible::get_accChildCount.

Al llamar a esta función para obtener información sobre los elementos secundarios de un elemento de interfaz de usuario, se recomienda que los clientes obtengan información sobre todos los elementos secundarios. Por ejemplo, iChildStart debe ser cero (0) y cChildren debe ser el valor devuelto por IAccessible::get_accChildCount.

Si se devuelve un identificador secundario para un elemento, el contenedor debe proporcionar información sobre el elemento secundario. Para obtener información sobre el elemento, los clientes usan el puntero de interfaz IAccessible del contenedor y especifican el identificador secundario obtenido en las llamadas a las propiedades IAccessible .

Los clientes deben llamar al método IUnknown::Release para las interfaces IDispatch recuperadas por esta función y liberar la matriz cuando ya no sea necesaria.

Ejemplos

La siguiente función de ejemplo muestra una vista del árbol de elementos debajo del elemento que se pasa. El nombre y el rol de cada elemento se imprimen mediante funciones definidas por el usuario que no se muestran aquí.

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;
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	oleacc.h
Library	Oleacc.lib
Archivo DLL	Oleacc.dll
Redistribuible	RDK de accesibilidad activa 1.3 en Windows NT 4.0 con SP6 y versiones posteriores y Windows 95

Consulte también

IAccessible

IDispatch

VARIANT