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

Artículo
03/13/2024

El método IAccessible::accNavigate atraviesa a otro elemento de interfaz de usuario dentro de un contenedor y recupera el objeto . Este método es opcional.

Nota El método accNavigate está en desuso y no se debe usar. Los clientes deben usar otros métodos y propiedades como AccessibleChildren, get_accChild, get_accParent e IEnumVARIANT.

Sintaxis

HRESULT accNavigate(
  [in]          long    navDir,
  [in]          VARIANT varStart,
  [out, retval] VARIANT *pvarEndUpAt
);

Parámetros

[in] navDir

Tipo: long

Especifica la dirección para navegar. Esta dirección está en orden espacial , como izquierda o derecha, o orden lógico , como siguiente o anterior. Este valor es una de las constantes de navegación.

[in] varStart

Tipo: VARIANT

Especifica si el objeto inicial de la navegación es el propio objeto o uno de los elementos secundarios del objeto. Este parámetro es CHILDID_SELF (para empezar desde el objeto) o un identificador secundario (para empezar desde uno de los elementos secundarios del objeto). Para obtener más información sobre cómo inicializar variant, vea Cómo se usan los identificadores secundarios en parámetros.

[out, retval] pvarEndUpAt

Tipo: VARIANT*

[out, retval] Dirección de una estructura VARIANT que recibe información sobre el objeto de destino. En la tabla siguiente se describe la información que se devuelve en pvarEnd.

Miembro vt	Miembro de valor
VT_EMPTY	Ninguno. No había ningún elemento de interfaz de usuario en la dirección especificada.
VT_I4	lVal contiene el identificador secundario del elemento de interfaz de usuario.
VT_DISPATCH	pdispVal contiene la dirección del IDispatch del elemento de la interfaz de usuario.

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 los valores devueltos de IAccessible y los valores devueltos.

Error	Descripción
S_FALSE	No se encontró ningún elemento de pantalla en la dirección especificada.
DISP_E_MEMBERNOTFOUND	El objeto no admite este método.
E_INVALIDARG	Un argumento no es válido.

Comentarios

La navegación, tanto espacial como lógica, siempre está restringida a los elementos de la interfaz de usuario dentro de un contenedor. Con la navegación espacial, los clientes solo navegan a un elemento relacionado del objeto de inicio (varStart). Dependiendo de la marca de navegación usada con la navegación lógica, los clientes navegan a un elemento secundario o a un elemento relacionado del objeto inicial.

El método accNavigate recupera elementos de la interfaz de usuario que tienen una ubicación de pantalla definida y objetos invisibles que no tienen una ubicación de pantalla definida.

Este método no cambia la selección ni el foco. Para cambiar el foco o seleccionar un objeto, use IAccessible::accSelect.

Para evitar el bucle al atravesar elementos de pantalla, accNavigate devuelve S_FALSE con VT_EMPTY cuando se especifica NAVDIR_NEXT en el último elemento o NAVDIR_PREVIOUS en el primer elemento.

Al igual que con otros métodos y funciones IAccessible , los clientes pueden recibir errores de punteros de interfaz IAccessible debido a una acción del usuario. Para obtener más información, vea Recibir errores para punteros de interfaz IAccessible.

Algunos elementos de interfaz de usuario definidos por el sistema, como menús, elementos de menú y menús emergentes, permiten la navegación a objetos invisibles. Sin embargo, otros elementos de interfaz de usuario definidos por el sistema no admiten esto. Los servidores pueden elegir si se admite la navegación a objetos invisibles y pueden omitirlos o exponerlos.

Las aplicaciones cliente deben devolver valores devueltos posteriores al proceso cuando se usa accNavigate para navegar entre objetos. El objetivo de los pasos posteriores al procesamiento es proporcionar a los clientes un puntero de interfaz IAccessible y un identificador secundario para que puedan usar los métodos y propiedades IAccessible para un elemento de interfaz de usuario.

En las tablas siguientes se describen los posibles escenarios para IAccessible::accNavigate, en función de los siguientes criterios:

Un punto de partida definido (ya sea que empiece con un objeto completo o un elemento simple)
Resultado devuelto ( IDispatch o un identificador secundario de VT_I4).
El procesamiento posterior que las aplicaciones cliente tendrán que realizar para tener un puntero de interfaz IAccessible y un identificador secundario

En estas tablas, supongamos que startID y endID son VT_I4 identificadores secundarios (elementos simples) y pStartAcc y pEndAcc se VT_I4 con CHILDID_SELF (objetos completos).

En esta tabla se describen las marcas de NAVDIR_ siguientes: NEXT, PREVIOUS, LEFT, RIGHT, UP y DOWN. Para obtener más información sobre las marcas de navegación, vea Constantes de navegación.

Punto de partida	Resultado devuelto	Posprocesamiento para el valor devuelto
pStartAcc, startID	VT_I4 endID	Llame a get_accChild en pStartAcc pasando endID. Siga los procedimientos normales descritos en get_accChild.
pStartAcc, startID	VT_DISPATCH pEndAcc	Use los procedimientos estándar para convertir un puntero de interfaz IDispatch a un puntero de interfaz IAccessible para pEndAcc.
pStartAcc, CHILDID_SELF	VT_I4 endID	Llame a get_accParent en pStartAcc y pase CHILDID_SELF para obtener el puntero de interfaz IAccessible del elemento primario para endID. A continuación, llame a get_accChild en ese puntero de interfaz IAccessible , pasando endID. Siga los procedimientos normales descritos en get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Use los procedimientos estándar para convertir un puntero de interfaz IDispatch a un puntero de interfaz IAccessible para pEndAcc.

En la tabla siguiente se describen las marcas de navegación NAVDIR_FIRSTCHILD y NAVDIR_LASTCHILD. No incluye entradas para navegar a un primer o último elemento secundario cuando el punto inicial es un elemento simple porque los elementos simples no pueden tener elementos secundarios.

Punto de partida	Resultado devuelto	Posprocesamiento para el valor devuelto
pStartAcc, CHILDID_SELF	VT_I4 endID	Llame a get_accChild en pStartAcc, pasando endID. Siga los procedimientos normales descritos en get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Use los procedimientos estándar para convertir un puntero de interfaz IDispatch a un puntero de interfaz IAccessible para pEndAcc.

Para obtener más información, vea Propiedades y métodos de navegación de objetos.

Ejemplo de servidor

En el ejemplo siguiente se muestra una posible implementación del método para un cuadro de lista personalizado cuyos elementos de lista son elementos secundarios.


// m_pControl is the control that returns this accessible object. 
// m_pStdAccessibleObject is the standard accessible object for the window 
//    that contains the control. 

HRESULT STDMETHODCALLTYPE AccServer::accNavigate( 
    long navDir,
    VARIANT varStart,
    VARIANT *pvarEndUpAt)
{
    // Default value. 
    pvarEndUpAt->vt = VT_EMPTY;

    if (varStart.vt != VT_I4)
    {
        return E_INVALIDARG;
    }

    switch (navDir)
    {
    case NAVDIR_FIRSTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = 1;
        }
        else  // Starting with child. 
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_LASTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = m_pControl->GetCount();
        }
        else  // Starting with child.           
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_NEXT:   
    case NAVDIR_DOWN:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal + 1;
            // Out of range. 
            if (pvarEndUpAt->lVal > m_pControl->GetCount())
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

    case NAVDIR_PREVIOUS:
    case NAVDIR_UP:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal - 1;
            // Out of range. 
            if (pvarEndUpAt->lVal <1)
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

     // Unsupported directions. 
    case NAVDIR_LEFT:
    case NAVDIR_RIGHT:
        if (varStart.lVal == CHILDID_SELF)
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        else 
        {
            pvarEndUpAt->vt = VT_EMPTY;
            return S_FALSE;
        }
        break;
    }
    return S_OK;
};

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