IAccessible::get_accDescription-Methode (oleacc.h)

Artikel
02/29/2024

Die IAccessible::get_accDescription-Methode ruft eine Zeichenfolge ab, die die visuelle Darstellung des angegebenen Objekts beschreibt. Nicht für alle Objekte liegt eine Beschreibung vor.

Hinweis Die Description-Eigenschaft wird häufig falsch verwendet und von Microsoft Benutzeroberflächenautomatisierung nicht unterstützt. Microsoft Active Accessibility-Serverentwickler sollten diese Eigenschaft nicht verwenden. Wenn weitere Informationen für Barrierefreiheits- und Automatisierungsszenarien erforderlich sind, verwenden Sie die Eigenschaften, die von Benutzeroberflächenautomatisierung Elementen und Steuerelementmustern unterstützt werden.

Syntax

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

Parameter

[in] varChild

Typ: VARIANT

Gibt an, ob die abgerufene Beschreibung zum Objekt oder zu einem der untergeordneten Elemente des Objekts gehört. Dieser Parameter ist entweder CHILDID_SELF (zum Abrufen von Informationen zum Objekt) oder eine untergeordnete ID (zum Abrufen von Informationen zum untergeordneten Element des Objekts). Weitere Informationen zum Initialisieren der VARIANT-Struktur finden Sie unter Verwenden untergeordneter IDs in Parametern.

[out, retval] pszDescription

Typ: BSTR*

Adresse eines BSTR , der eine lokalisierte Zeichenfolge empfängt, die das angegebene Objekt beschreibt, oder NULL , wenn dieses Objekt keine Beschreibung enthält.

Rückgabewert

Typ: HRESULT

Gibt bei Erfolg S_OK zurück.

Wenn dies nicht erfolgreich ist, gibt einen der Werte in der folgenden Tabelle oder einen anderen COM-Standardfehlercode zurück. Server geben diese Werte zurück, aber Clients müssen ausgabeparameter immer überprüfen, um sicherzustellen, dass sie gültige Werte enthalten. Weitere Informationen finden Sie unter Überprüfen von IAccessible-Rückgabewerten.

Rückgabecode	Beschreibung
S_FALSE	Das angegebene Objekt verfügt nicht über eine Beschreibung.
E_INVALIDARG	Ein Argument ist ungültig.
DISP_E_MEMBERNOTFOUND	Das angegebene Objekt unterstützt diese Eigenschaft nicht.

Hinweise

Ein Microsoft Active Accessibility-Server kann Unterstützung für Benutzeroberflächenautomatisierung hinzufügen, indem er direct Annotation verwendet, die IAccessibleEx-Schnittstelle verwendet oder Microsoft Active Accessibility implementiert und Benutzeroberflächenautomatisierung parallel zu beiden Implementierungen, die die WM_GETOBJECT-Nachricht behandeln.

Diese Eigenschaft stellt eine Textäquivalente des -Objekts für den Benutzer bereit. Die Beschreibung sollte dem textähnlichen Text entsprechen, der mit dem ALT-Attribut in HTML bereitgestellt wird. Dabei handelt es sich um den Text, der angezeigt wird, um Bilder für Personen zu beschreiben, die nur textbasierte Browser verwenden. Einige Steuerelemente verwenden diese Eigenschaft jedoch, um zusätzliche Informationen über das Steuerelement zu speichern, die nicht mit einem Textäquivalent zusammenhängen. Weitere Informationen zu dieser Eigenschaft finden Sie unter Description Property.

Hinweis für Serverentwickler: Lokalisieren Sie die von dieser Eigenschaft zurückgegebene Zeichenfolge.

Serverbeispiel

Der folgende Beispielcode zeigt eine mögliche Implementierung dieser Methode für ein benutzerdefiniertes Listenfeld, das seine eigenen untergeordneten Elemente verwaltet. Das Beispiel veranschaulicht die Syntax, aber denken Sie daran, dass ein reines Textlistenfeld diese Eigenschaft wahrscheinlich nicht unterstützen muss. Der Einfachheit halber werden die Zeichenfolgen im Beispiel nicht lokalisiert.


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

Clientbeispiel

Die folgende Beispielfunktion ruft die Beschreibung des angegebenen Barrierefreien Objekts oder eines untergeordneten Elements ab und zeigt es in der Konsole an.


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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	oleacc.h
Bibliothek	Oleacc.lib
DLL	Oleacc.dll
Verteilbare Komponente	Active Accessibility 1.3 RDK unter Windows NT 4.0 mit SP6 und höher und Windows 95