Método IAccessible::get_accState (oleacc.h)

Artigo
03/05/2024

O método IAccessible::get_accState recupera o estado atual do objeto especificado. Todos os objetos dão suporte a essa propriedade.

Sintaxe

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

Parâmetros

[in] varChild

Tipo: VARIANT

Especifica se as informações de estado recuperadas pertencem ao objeto ou a um dos elementos filho do objeto. Esse parâmetro é CHILDID_SELF (para obter informações sobre o objeto) ou uma ID filho (para obter informações sobre o elemento filho do objeto). Para obter mais informações sobre como inicializar a VARIANT, consulte Como as IDs filho são usadas em parâmetros.

[out, retval] pvarState

Tipo: VARIANT*

Endereço de uma estrutura VARIANT que recebe informações que descrevem o estado do objeto. O membro vt é VT_I4 e o membro lVal é uma ou mais das constantes de estado do objeto.

Retornar valor

Tipo: HRESULT

Se for bem-sucedido, retornará S_OK.

Se não for bem-sucedido, retornará um dos valores na tabela a seguir ou outro código de erro COM padrão. Os servidores retornam esses valores, mas os clientes devem sempre marcar parâmetros de saída para garantir que eles contenham valores válidos. Para obter mais informações, consulte Verificando valores retornados IAccessible.

Erro	Descrição
E_INVALIDARG	Um argumento não é válido.

Comentários

Se os valores de estado predefinidos forem retornados, os clientes chamarão GetStateText para recuperar uma cadeia de caracteres localizada que descreve o estado do objeto.

O estado real de uma criança geralmente depende do estado de seus ancestrais. Por exemplo, os controles na janela main de um aplicativo não são focalizáveis quando uma caixa de diálogo modal está aberta, mas os controles podem não relatar esse estado. Para verificar as informações de estado de um objeto filho, chame get_accState para o objeto pai.

Observação para desenvolvedores de servidores: Você deve usar as constantes de estado predefinidas.

Exemplo de servidor

O código de exemplo a seguir mostra uma possível implementação desse método para uma caixa de listagem personalizada que mantém seus próprios elementos filho (itens de lista), apenas um dos quais pode ser selecionado por vez. Se o cliente solicitar o estado da própria caixa de listagem, o método passará a chamada para o objeto acessível padrão que atende à janela de controle. Para itens filho, sinalizadores diferentes são retornados dependendo se o item está selecionado ou não.


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

Exemplo de cliente

A função de exemplo a seguir exibe os estados do objeto acessível especificado ou de um elemento filho.


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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	oleacc.h
Biblioteca	Oleacc.lib
DLL	Oleacc.dll
Redistribuível	Active Accessibility 1.3 RDK no Windows NT 4.0 e Windows 95