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

Article
03/04/2024

La méthode IAccessible ::get_accName récupère le nom de l’objet spécifié. Tous les objets prennent en charge cette propriété.

Syntaxe

HRESULT get_accName(
  [in]          VARIANT varChild,
  [out, retval] BSTR    *pszName
);

Paramètres

[in] varChild

Type : VARIANT

Spécifie si le nom récupéré appartient à l’objet ou à l’un des éléments enfants de l’objet. Ce paramètre est soit CHILDID_SELF (pour obtenir des informations sur l’objet) soit 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] pszName

Type : BSTR*

Adresse d’un BSTR qui reçoit une chaîne qui contient le nom de l’objet spécifié.

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.

Erreur	Description
S_FALSE	L’objet spécifié n’a pas de nom.
E_INVALIDARG	Un argument n’est pas valide.

Remarques

De nombreux objets tels que les icônes, les menus, les case activée zones, les zones de liste déroulante et d’autres contrôles ont des étiquettes qui sont affichées pour les utilisateurs. Toute étiquette affichée aux utilisateurs est utilisée pour la propriété name de l’objet. Pour plus d’informations, consultez La propriété Name.

Remarque aux développeurs de serveurs : Si vous utilisez le texte de menu ou de bouton pour la propriété Name, supprimez les ampersands (&) marquant les touches d’accès du clavier. Fournissez la clé d’accès au client en réponse à IAccessible ::get_accKeyboardShortcut.

Localisez la chaîne retournée à partir de cette propriété.

Exemple de serveur

L’exemple suivant montre une implémentation possible de cette méthode pour un contrôle de zone de liste personnalisé qui gère ses propres éléments enfants.


// m_pStdAccessibleObject is the standard object returned by CreateStdAccessibleObject. 
// m_pControl is the control object that provides this accessibility object. It maintains
// a zero-based collection of child items. 

HRESULT STDMETHODCALLTYPE AccServer::get_accName( 
    VARIANT varChild,
    BSTR *pszName)
{
    if (varChild.vt != VT_I4)
    {
        *pszName = NULL;
        return E_INVALIDARG;
    }
    // For the control itself, let the standard accessible object return the name 
    // assigned by the application. This is either the "caption" property or, if 
    // there is no caption, the text of any label. 
    if (varChild.lVal == CHILDID_SELF)
    {
        return m_pStdAccessibleObject->get_accName(varChild, pszName);                  
    }
    
    // Else return the name of the item in the list. 
    else
    {
        CustomListControlItem* pItem = m_pControl->GetItemAt(varChild.lVal - 1);
        if (pItem)
        {
            *pszName = SysAllocString(pItem->GetName());        
       
        }
    }
    return S_OK;
};

Exemple de client

L’exemple de fonction suivant affiche le nom accessible d’un contrôle.


HRESULT PrintName(IAccessible* pAcc, long childId)
{
    if (pAcc == NULL)
    {
        return E_INVALIDARG;
    }
    BSTR bstrName;
    VARIANT varChild;
    varChild.vt = VT_I4;
    varChild.lVal = childId;
    HRESULT hr = pAcc->get_accName(varChild, &bstrName);
    printf("Name: %S ", bstrName);
    SysFreeString(bstrName);
    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