Metodo IAccess::accNavigate (oleacc.h)

Articolo
02/29/2024

Il metodo IAccess::accNavigate attraversa un altro elemento dell'interfaccia utente all'interno di un contenitore e recupera l'oggetto. È facoltativo.

Nota Il metodo accNavigate è deprecato e non deve essere usato. I client devono usare altri metodi e proprietà, ad esempio AccessibleChildren, get_accChild, get_accParent e IEnumVARIANT.

Sintassi

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

Parametri

[in] navDir

Tipo: long

Specifica la direzione da esplorare. Questa direzione è in ordine spaziale , ad esempio a sinistra o destra, o ordine logico , ad esempio successivo o precedente. Questo valore è una delle costanti di spostamento.

[in] varStart

Tipo: VARIANT

Specifica se l'oggetto iniziale della navigazione è l'oggetto stesso o uno degli elementi figlio dell'oggetto. Questo parametro è CHILDID_SELF (da iniziare dall'oggetto) o da un ID figlio (per iniziare da uno degli elementi figlio dell'oggetto). Per altre informazioni sull'inizializzazione di VARIANT, vedere Come vengono usati gli ID figlio nei parametri.

[out, retval] pvarEndUpAt

Tipo: VARIANT*

[out, retval] Indirizzo di una struttura VARIANT che riceve informazioni sull'oggetto di destinazione. La tabella seguente descrive le informazioni restituite in pvarEnd.

membro vt	Membro valore
VT_EMPTY	Nessuno. Non c'era alcun elemento dell'interfaccia utente nella direzione specificata.
VT_I4	lVal contiene l'ID figlio dell'elemento ui.
VT_DISPATCH	pdispVal contiene l'indirizzo dell'elemento IDispatch dell'interfaccia utente.

Valore restituito

Tipo: HRESULT

Se ha esito positivo, restituisce S_OK.

In caso contrario, restituisce uno dei valori della tabella che segue o un altro codice di errore COM standard. I server restituiscono questi valori, ma i client devono sempre controllare i parametri di output per assicurarsi che contengano valori validi. Per altre informazioni, vedere Controllo dei valori restituiti IAccessibile e valori restituiti.

Errore	Descrizione
S_FALSE	Nessun elemento dello schermo trovato nella direzione specificata.
DISP_E_MEMBERNOTFOUND	L'oggetto non supporta questo metodo.
E_INVALIDARG	Un argomento non è valido.

Commenti

Lo spostamento, sia spaziale che logico, è sempre limitato agli elementi dell'interfaccia utente all'interno di un contenitore. Con lo spostamento spaziale, i client passano solo a un elemento di pari livello dell'oggetto iniziale (varStart). A seconda del flag di spostamento usato con lo spostamento logico, i client passano a un elemento figlio o a un elemento di pari livello dell'oggetto iniziale.

Il metodo accNavigate recupera gli elementi dell'interfaccia utente che hanno una posizione dello schermo definita e oggetti invisibili che non hanno una posizione dello schermo definita.

Questo metodo non modifica la selezione o lo stato attivo. Per modificare lo stato attivo o per selezionare un oggetto, usare IAccess::accSelect.

Per evitare l'attraversamento degli elementi dello schermo, accNavigate restituisce S_FALSE con VT_EMPTY quando si specifica NAVDIR_NEXT sull'ultimo elemento o NAVDIR_PREVIOUS sul primo elemento.

Come per altri metodi e funzioni IAccessi , i client potrebbero ricevere errori per i puntatori di interfaccia IAccessi a causa di un'azione utente. Per altre informazioni, vedere Ricezione di errori per i puntatori dell'interfaccia IAccessibile.

Alcuni elementi dell'interfaccia utente definiti dal sistema, ad esempio menu, voci di menu e menu popup consentono la navigazione agli oggetti invisibili. Tuttavia, altri elementi dell'interfaccia utente definiti dal sistema non supportano questa operazione. I server possono scegliere se supportare lo spostamento a oggetti invisibili e possono ignorarli o esponerli.

Le applicazioni client devono restituire valori restituiti dopo il processo quando si usa accNavigate per spostarsi tra oggetti. L'obiettivo dei passaggi di post-elaborazione consiste nel fornire ai client un puntatore dell'interfaccia IAccessibile e un ID figlio in modo che possano usare i metodi e le proprietà IAccessi per un elemento dell'interfaccia utente.

Le tabelle seguenti descrivono gli scenari possibili per IAccess::accNavigate, in base ai criteri seguenti:

Punto di partenza definito (se si inizia con un oggetto completo o un elemento semplice)
Risultato restituito (un ID IDispatch o un ID figlio VT_I4)
Il post-elaborazione che le applicazioni client dovranno eseguire per avere un puntatore dell'interfaccia IAccessibile e un ID figlio

Per queste tabelle si supponga che startID e endID siano VT_I4 ID figlio (elementi semplici) e pStartAcc e pEndAcc siano VT_I4 con CHILDID_SELF (oggetti completi).

Questa tabella descrive i flag di NAVDIR_ seguenti: NEXT, PREVIOUS, LEFT, RIGHT, UP e DOWN. Per altre informazioni sui flag di spostamento, vedere Costanti di spostamento.

Punto di partenza	Risultato restituito	Post-elaborazione per il valore restituito
pStartAcc, startID	endID VT_I4	Chiamare get_accChild in pStartAcc passando endID. Seguire le normali procedure descritte in get_accChild.
pStartAcc, startID	VT_DISPATCH pEndAcc	Usare le procedure standard per convertire un puntatore dell'interfaccia IDispatch in un puntatore dell'interfaccia IAccessibile per pEndAcc.
pStartAcc, CHILDID_SELF	endID VT_I4	Chiamare get_accParent in pStartAcc, passando CHILDID_SELF per ottenere il puntatore dell'interfaccia IAccessibile dell'elemento padre per endID. Chiamare quindi get_accChild sul puntatore dell'interfaccia IAccessibile , passando endID. Seguire le normali procedure descritte in get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Usare le procedure standard per convertire un puntatore dell'interfaccia IDispatch in un puntatore dell'interfaccia IAccessibile per pEndAcc.

La tabella seguente descrive i flag di spostamento NAVDIR_FIRSTCHILD e NAVDIR_LASTCHILD. Non include voci per passare a un primo o ultimo elemento figlio quando il punto iniziale è un elemento semplice perché gli elementi semplici non possono avere elementi figlio.

Punto di partenza	Risultato restituito	Post-elaborazione per il valore restituito
pStartAcc, CHILDID_SELF	endID VT_I4	Chiamare get_accChild in pStartAcc, passando endID. Seguire le normali procedure descritte in get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Usare le procedure standard per convertire un puntatore dell'interfaccia IDispatch in un puntatore dell'interfaccia IAccessibile per pEndAcc.

Per altre informazioni, vedere Proprietà e metodi di spostamento degli oggetti.

Esempio di server

Nell'esempio seguente viene illustrata una possibile implementazione del metodo per una casella di riepilogo personalizzata i cui elementi di elenco sono elementi figlio.


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

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	oleacc.h
Libreria	Oleacc.lib
DLL	Oleacc.dll
Componente ridistribuibile	Accessibilità attiva 1.3 RDK in Windows NT 4.0 con SP6 e versioni successive e Windows 95