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

Article
03/04/2024

La méthode IAccessible ::get_accDescription récupère une chaîne qui décrit l’apparence visuelle de l’objet spécifié. Les objets n'ont pas tous une description.

Note La propriété Description est souvent utilisée de manière incorrecte et n’est pas prise en charge par Microsoft UI Automation. Les développeurs du serveur Microsoft Active Accessibility ne doivent pas utiliser cette propriété. Si des informations supplémentaires sont nécessaires pour les scénarios d’accessibilité et d’automatisation, utilisez les propriétés prises en charge par UI Automation éléments et les modèles de contrôle.

Syntaxe

HRESULT get_accDescription(
  [in]          VARIANT varChild,
  [out, retval] BSTR    *pszDescription
);

Paramètres

[in] varChild

Type : VARIANT

Spécifie si la description récupérée appartient à 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 de la structure VARIANT, consultez Utilisation des ID enfants dans les paramètres.

[out, retval] pszDescription

Type : BSTR*

Adresse d’un BSTR qui reçoit une chaîne localisée qui décrit l’objet spécifié, ou NULL si cet objet n’a aucune description.

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.

Code de retour	Description
S_FALSE	L’objet spécifié n’a pas de description.
E_INVALIDARG	Un argument n’est pas valide.
DISP_E_MEMBERNOTFOUND	L’objet spécifié ne prend pas en charge cette propriété.

Remarques

Un serveur Microsoft Active Accessibility peut ajouter la prise en charge des UI Automation à l’aide de l’annotation directe, à l’aide de l’interface IAccessibleEx, ou en implémentant Microsoft Active Accessibility et UI Automation côte à côte avec les deux implémentations qui gèrent le message WM_GETOBJECT.

Cette propriété fournit un équivalent textuel de l’objet pour l’utilisateur. La description doit être similaire au texte fourni avec l’attribut ALT en HTML, qui est le texte affiché pour décrire les images pour les personnes utilisant des navigateurs de texte uniquement. Toutefois, certains contrôles utilisent cette propriété pour stocker des informations supplémentaires sur le contrôle qui ne sont pas liées à un équivalent textuel. Pour plus d’informations sur cette propriété, consultez Description, propriété.

Remarque pour les développeurs de serveurs : Localisez la chaîne retournée à partir de cette propriété.

Exemple de serveur

L’exemple de code suivant montre une implémentation possible de cette méthode pour une zone de liste personnalisée qui gère ses propres éléments enfants. L’exemple illustre la syntaxe, mais n’oubliez pas qu’une vraie zone de liste de texte uniquement n’aurait probablement pas besoin de prendre en charge cette propriété. Par souci de simplicité, les chaînes de l’exemple ne sont pas localisées.


HRESULT STDMETHODCALLTYPE AccServer::get_accDescription( 
    VARIANT varChild,
    BSTR *pszDescription)
{
    if (varChild.vt != VT_I4)
    {
        *pszDescription = NULL;
        return E_INVALIDARG;
    }
    if (varChild.lVal == CHILDID_SELF)
    {
        *pszDescription = SysAllocString(L"List of contacts.");    
            
    }
    else
    {
        *pszDescription = SysAllocString(L"A contact.");           
            
    }
    return S_OK;
};

Exemple de client

L’exemple de fonction suivant récupère la description de l’objet accessible spécifié, ou d’un élément enfant, et l’affiche sur la console.


HRESULT PrintDescription(IAccessible* pAcc, long child)
{
    VARIANT varObject;
    varObject.vt = VT_I4;
    varObject.lVal = child;
    BSTR bstrDesc;
    HRESULT hr = pAcc->get_accDescription(varObject, &bstrDesc);
    if (hr == S_OK)
    {
        printf("Description: %S\n", bstrDesc);
        SysFreeString(bstrDesc);
    }
    return hr;
}

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