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

Artigo
01/10/2024

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

Sintaxe

HRESULT get_accName(
  [in]          VARIANT varChild,
  [out, retval] BSTR    *pszName
);

Parâmetros

[in] varChild

Tipo: VARIANT

Especifica se o nome recuperado 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] pszName

Tipo: BSTR*

Endereço de um BSTR que recebe uma cadeia de caracteres que contém o nome do objeto especificado.

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.

Erro	Descrição
S_FALSE	O objeto especificado não tem um nome.
E_INVALIDARG	Um argumento não é válido.

Comentários

Muitos objetos, como ícones, menus, caixas de marcar, caixas de combinação e outros controles, têm rótulos que são exibidos aos usuários. Qualquer rótulo exibido aos usuários é usado para a propriedade name do objeto. Para obter mais informações, consulte a Propriedade Name.

Observação para desenvolvedores de servidores: Se você estiver usando o menu ou o texto do botão para a propriedade Name, remova qualquer e comercial (&) marcando as teclas de acesso do teclado. Forneça a chave de acesso ao cliente em resposta a IAccessible::get_accKeyboardShortcut.

Localize a cadeia de caracteres retornada dessa propriedade.

Exemplo de servidor

O exemplo a seguir mostra uma possível implementação desse método para um controle de caixa de listagem personalizado que gerencia seus próprios elementos filho.


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

Exemplo de cliente

A função de exemplo a seguir exibe o nome acessível de um controle.


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

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