Méthode IAccessible ::accNavigate (oleacc.h)

Article
03/06/2024

La méthode IAccessible ::accNavigate traverse vers un autre élément d’interface utilisateur au sein d’un conteneur et récupère l’objet. Cette méthode est facultative.

Note La méthode accNavigate est déconseillée et ne doit pas être utilisée. Les clients doivent utiliser d’autres méthodes et propriétés telles que AccessibleChildren, get_accChild, get_accParent et IEnumVARIANT.

Syntaxe

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

Paramètres

[in] navDir

Type : long

Spécifie la direction à parcourir. Cette direction est dans l’ordre spatial , par exemple à gauche ou à droite, ou dans l’ordre logique , comme suivant ou précédent. Cette valeur est l’une des constantes de navigation.

[in] varStart

Type : VARIANT

Spécifie si l’objet de départ de la navigation est l’objet lui-même ou l’un des enfants de l’objet. Ce paramètre est soit CHILDID_SELF (pour démarrer à partir de l’objet) soit un ID enfant (pour démarrer à partir de l’un des éléments enfants de l’objet). Pour plus d’informations sur l’initialisation du VARIANT, consultez Utilisation des ID enfants dans les paramètres.

[out, retval] pvarEndUpAt

Type : VARIANT*

[out, retval] Adresse d’une structure VARIANT qui reçoit des informations sur l’objet de destination. Le tableau suivant décrit les informations retournées dans pvarEnd.

membre vt	Membre value
VT_EMPTY	Aucun. Il n’y avait aucun élément d’interface utilisateur dans le sens spécifié.
VT_I4	lVal contient l’ID enfant de l’élément d’interface utilisateur.
VT_DISPATCH	pdispVal contient l’adresse du IDispatch de l’élément d’interface utilisateur.

Valeur retournée

Type : HRESULT

En cas de réussite, retourne S_OK.

En cas de non-réussite, retourne l’une des valeurs de la table qui suit ou un autre code d’erreur COM standard. Les serveurs retournent ces valeurs, mais les clients doivent toujours case activée paramètres de sortie pour s’assurer qu’ils contiennent des valeurs valides. Pour plus d’informations, consultez Vérification des valeurs de retour IAccessibles et des valeurs de retour.

Erreur	Description
S_FALSE	Aucun élément d’écran n’a été trouvé dans le sens spécifié.
DISP_E_MEMBERNOTFOUND	L’objet ne prend pas en charge cette méthode.
E_INVALIDARG	Un argument n’est pas valide.

Remarques

La navigation, à la fois spatiale et logique, est toujours limitée aux éléments d’interface utilisateur au sein d’un conteneur. Avec la navigation spatiale, les clients accèdent uniquement à un frère de l’objet de départ (varStart). Selon l’indicateur de navigation utilisé avec la navigation logique, les clients accèdent à un enfant ou à un frère de l’objet de départ.

La méthode accNavigate récupère les éléments d’interface utilisateur qui ont un emplacement d’écran défini et les objets invisibles qui n’ont pas d’emplacement d’écran défini.

Cette méthode ne modifie pas la sélection ou le focus. Pour modifier le focus ou sélectionner un objet, utilisez IAccessible ::accSelect.

Pour empêcher la boucle lors du passage d’éléments d’écran, accNavigate retourne S_FALSE avec VT_EMPTY lorsque vous spécifiez NAVDIR_NEXT sur le dernier élément ou NAVDIR_PREVIOUS sur le premier élément.

Comme avec d’autres méthodes et fonctions IAccessible , les clients peuvent recevoir des erreurs pour les pointeurs d’interface IAccessible en raison d’une action utilisateur. Pour plus d’informations, consultez Réception d’erreurs pour les pointeurs d’interface IAccessible.

Certains éléments d’interface utilisateur définis par le système, tels que les menus, les éléments de menu et les menus contextuels, permettent la navigation vers des objets invisibles. Toutefois, d’autres éléments d’interface utilisateur définis par le système ne le prennent pas en charge. Les serveurs peuvent choisir de prendre en charge la navigation vers des objets invisibles et de les ignorer ou de les exposer.

Les applications clientes doivent retourner des valeurs de retour post-traitement lors de l’utilisation d’accNavigate pour naviguer entre les objets. L’objectif des étapes de post-traitement est de donner aux clients un pointeur d’interface IAccessible et un ID enfant afin qu’ils puissent utiliser les méthodes et propriétés IAccessible pour un élément d’interface utilisateur.

Les tableaux suivants décrivent les scénarios possibles pour IAccessible ::accNavigate, en fonction des critères suivants :

Point de départ défini (qu’il s’agisse d’un objet complet ou d’un élément simple)
Résultat retourné (un IDispatch ou un ID enfant VT_I4)
Post-traitement que les applications clientes devront effectuer pour avoir un pointeur d’interface IAccessible et un ID enfant

Pour ces tables, supposons que startID et endID sont VT_I4 id enfants (éléments simples), et pStartAcc et pEndAcc sont VT_I4 avec CHILDID_SELF (objets complets).

Ce tableau décrit les indicateurs de NAVDIR_ suivants : SUIVANT, PRÉCÉDENT, GAUCHE, DROITE, HAUT et BAS. Pour plus d’informations sur les indicateurs de navigation, consultez Constantes de navigation.

Point de départ	Résultat retourné	Post-traitement de la valeur de retour
pStartAcc, startID	VT_I4 endID	Appelez get_accChild sur pStartAcc qui passe endID. Suivez les procédures normales décrites dans get_accChild.
pStartAcc, startID	VT_DISPATCH pEndAcc	Utilisez les procédures standard pour convertir un pointeur d’interface IDispatch en pointeur d’interface IAccessible pour pEndAcc.
pStartAcc, CHILDID_SELF	VT_I4 endID	Appelez get_accParent sur pStartAcc, en passant CHILDID_SELF pour obtenir le pointeur d’interface IAccessible du parent pour endID. Ensuite, appelez get_accChild sur ce pointeur d’interface IAccessible , en passant endID. Suivez les procédures normales décrites dans get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Utilisez les procédures standard pour convertir un pointeur d’interface IDispatch en pointeur d’interface IAccessible pour pEndAcc.

Le tableau suivant décrit les indicateurs de navigation NAVDIR_FIRSTCHILD et NAVDIR_LASTCHILD. Il n’inclut pas d’entrées permettant d’accéder à un premier ou dernier enfant lorsque le point de départ est un élément simple, car les éléments simples ne peuvent pas avoir d’enfants.

Point de départ	Résultat retourné	Post-traitement de la valeur de retour
pStartAcc, CHILDID_SELF	VT_I4 endID	Appelez get_accChild sur pStartAcc, en passant endID. Suivez les procédures normales décrites dans get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Utilisez les procédures standard pour convertir un pointeur d’interface IDispatch en pointeur d’interface IAccessible pour pEndAcc.

Pour plus d’informations, consultez Propriétés et méthodes de navigation d’objet.

Exemple de serveur

L’exemple suivant montre une implémentation possible de la méthode pour une zone de liste personnalisée dont les éléments de liste sont des éléments enfants.


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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	oleacc.h
Bibliothèque	Oleacc.lib
DLL	Oleacc.dll
Composant redistribuable	Active Accessibility 1.3 RDK sur Windows NT 4.0 avec SP6 et versions ultérieures et Windows 95