IAccessible::get_accDescription

Article
03/28/2008

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

HRESULT get_accDescription(
VARIANTvarID,BSTR* pszDescription);

Parameters

varID
[in] Specifies whether the description retrieved is that of the object or of 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] Address of a BSTR that receives a localized string that describes the specified object, or NULL if no description is available for this object.

Return Values

If successful, returns S_OK.

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

Error	Description
S_FALSE	The specified object does not have a description.
E_INVALIDARG	An argument is invalid.
DISP_E_MEMBERNOTFOUND	The specified object does not support this property.

Remarks

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

**  Windows NT/2000/XP/Server 2003:** Included in Windows 2000 and later.
**  Windows 95/98/Me:** Included in Windows 98 and later.
**  Redistributable:** Requires Active Accessibility 1.3 RDK on Windows NT 4.0 SP6 and Windows 95.
**  Header:** Declared in Oleacc.h.
**  Library:** Use Oleacc.lib.