IAccessible::get_accHelp

Article
03/28/2008

The IAccessible::get_accHelp method retrieves an object's Help property string. Not all objects support this property.

HRESULT get_accHelp(
VARIANTvarID,BSTR* pszHelp);

Parameters

varID
[in] Specifies whether the help information 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 one of the object's child elements). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pszHelp
[out, retval] Address of a BSTR that receives the localized string that contains the help information for the specified object, or NULL if no help information is available.

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	No help information is available.
E_INVALIDARG	An argument is invalid.
DISP_E_MEMBERNOTFOUND	The object does not support this property.

Remarks

None of the predefined and common controls support this property.

The information in this property should be similar to the help provided in ToolTips. Use this property to describe what the object does or how to use it, as opposed to IAccessible::get_accDescription, which describes an object's appearance.

This property returns a string, whereas IAccessible::get_accHelpTopic provides access to a Help topic in WinHelp. Objects are not required to support both IAccessible::get_accHelp and IAccessible::get_accHelpTopic, but they must support at least one. If they easily return a string, they must support IAccessible::get_accHelp; otherwise they must support IAccessible::get_accHelpTopic. If both are supported, IAccessible::get_accHelpTopic provides more detailed information.

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. Different text is displayed depending on the status of the contact in the list. For simplicity, the example does not localize the returned string.

// m_pControl is the custom control that returns this accessible object.
// 'online' is an enumerated value.

HRESULT STDMETHODCALLTYPE AccServer::get_accHelp( 
    VARIANT varChild,
    BSTR *pszHelp)
{
    *pszHelp = NULL;
    if (varChild.vt != VT_I4)
    {
        return E_INVALIDARG;
    }
    if (varChild.lVal == CHILDID_SELF)
    {
        *pszHelp = SysAllocString(L"Contact list.");
    }
    else
    {
        int index = (int)varChild.lVal - 1;
        CustomListControlItem* pItem = m_pControl->GetItemAt(index);
        if (pItem == NULL)
        {
            return E_INVALIDARG;
        }
        if (pItem->GetStatus() == online)
        {
            *pszHelp = SysAllocString(L"Online contact.");
        }
        else 
        {
            *pszHelp = SysAllocString(L"Offline contact.");
        }
    }
    return S_OK;
};

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.

Share via