IAccessible::get_accDescription method

The IAccessible::get_accDescription method retrieves a string that describes the visual appearance of the specified object. Not all objects have a description.

Note  The Description property is often used incorrectly and is not supported by Microsoft UI Automation. Microsoft Active Accessibility server developers should not use this property. If more information is needed for accessibility and automation scenarios, use the properties supported by UI Automation elements and control patterns.

Syntax


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

Parameters

varID [in]

Type: VARIANT

Specifies whether the retrieved description belongs to the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.

pszDescription [out, retval]

Type: BSTR*

Address of a BSTR that receives a localized string that describes the specified object, or NULL if this object has no description.

Return value

Type: HRESULT

If successful, returns S_OK.

If not successful, returns one of the values in the table that follows, or another standard COM error code. Servers return these values, but clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Return codeDescription
S_FALSE

The specified object does not have a description.

E_INVALIDARG

An argument is not valid.

DISP_E_MEMBERNOTFOUND

The specified object does not support this property.

 

Remarks

An Microsoft Active Accessibility server can add support for UI Automation by using Direct Annotation, using the IAccessibleEx interface, or by implementing Microsoft Active Accessibility and UI Automation side-by-side with both implementations handling the WM_GETOBJECT message.

This property provides a textual equivalent of the object for the user. The description should be similar to the text supplied with the ALT attribute in HTML, which is the text that is displayed to describe images for people using text-only browsers. However, some controls use this property to store extra information about the control that is not related to a textual equivalent. For more information about this property, see Description Property.

Note to server developers:   Localize the string returned from this property.

Server Example

The following example code shows one possible implementation of this method for a custom list box that maintains its own child elements. The example demonstrates the syntax, but remember that a real text-only list box would probably not need to support this property. For simplicity, the strings in the example are not localized.



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


Client Example

The following example function retrieves the description of the specified accessible object, or a child element, and displays it on the 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;
}


Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Redistributable

Active Accessibility 1.3 RDK on Windows NT 4.0 with SP6 and later and Windows 95

Header

Oleacc.h

Library

Oleacc.lib

DLL

Oleacc.dll

See also

Reference
IAccessible
IAccessible::get_accName
IAccessible::get_accHelp
IAccessible::get_accValue
Conceptual
Description Property
Using Direct Annotation

 

 

Community Additions

ADD
Show:
© 2014 Microsoft