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

Artigo
08/25/2023

O método IAccessible::get_accDescription recupera uma cadeia de caracteres que descreve a aparência visual do objeto especificado. Nem todos os objetos têm uma descrição.

Nota A propriedade Description geralmente é usada incorretamente e não tem suporte do Microsoft Automação da Interface do Usuário. Os desenvolvedores de servidores do Microsoft Active Accessibility não devem usar essa propriedade. Se mais informações forem necessárias para cenários de acessibilidade e automação, use as propriedades compatíveis com elementos Automação da Interface do Usuário e padrões de controle.

Sintaxe

HRESULT get_accDescription(
  [in]          VARIANT varChild,
  [out, retval] BSTR    *pszDescription
);

Parâmetros

[in] varChild

Tipo: VARIANT

Especifica se a descrição recuperada pertence 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 estrutura VARIANT, consulte Como as IDs filho são usadas em parâmetros.

[out, retval] pszDescription

Tipo: BSTR*

Endereço de um BSTR que recebe uma cadeia de caracteres localizada que descreve o objeto especificado ou NULL se esse objeto não tiver descrição.

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 do IAccessible.

Código de retorno	Descrição
S_FALSE	O objeto especificado não tem uma descrição.
E_INVALIDARG	Um argumento não é válido.
DISP_E_MEMBERNOTFOUND	O objeto especificado não dá suporte a essa propriedade.

Comentários

Um servidor de Acessibilidade Ativa da Microsoft pode adicionar suporte para Automação da Interface do Usuário usando a Anotação Direta, usando a interface IAccessibleEx ou implementando a Acessibilidade Ativa da Microsoft e Automação da Interface do Usuário lado a lado com ambas as implementações que lidam com a mensagem WM_GETOBJECT.

Essa propriedade fornece um equivalente textual do objeto para o usuário. A descrição deve ser semelhante ao texto fornecido com o atributo ALT em HTML, que é o texto que é exibido para descrever imagens para pessoas que usam navegadores somente texto. No entanto, alguns controles usam essa propriedade para armazenar informações extras sobre o controle que não está relacionado a um equivalente textual. Para obter mais informações sobre essa propriedade, consulte Propriedade Description.

Observação para desenvolvedores de servidores: Localize a cadeia de caracteres retornada dessa propriedade.

Exemplo de servidor

O código de exemplo a seguir mostra uma implementação possível desse método para uma caixa de listagem personalizada que mantém seus próprios elementos filho. O exemplo demonstra a sintaxe, mas lembre-se de que uma caixa de listagem real somente texto provavelmente não precisaria dar suporte a essa propriedade. Para simplificar, as cadeias de caracteres no exemplo não são localizadas.


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

Exemplo de cliente

A função de exemplo a seguir recupera a descrição do objeto acessível especificado ou um elemento filho e o exibe no 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;
}

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 com SP6 e posterior e Windows 95