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

Artículo
03/05/2024

El método IAccessible::get_accName recupera el nombre del objeto especificado. Todos los objetos admiten esta propiedad.

Sintaxis

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

Parámetros

[in] varChild

Tipo: VARIANT

Especifica si el nombre recuperado pertenece al objeto o a uno de los elementos secundarios del objeto. Este parámetro es CHILDID_SELF (para obtener información sobre el objeto) o un identificador secundario (para obtener información sobre el elemento secundario del objeto). Para obtener más información sobre cómo inicializar la estructura VARIANT, vea Cómo se usan los identificadores secundarios en parámetros.

[out, retval] pszName

Tipo: BSTR*

Dirección de un BSTR que recibe una cadena que contiene el nombre del objeto especificado.

Valor devuelto

Tipo: HRESULT

Si se ejecuta correctamente, devuelve S_OK.

Si no se ejecuta correctamente, devuelve uno de los valores de la tabla siguiente u otro código de error COM estándar. Los servidores devuelven estos valores, pero los clientes siempre deben comprobar los parámetros de salida para asegurarse de que contienen valores válidos. Para obtener más información, vea Comprobar valores devueltos de IAccessible.

Error	Descripción
S_FALSE	El objeto especificado no tiene un nombre.
E_INVALIDARG	Un argumento no es válido.

Comentarios

Muchos objetos, como iconos, menús, casillas, cuadros combinados y otros controles, tienen etiquetas que se muestran a los usuarios. Cualquier etiqueta que se muestre a los usuarios se usa para la propiedad name del objeto. Para obtener más información, vea La propiedad Name.

Nota para los desarrolladores de servidores: Si usa texto de menú o botón para la propiedad Name, quite las y comercial (&) que marquen las teclas de acceso del teclado. Proporcione la clave de acceso al cliente en respuesta a IAccessible::get_accKeyboardShortcut.

Localizar la cadena devuelta de esta propiedad.

Ejemplo de servidor

En el ejemplo siguiente se muestra una posible implementación de este método para un control de cuadro de lista personalizado que administra sus propios elementos secundarios.


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

Ejemplo de cliente

La siguiente función de ejemplo muestra el nombre accesible de un control.


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	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	oleacc.h
Library	Oleacc.lib
Archivo DLL	Oleacc.dll
Redistribuible	RDK de accesibilidad activa 1.3 en Windows NT 4.0 con SP6 y versiones posteriores y Windows 95