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

Article
02/29/2024

La méthode IAccessible ::get_accRole récupère des informations qui décrivent le rôle de l’objet spécifié. Tous les objets prennent en charge cette propriété.

Syntaxe

HRESULT get_accRole(
  [in]          VARIANT varChild,
  [out, retval] VARIANT *pvarRole
);

Paramètres

[in] varChild

Type : VARIANT

Spécifie si les informations de rôle récupérées appartiennent à l’objet ou à l’un des éléments enfants de l’objet. Ce paramètre est CHILDID_SELF (pour obtenir des informations sur l’objet) ou un ID enfant (pour obtenir des informations sur l’élément enfant de l’objet). Pour plus d’informations sur l’initialisation du VARIANT, consultez Utilisation des ID enfants dans les paramètres.

[out, retval] pvarRole

Type : VARIANT*

Adresse d’un VARIANT qui reçoit une constante de rôle d’objet . Le membre vt doit être VT_I4. Le membre lVal reçoit une constante de rôle d’objet.

Valeur retournée

Type : HRESULT

En cas de réussite, retourne S_OK.

En cas d’erreur, 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 IAccessible.

Erreur	Description
E_INVALIDARG	Un argument n’est pas valide.

Remarques

Les clients appellent GetRoleText pour récupérer une chaîne localisée qui décrit le rôle de l’objet.

Remarque pour les développeurs de serveurs : Vous devez utiliser les constantes de rôle prédéfinies.

Exemple de serveur

L’exemple de code suivant est une implémentation possible de cette méthode pour une zone de liste personnalisée qui gère ses propres éléments de liste.


HRESULT STDMETHODCALLTYPE AccServer::get_accRole( 
    VARIANT varChild,
    VARIANT *pvarRole)
{
    if (varChild.vt != VT_I4)
    {
        pvarRole->vt = VT_EMPTY;
        return E_INVALIDARG;
    }

    pvarRole->vt = VT_I4;

    if (varChild.lVal == CHILDID_SELF)
    {
        pvarRole->lVal = ROLE_SYSTEM_LIST;
    }
    else
    {
        pvarRole->lVal = ROLE_SYSTEM_LISTITEM;
    }
    return S_OK;
};

Exemple de client

L’exemple de fonction suivant affiche le rôle d’un objet accessible ou d’un élément enfant.


HRESULT PrintRole(IAccessible* pAcc, long childId)
{
    DWORD roleId;
    if (pAcc == NULL)
    {
        return E_INVALIDARG;    
    }
    VARIANT varChild;
    varChild.vt = VT_I4;
    varChild.lVal = childId;
    VARIANT varResult;
    HRESULT hr = pAcc->get_accRole(varChild, &varResult);
    if ((hr == S_OK) && (varResult.vt == VT_I4))
    {
        roleId = varResult.lVal;
        UINT   roleLength;
        LPTSTR lpszRoleString;

        // Get the length of the string. 
        roleLength = GetRoleText(roleId, NULL, 0);

        // Allocate memory for the string. Add one character to 
        // the length you got in the previous call to make room 
        // for the null character. 
        lpszRoleString = (LPTSTR)malloc((roleLength+1) * sizeof(TCHAR));
        if (lpszRoleString != NULL)
        {
            // Get the string. 
            GetRoleText(roleId, lpszRoleString, roleLength + 1);
#ifdef UNICODE
            printf("Role: %S\n", lpszRoleString);
#else
            printf(("Role: %s\n", lpszRoleString);
#endif
            // Free the allocated memory 
            free(lpszRoleString);
        }
        else 
        {
            return E_OUTOFMEMORY;
        }
    }
    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