AccessibleChildren-Funktion (oleacc.h)

Artikel
03/04/2024

Ruft die untergeordnete ID oder IDispatch jedes untergeordneten Elements innerhalb eines barrierefreien Containerobjekts ab.

Syntax

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

Parameter

[in] paccContainer

Typ: IAccessible*

Zeiger auf die IAccessible-Schnittstelle des Containerobjekts.

[in] iChildStart

Typ: LONG

Gibt den nullbasierten Index des ersten untergeordneten Elements an, das abgerufen wird. Dieser Parameter ist ein Index, keine untergeordnete ID, und er ist in der Regel auf Null (0) festgelegt.

[in] cChildren

Typ: LONG

Gibt die Anzahl der abzurufenden untergeordneten Elemente an. Um die aktuelle Anzahl von untergeordneten Elementen abzurufen, ruft eine Anwendung IAccessible::get_accChildCount auf.

[out] rgvarChildren

Typ: VARIANT*

Zeiger auf ein Array von VARIANT-Strukturen , das Informationen zu den untergeordneten Elementen des Containers empfängt. Wenn das vt-Element eines Arrayelements VT_I4 ist, ist der lVal-Member für dieses Element die untergeordnete ID. Wenn der vt-Member eines Arrayelements VT_DISPATCH ist, ist der pdispVal-Member für dieses Element die Adresse der IDispatch-Schnittstelle des untergeordneten Objekts.

[out] pcObtained

Typ: LONG*

Adresse einer Variablen, die die Anzahl der Elemente im rgvarChildren-Array empfängt , das von der AccessibleChildren-Funktion aufgefüllt wird. Dieser Wert entspricht dem des cChildren-Parameters . Wenn Sie jedoch mehr untergeordnete Elemente anfordern, als vorhanden sind, ist dieser Wert kleiner als der von cChildren.

Rückgabewert

Typ: STDAPI

Gibt bei Erfolg S_OK zurück.

Wenn dies nicht erfolgreich ist, gibt einen der folgenden oder einen anderen COM-Standardfehlercode zurück.

Rückgabecode	Beschreibung
E_INVALIDARG	Ein Argument ist ungültig.
S_FALSE	Die Funktion war erfolgreich, aber es gibt weniger Elemente im rgvarChildren-Array , als untergeordnete Elemente in cChildren angefordert werden.

Hinweise

Um Informationen zu allen untergeordneten Elementen in einem Container abzurufen, muss der iChildStart-Parameter null (0) und cChildren der von IAccessible::get_accChildCount zurückgegebene Wert sein.

Beim Aufrufen dieser Funktion zum Abrufen von Informationen zu den untergeordneten Elementen eines Benutzeroberflächenelements wird empfohlen, dass Clients Informationen zu allen untergeordneten Elementen abrufen. Beispielsweise muss iChildStart null (0) sein, und cChildren muss der von IAccessible::get_accChildCount zurückgegebene Wert sein.

Wenn eine untergeordnete ID für ein Element zurückgegeben wird, muss der Container Informationen über das untergeordnete Element bereitstellen. Um Informationen über das Element zu erhalten, verwenden Clients den IAccessible-Schnittstellenzeiger des Containers und geben die abgerufene untergeordnete ID in Aufrufen der IAccessible-Eigenschaften an.

Clients müssen die IUnknown::Release-Methode für alle IDispatch-Schnittstellen aufrufen, die von dieser Funktion abgerufen werden, und das Array freigeben, wenn es nicht mehr benötigt wird.

Beispiele

Die folgende Beispielfunktion zeigt eine Ansicht der Elementstruktur unterhalb des übergebenen Elements an. Der Name und die Rolle jedes Elements werden von benutzerdefinierten Funktionen ausgegeben, die hier nicht angezeigt werden.


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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	oleacc.h
Bibliothek	Oleacc.lib
DLL	Oleacc.dll
Verteilbare Komponente	Active Accessibility 1.3 RDK unter Windows NT 4.0 mit SP6 und höher und Windows 95

Weitere Informationen

Iaccessible

IDispatch

VARIANTE

Freigeben über