IAccessible::accNavigate-Methode (oleacc.h)

Artikel
08/25/2023

Die IAccessible::accNavigate-Methode durchläuft ein anderes UI-Element in einem Container und ruft das Objekt ab. Diese Methode ist optional.

Hinweis Die accNavigate-Methode ist veraltet und sollte nicht verwendet werden. Clients sollten andere Methoden und Eigenschaften wie AccessibleChildren, get_accChild, get_accParent und IEnumVARIANT verwenden.

Syntax

HRESULT accNavigate(
  [in]          long    navDir,
  [in]          VARIANT varStart,
  [out, retval] VARIANT *pvarEndUpAt
);

Parameter

[in] navDir

Typ: long

Gibt die Navigationsrichtung an. Diese Richtung befindet sich in räumlicher Reihenfolge, z. B. links oder rechts oder in logischer Reihenfolge, z. B. weiter oder früher. Dieser Wert ist eine der Navigationskonstanten.

[in] varStart

Typ: VARIANT

Gibt an, ob das Startobjekt der Navigation das Objekt selbst oder eines der untergeordneten Elemente des Objekts ist. Dieser Parameter ist entweder CHILDID_SELF (um mit dem Objekt zu beginnen) oder eine untergeordnete ID (um mit einem der untergeordneten Elemente des Objekts zu beginnen). Weitere Informationen zum Initialisieren von VARIANT finden Sie unter Verwenden untergeordneter IDs in Parametern.

[out, retval] pvarEndUpAt

Typ: VARIANT*

[out, retval] Adresse einer VARIANT-Struktur , die Informationen über das Zielobjekt empfängt. In der folgenden Tabelle werden die in pvarEnd zurückgegebenen Informationen beschrieben.

vt-Member	Wertelement
VT_EMPTY	Keine. Es gab kein UI-Element in der angegebenen Richtung.
VT_I4	lVal enthält die untergeordnete ID des UI-Elements.
VT_DISPATCH	pdispVal enthält die Adresse des IDispatch des UI-Elements.

Rückgabewert

Typ: HRESULT

Gibt bei Erfolg S_OK zurück.

Wenn dies nicht erfolgreich ist, gibt einen der Werte in der folgenden Tabelle oder einen anderen COM-Standardfehlercode zurück. Server geben diese Werte zurück, aber Clients müssen ausgabeparameter immer überprüfen, um sicherzustellen, dass sie gültige Werte enthalten. Weitere Informationen finden Sie unter Überprüfen von IAccessible-Rückgabewerten und Rückgabewerten.

Fehler	BESCHREIBUNG
S_FALSE	Es wurde kein Bildschirmelement in der angegebenen Richtung gefunden.
DISP_E_MEMBERNOTFOUND	Diese Methode wird vom -Objekt nicht unterstützt.
E_INVALIDARG	Ein Argument ist ungültig.

Hinweise

Die räumliche und logische Navigation ist immer auf die Ui-Elemente in einem Container beschränkt. Bei der räumlichen Navigation navigieren Clients nur zu einem gleichgeordneten Des Startobjekts (varStart). Abhängig vom Navigationsflag, das bei der logischen Navigation verwendet wird, navigieren Clients entweder zu einem untergeordneten Element oder zu einem gleichgeordneten Des Startobjekts.

Die accNavigate-Methode ruft Benutzeroberflächenelemente mit einer definierten Bildschirmposition und unsichtbare Objekte ab, die keine definierte Bildschirmposition aufweisen.

Diese Methode ändert die Auswahl oder den Fokus nicht. Verwenden Sie IAccessible::accSelect, um den Fokus zu ändern oder ein Objekt auszuwählen.

Um schleifen beim Durchlaufen von Bildschirmelementen zu verhindern, gibt accNavigate S_FALSE mit VT_EMPTY zurück, wenn Sie NAVDIR_NEXT für das letzte Element oder NAVDIR_PREVIOUS für das erste Element angeben.

Wie bei anderen IAccessible-Methoden und Funktionen erhalten Clients aufgrund einer Benutzeraktion möglicherweise Fehler für IAccessible-Schnittstellenzeiger . Weitere Informationen finden Sie unter Empfangen von Fehlern für IAccessible-Schnittstellenzeiger.

Einige systemdefinierte Ui-Elemente wie Menüs, Menüelemente und Popupmenüs ermöglichen die Navigation zu unsichtbaren Objekten. Andere systemdefinierte UI-Elemente unterstützen dies jedoch nicht. Server können auswählen, ob die Navigation zu unsichtbaren Objekten unterstützt werden soll, und diese entweder überspringen oder verfügbar machen.

Clientanwendungen müssen Post-Process-Rückgabewerte zurückgeben, wenn accNavigate zum Navigieren zwischen Objekten verwendet wird. Das Ziel der Nachverarbeitungsschritte besteht darin, Clients einen IAccessible-Schnittstellenzeiger und eine untergeordnete ID zu geben, damit sie die IAccessible-Methoden und -Eigenschaften für ein UI-Element verwenden können.

In den folgenden Tabellen werden mögliche Szenarien für IAccessible::accNavigate anhand der folgenden Kriterien beschrieben:

Ein definierter Startpunkt (unabhängig davon, ob Sie mit einem vollständigen Objekt oder einem einfachen Element beginnen)
Das zurückgegebene Ergebnis (ein IDispatch oder eine VT_I4 untergeordnete ID)
Die Nachverarbeitung, die Clientanwendungen ausführen müssen, um über einen IAccessible-Schnittstellenzeiger und eine untergeordnete ID zu verfügen

Gehen Sie für diese Tabellen davon aus, dass startID und endID VT_I4 untergeordneten IDs (einfache Elemente) und pStartAcc und pEndAcc mit CHILDID_SELF (vollständige Objekte) VT_I4 werden.

In dieser Tabelle werden die folgenden NAVDIR_-Flags beschrieben: NEXT, PREVIOUS, LEFT, RIGHT, UP und DOWN. Weitere Informationen zu Navigationsflags finden Sie unter Navigationskonstanten.

Startpunkt	Zurückgegebenes Ergebnis	Nachverarbeitung für den Rückgabewert
pStartAcc, startID	VT_I4 endID	Rufen Sie get_accChild auf pStartAcc und übergeben Sie endID. Befolgen Sie die in get_accChild beschriebenen normalen Verfahren.
pStartAcc, startID	VT_DISPATCH pEndAcc	Verwenden Sie die Standardprozeduren zum Konvertieren eines IDispatch-Schnittstellenzeigers in einen IAccessible-Schnittstellenzeiger für pEndAcc.
pStartAcc, CHILDID_SELF	VT_I4 endID	Rufen Sie get_accParent auf pStartAcc auf, und übergeben Sie CHILDID_SELF, um den IAccessible-Schnittstellenzeiger des übergeordneten Elements für endID abzurufen. Rufen Sie dann get_accChild für diesen IAccessible-Schnittstellenzeiger auf, und übergeben Sie endID. Befolgen Sie die in get_accChild beschriebenen normalen Verfahren.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Verwenden Sie die Standardprozeduren zum Konvertieren eines IDispatch-Schnittstellenzeigers in einen IAccessible-Schnittstellenzeiger für pEndAcc.

In der folgenden Tabelle werden Navigationsflags NAVDIR_FIRSTCHILD und NAVDIR_LASTCHILD beschrieben. Es enthält keine Einträge für die Navigation zu einem ersten oder letzten untergeordneten Element, wenn der Startpunkt ein einfaches Element ist, da einfache Elemente keine untergeordneten Elemente haben können.

Startpunkt	Zurückgegebenes Ergebnis	Nachverarbeitung für den Rückgabewert
pStartAcc, CHILDID_SELF	VT_I4 endID	Rufen Sie get_accChild auf pStartAcc auf, und übergeben Sie endID. Befolgen Sie die in get_accChild beschriebenen normalen Verfahren.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Verwenden Sie die Standardprozeduren zum Konvertieren eines IDispatch-Schnittstellenzeigers in einen IAccessible-Schnittstellenzeiger für pEndAcc.

Weitere Informationen finden Sie unter Eigenschaften und Methoden der Objektnavigation.

Serverbeispiel

Das folgende Beispiel zeigt eine mögliche Implementierung der Methode für ein benutzerdefiniertes Listenfeld, dessen Listenelemente untergeordnete Elemente sind.


// m_pControl is the control that returns this accessible object. 
// m_pStdAccessibleObject is the standard accessible object for the window 
//    that contains the control. 

HRESULT STDMETHODCALLTYPE AccServer::accNavigate( 
    long navDir,
    VARIANT varStart,
    VARIANT *pvarEndUpAt)
{
    // Default value. 
    pvarEndUpAt->vt = VT_EMPTY;

    if (varStart.vt != VT_I4)
    {
        return E_INVALIDARG;
    }

    switch (navDir)
    {
    case NAVDIR_FIRSTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = 1;
        }
        else  // Starting with child. 
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_LASTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = m_pControl->GetCount();
        }
        else  // Starting with child.           
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_NEXT:   
    case NAVDIR_DOWN:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal + 1;
            // Out of range. 
            if (pvarEndUpAt->lVal > m_pControl->GetCount())
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

    case NAVDIR_PREVIOUS:
    case NAVDIR_UP:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal - 1;
            // Out of range. 
            if (pvarEndUpAt->lVal <1)
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

     // Unsupported directions. 
    case NAVDIR_LEFT:
    case NAVDIR_RIGHT:
        if (varStart.lVal == CHILDID_SELF)
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        else 
        {
            pvarEndUpAt->vt = VT_EMPTY;
            return S_FALSE;
        }
        break;
    }
    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