IAccessible::get_accName

Article
03/28/2008

The IAccessible::get_accName method retrieves the name of the specified object. All objects support this property.

HRESULT get_accName(
VARIANTvarID,BSTR* pszName);

Parameters

varID
[in] Specifies whether the name 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.
pszName
[out, retval] Address of a BSTR that receives a string that contains the specified object's name.

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 name.
E_INVALIDARG	An argument is invalid.

Remarks

Many objects such as icons, menus, check boxes, combo boxes, and other controls have labels that are displayed to users. Any label that is displayed to users is used for the object's name property. For more information, see the Name Property.

Note to server developers If you are using menu or button text for the Name property, remove any ampersands (&) marking the keyboard access keys. Provide the access key to the client in response to IAccessible::get_accKeyboardShortcut.

Localize the string returned from this property.

Server Example

The following example shows a possible implementation of this method for a custom list box control that manages its own child elements.

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

Client Example

The following example function displays the accessible name of a control.

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

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.