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

Artigo
08/25/2023

O método IAccessible::accNavigate atravessa para outro elemento de interface do usuário dentro de um contêiner e recupera o objeto . Esse método é opcional.

Nota O método accNavigate foi preterido e não deve ser usado. Os clientes devem usar outros métodos e propriedades, como AccessibleChildren, get_accChild, get_accParent e IEnumVARIANT.

Sintaxe

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

Parâmetros

[in] navDir

Tipo: long

Especifica a direção a ser navegada. Essa direção está em ordem espacial , como esquerda, direita ou ordem lógica , como a próxima ou anterior. Esse valor é uma das constantes de navegação.

[in] varStart

Tipo: VARIANT

Especifica se o objeto inicial da navegação é o próprio objeto ou um dos filhos do objeto. Esse parâmetro é CHILDID_SELF (para começar do objeto) ou uma ID filho (para começar de um dos elementos filho do objeto). Para obter mais informações sobre como inicializar o VARIANT, consulte Como as IDs filho são usadas em parâmetros.

[out, retval] pvarEndUpAt

Tipo: VARIANT*

[out, retval] Endereço de uma estrutura VARIANT que recebe informações sobre o objeto de destino. A tabela a seguir descreve as informações retornadas em pvarEnd.

membro vt	Membro de valor
VT_EMPTY	Nenhum. Não havia nenhum elemento de interface do usuário na direção especificada.
VT_I4	LVal contém a ID filho do elemento de interface do usuário.
VT_DISPATCH	pdispVal contém o endereço do IDispatch do elemento de interface do usuário.

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 IAccessible e Valores retornados.

Erro	Descrição
S_FALSE	Nenhum elemento de tela foi encontrado na direção especificada.
DISP_E_MEMBERNOTFOUND	O objeto não dá suporte a esse método.
E_INVALIDARG	Um argumento não é válido.

Comentários

A navegação, espacial e lógica, é sempre restrita aos elementos da interface do usuário em um contêiner. Com a navegação espacial, os clientes navegam apenas para um irmão do objeto inicial (varStart). Dependendo do sinalizador de navegação usado com navegação lógica, os clientes navegam até um filho ou para um irmão do objeto inicial.

O método accNavigate recupera elementos de interface do usuário que têm um local de tela definido e objetos invisíveis que não têm um local de tela definido.

Esse método não altera a seleção nem o foco. Para alterar o foco ou selecionar um objeto, use IAccessible::accSelect.

Para evitar o loop ao percorrer elementos de tela, accNavigate retorna S_FALSE com VT_EMPTY quando você especifica NAVDIR_NEXT no último elemento ou NAVDIR_PREVIOUS no primeiro elemento.

Assim como acontece com outros métodos e funções IAccessible , os clientes podem receber erros para ponteiros de interface IAccessible devido a uma ação do usuário. Para obter mais informações, consulte Recebendo erros para ponteiros de interface IAccessible.

Alguns elementos de interface do usuário definidos pelo sistema, como menus, itens de menu e menus pop-up, permitem a navegação para objetos invisíveis. No entanto, outros elementos de interface do usuário definidos pelo sistema não dão suporte a isso. Os servidores podem escolher se desejam dar suporte à navegação para objetos invisíveis e podem ignorá-los ou expô-los.

Os aplicativos cliente devem retornar valores retornados pós-processo ao usar accNavigate para navegar entre objetos. O objetivo das etapas pós-processamento é dar aos clientes um ponteiro de interface IAccessible e uma ID filho para que eles possam usar os métodos e propriedades IAccessible para um elemento de interface do usuário.

As tabelas a seguir descrevem possíveis cenários para IAccessible::accNavigate, com base nos seguintes critérios:

Um ponto de partida definido (se você está começando com um objeto completo ou um elemento simples)
O resultado retornado (um IDispatch ou uma ID filho VT_I4)
O pós-processamento que os aplicativos cliente precisarão executar para ter um ponteiro de interface IAccessible e uma ID filho

Para essas tabelas, suponha que startID e endID sejam VT_I4 IDs filho (elementos simples) e pStartAcc e pEndAcc sejam VT_I4 com CHILDID_SELF (objetos completos).

Esta tabela descreve os seguintes sinalizadores de NAVDIR_: NEXT, PREVIOUS, LEFT, RIGHT, UP e DOWN. Para obter mais informações sobre sinalizadores de navegação, consulte Constantes de navegação.

Ponto inicial	Resultado retornado	Pós-processamento para o valor retornado
pStartAcc, startID	VT_I4 endID	Chame get_accChild em pStartAcc passando endID. Siga os procedimentos normais descritos em get_accChild.
pStartAcc, startID	VT_DISPATCH pEndAcc	Use os procedimentos padrão para converter um ponteiro de interface IDispatch em um ponteiro de interface IAccessible para pEndAcc.
pStartAcc, CHILDID_SELF	VT_I4 endID	Chame get_accParent em pStartAcc, passando CHILDID_SELF para obter o ponteiro da interface IAccessible do pai para endID. Em seguida, chame get_accChild nesse ponteiro de interface IAccessible , passando endID. Siga os procedimentos normais descritos em get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Use os procedimentos padrão para converter um ponteiro de interface IDispatch em um ponteiro de interface IAccessible para pEndAcc.

A tabela a seguir descreve os sinalizadores de navegação NAVDIR_FIRSTCHILD e NAVDIR_LASTCHILD. Ele não inclui entradas para navegar até um primeiro ou último filho quando o ponto de partida é um elemento simples porque elementos simples não podem ter filhos.

Ponto inicial	Resultado retornado	Pós-processamento para o valor retornado
pStartAcc, CHILDID_SELF	VT_I4 endID	Chame get_accChild em pStartAcc, passando endID. Siga os procedimentos normais descritos em get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Use os procedimentos padrão para converter um ponteiro de interface IDispatch em um ponteiro de interface IAccessible para pEndAcc.

Para obter mais informações, consulte Propriedades e métodos de navegação de objeto.

Exemplo de servidor

O exemplo a seguir mostra uma possível implementação do método para uma caixa de listagem personalizada cujos itens de lista são elementos filho.


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