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

Artículo
03/05/2024

El método IAccessible::get_accDescription recupera una cadena que describe la apariencia visual del objeto especificado. No todos los objetos tienen una descripción.

Nota La propiedad Description se usa a menudo incorrectamente y no es compatible con Microsoft Automatización de la interfaz de usuario. Los desarrolladores de servidores de accesibilidad activa de Microsoft no deben usar esta propiedad. Si se necesita más información para escenarios de accesibilidad y automatización, use las propiedades admitidas por Automatización de la interfaz de usuario elementos y patrones de control.

Sintaxis

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

Parámetros

[in] varChild

Tipo: VARIANT

Especifica si la descripción recuperada 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] pszDescription

Tipo: BSTR*

Dirección de un BSTR que recibe una cadena localizada que describe el objeto especificado o NULL si este objeto no tiene ninguna descripción.

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 Comprobación de valores devueltos de IAccessible.

Código devuelto	Descripción
S_FALSE	El objeto especificado no tiene una descripción.
E_INVALIDARG	Un argumento no es válido.
DISP_E_MEMBERNOTFOUND	El objeto especificado no admite esta propiedad.

Comentarios

Un servidor de accesibilidad activa de Microsoft puede agregar compatibilidad con Automatización de la interfaz de usuario mediante anotación directa, mediante la interfaz IAccessibleEx o mediante la implementación de Microsoft Active Accessibility y Automatización de la interfaz de usuario en paralelo con ambas implementaciones que controlan el WM_GETOBJECT Mensaje.

Esta propiedad proporciona un equivalente textual del objeto para el usuario. La descripción debe ser similar al texto proporcionado con el atributo ALT en HTML, que es el texto que se muestra para describir imágenes para personas que usan exploradores de solo texto. Sin embargo, algunos controles usan esta propiedad para almacenar información adicional sobre el control que no está relacionado con un equivalente textual. Para obtener más información sobre esta propiedad, vea Description Property.

Nota para los desarrolladores de servidores: Localice la cadena devuelta de esta propiedad.

Ejemplo de servidor

En el código de ejemplo siguiente se muestra una posible implementación de este método para un cuadro de lista personalizado que mantiene sus propios elementos secundarios. En el ejemplo se muestra la sintaxis, pero recuerde que probablemente un cuadro de lista de solo texto real no necesitaría admitir esta propiedad. Para simplificar, las cadenas del ejemplo no se localizan.


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

Ejemplo de cliente

La siguiente función de ejemplo recupera la descripción del objeto accesible especificado, o un elemento secundario, y lo muestra en la consola.


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