Função AccessibleChildren (oleacc.h)

Recupera a ID filho ou o IDispatch de cada filho dentro de um objeto de contêiner acessível.

Sintaxe

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

Parâmetros

[in] paccContainer

Tipo: IAccessible*

Ponteiro para a interface IAccessible do objeto contêiner.

[in] iChildStart

Tipo: LONG

Especifica o índice baseado em zero do primeiro filho recuperado. Esse parâmetro é um índice, não uma ID filho, e geralmente é definido como zero (0).

[in] cChildren

Tipo: LONG

Especifica o número de filhos a serem recuperados. Para recuperar o número atual de filhos, um aplicativo chama IAccessible::get_accChildCount.

[out] rgvarChildren

Tipo: VARIANT*

Ponteiro para uma matriz de estruturas VARIANT que recebe informações sobre os filhos do contêiner. Se o membro vt de um elemento de matriz for VT_I4, o membro lVal desse elemento será a ID filho. Se o membro vt de um elemento de matriz for VT_DISPATCH, o membro pdispVal desse elemento será o endereço da interface IDispatch do objeto filho.

[out] pcObtained

Tipo: LONG*

Endereço de uma variável que recebe o número de elementos na matriz rgvarChildren que é populada pela função AccessibleChildren . Esse valor é o mesmo do parâmetro cChildren ; no entanto, se você solicitar mais filhos do que o existente, esse valor será menor que o de cChildren.

Retornar valor

Tipo: STDAPI

Se for bem-sucedido, retornará S_OK.

Se não for bem-sucedido, retornará um dos seguintes ou outro código de erro COM padrão.

Código de retorno	Descrição
E_INVALIDARG	Um argumento não é válido.
S_FALSE	A função foi bem-sucedida, mas há menos elementos na matriz rgvarChildren do que os filhos solicitados em cChildren.

Comentários

Para recuperar informações sobre todos os filhos em um contêiner, o parâmetro iChildStart deve ser zero (0) e cChildren deve ser o valor retornado por IAccessible::get_accChildCount.

Ao chamar essa função para obter informações sobre os filhos de um elemento de interface do usuário, é recomendável que os clientes obtenham informações sobre todos os filhos. Por exemplo, iChildStart deve ser zero (0) e cChildren deve ser o valor retornado por IAccessible::get_accChildCount.

Se uma ID filho for retornada para um elemento , o contêiner deverá fornecer informações sobre o elemento filho. Para obter informações sobre o elemento , os clientes usam o ponteiro de interface IAccessible do contêiner e especificam a ID filho obtida em chamadas para as propriedades IAccessible .

Os clientes devem chamar o método IUnknown::Release para quaisquer interfaces IDispatch recuperadas por essa função e liberar a matriz quando ela não for mais necessária.

Exemplos

A função de exemplo a seguir exibe uma exibição da árvore de elementos abaixo do elemento que é passado. O nome e a função de cada elemento são impressos por funções definidas pelo usuário que não são mostradas aqui.

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	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	oleacc.h
Biblioteca	Oleacc.lib
DLL	Oleacc.dll
Redistribuível	Active Accessibility 1.3 RDK no Windows NT 4.0 com SP6 e posterior e Windows 95

Confira também

Iaccessible

IDispatch

VARIANT