IAccessible::get_accState method (oleacc.h)

Article
02/22/2024

The IAccessible::get_accState method retrieves the current state of the specified object. All objects support this property.

Syntax

HRESULT get_accState(
  [in]          VARIANT varChild,
  [out, retval] VARIANT *pvarState
);

Parameters

[in] varChild

Type: VARIANT

Specifies whether the retrieved state information belongs to 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, see How Child IDs Are Used in Parameters.

[out, retval] pvarState

Type: VARIANT*

Address of a VARIANT structure that receives information that describes the object's state. The vt member is VT_I4, and the lVal member is one or more of the object state constants.

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.

Error	Description
E_INVALIDARG	An argument is not valid.

Remarks

If predefined state values are returned, clients call GetStateText to retrieve a localized string that describes the object's state.

The actual state of a child often depends on the state of its ancestors. For example, controls in an application's main window are not focusable when a modal dialog box is open, but the controls may not report this state. To verify the state information of a child object, call get_accState for the parent object.

Note to server developers: You must use the predefined state constants.

Server Example

The following example code shows a possible implementation of this method for a custom list box that maintains its own child elements (list items), only one of which can be selected at a time. If the client requests the state of the list box itself, the method passes the call to the standard accessible object that serves the control window. For child items, different flags are returned depending on whether the item is selected or not.


// m_pStdAccessibleObject is the standard accessible object returned by CreateAccessibleObject. 
// m_pControl is the custom control instance that returns this accessible object. 

HRESULT STDMETHODCALLTYPE AccServer::get_accState( 
    VARIANT varChild,
    VARIANT *pvarState)
{
    if (varChild.vt != VT_I4)
    {
        pvarState->vt = VT_EMPTY;
        return E_INVALIDARG;
    }
    if (varChild.lVal == CHILDID_SELF)
    {
        return m_pStdAccessibleObject->get_accState(varChild, pvarState);
    }
    else  // For list items. 
    {
        DWORD flags = STATE_SYSTEM_SELECTABLE;
        int index = (int)varChild.lVal - 1;
        if (index == m_pControl->GetSelectedIndex())
        {
            flags |= STATE_SYSTEM_SELECTED;
        }
        pvarState->vt = VT_I4;
        pvarState->lVal = flags; 
    }
    return S_OK;
};

Client Example

The following example function displays the states of the specified accessible object or a child element.


HRESULT PrintState(IAccessible* pAcc, long childId)
{
    if (pAcc == NULL)
    {
        return E_INVALIDARG;    
    }
    VARIANT      varChild;
    varChild.vt = VT_I4;
    varChild.lVal = childId;
    VARIANT varResult;
    HRESULT hr = pAcc->get_accState(varChild, &varResult);
    long stateBits = 0;
    if ((hr == S_OK) && (varResult.vt == VT_I4))
    {
        printf("State: ");
        stateBits = (DWORD)varResult.lVal;
        for (DWORD mask = 1; mask <= 0x8000; mask <<= 1)
        {
            if (mask & stateBits)
            {

                // Get the length of the string. 
                UINT stateLength = GetStateText(mask, NULL, 0);

                // Allocate memory for the string. Add one character to 
                // the length you got in the previous call to make room 
                // for the null character. 
                LPTSTR lpszStateString = (LPTSTR)malloc(
                    (stateLength + 1) * sizeof(TCHAR));
                if (lpszStateString != NULL)
                {
                    // Get the string. 
                    GetStateText(mask, 
                        lpszStateString, stateLength + 1); 
#ifdef UNICODE
                    printf("%S\n", lpszStateString);
#else
                    printf(("%s\n", lpszStateString);
#endif
                    // Free the allocated memory
                    free(lpszStateString);
                }
                else 
                {
                    return E_OUTOFMEMORY;
                }
            }
        }
    }
    return hr;
}

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	oleacc.h
Library	Oleacc.lib
DLL	Oleacc.dll
Redistributable	Active Accessibility 1.3 RDK on Windows NT 4.0 and Windows 95