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

Artigo
08/25/2023

O método IAccessible::accHitTest recupera o elemento filho ou objeto filho exibido em um ponto específico na tela. Todos os objetos visuais dão suporte a esse método, mas objetos de som não. Os aplicativos cliente raramente chamam esse método diretamente; para obter o objeto acessível exibido em um ponto, use a função AccessibleObjectFromPoint , que chama esse método internamente.

Sintaxe

HRESULT accHitTest(
  [in]          long    xLeft,
  [in]          long    yTop,
  [out, retval] VARIANT *pvarChild
);

Parâmetros

[in] xLeft

Tipo: long

Especifica as coordenadas de tela do ponto que é atingido testado. As coordenadas x aumentam da esquerda para a direita. Observe que quando as coordenadas de tela são usadas, a origem é o canto superior esquerdo da tela.

[in] yTop

Tipo: long

Especifica as coordenadas de tela do ponto que é atingido testado. As coordenadas y aumentam de cima para baixo. Observe que quando as coordenadas de tela são usadas, a origem é o canto superior esquerdo da tela.

[out, retval] pvarChild

Tipo: VARIANT*

[out, retval] Endereço de uma VARIANT que identifica o objeto exibido no ponto especificado por xLeft e yTop. As informações retornadas em pvarID dependem do local do ponto especificado em relação ao objeto cujo método accHitTest está sendo chamado.

Localização do ponto	membro vt	Membro value
Fora dos limites do objeto e dentro ou fora do retângulo delimitador do objeto.	VT_EMPTY	Nenhum.
Dentro do objeto, mas não dentro de um elemento filho ou de um objeto filho.	VT_I4	lVal é CHILDID_SELF.
Dentro de um elemento filho.	VT_I4	lVal contém a ID filho.
Dentro de um objeto filho.	VT_DISPATCH	pdispVal é definido como o ponteiro da interface IDispatch do objeto filho

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.

Erro	Descrição
S_FALSE	O ponto está fora dos limites do objeto. O membro vt de pvarID é VT_EMPTY.
DISP_E_MEMBERNOTFOUND	O objeto não dá suporte a esse método.
E_INVALIDARG	Um argumento não é válido.

Observação aos desenvolvedores cliente: Embora os servidores retornem S_FALSE se o membro vt do pvarID for VT_EMPTY, os clientes também deverão lidar com o caso em que pvarID-vt> é VT_EMPTY e o valor retornado é S_OK.

Comentários

Se o ponto testado estiver em um dos filhos do objeto e esse filho oferecer suporte à própria interface IAccessible , esse método deverá retornar um ponteiro de interface IAccessible . No entanto, os clientes devem estar preparados para lidar com um ponteiro de interface IAccessible ou uma ID filho. Para obter mais informações, consulte Como as IDs filho são usadas em parâmetros.

Como accLocation retorna um retângulo delimitador, nem todos os pontos nesse retângulo estarão dentro dos limites reais do objeto. Alguns pontos dentro do retângulo delimitador podem não estar no objeto . Para objetos não retangulares, como itens de exibição de lista no modo de ícone grande, em que um único item tem um retângulo para o ícone e outro retângulo para o texto do ícone, as coordenadas do retângulo delimitador do objeto recuperado por IAccessible::accLocation podem falhar se testados com accHitTest .

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.

Quando esse método é usado em determinadas situações, as notas de uso adicionais se aplicam. Para obter mais informações, consulte Navegação por meio de teste de clique e local da tela.

Exemplo de servidor

O código de exemplo a seguir mostra uma possível implementação para uma caixa de listagem personalizada.


// m_pControl is the control that returns this accessible object. 
// m_hwnd is the HWND of the control window. 
//  
HRESULT STDMETHODCALLTYPE AccServer::accHitTest( 
    long xLeft,
    long yTop,
    VARIANT *pvarChild) 

{
    POINT pt;
    pt.x = xLeft;
    pt.y = yTop;

    // Not in our window. 
    if (WindowFromPoint(pt) != m_hwnd)
    {
        pvarChild->vt = VT_EMPTY;
        return S_FALSE;
    }

    else  // In our window; return list item, or self if in blank space. 
    {
        pvarChild->vt = VT_I4;
        ScreenToClient(m_hwnd, &pt);
        // IndexFromY returns the 0-based index of the item at that point, 
        // or -1 if the point is not on any item.
        int index = m_pControl->IndexFromY(pt.y);
        if (index >= 0)
        {
            // Increment, because the child array is 1-based. 
            pvarChild->lVal = index + 1;
        }
        else
        {
            pvarChild->lVal = CHILDID_SELF;

        }
        return S_OK;
    }
};

Exemplo de cliente

A função de exemplo a seguir seleciona o item em um ponto especificado na tela dentro da lista representada por pAcc. Supõe-se que uma única seleção seja desejada.


HRESULT SelectItemAtPoint(IAccessible* pAcc, POINT point)
{
    if (pAcc == NULL)
    {
        return E_INVALIDARG;
    }
    VARIANT varChild;

    HRESULT hr = pAcc->accHitTest(point.x, point.y, &varChild);        
    if ((hr == S_OK) && (varChild.lVal != CHILDID_SELF))
    {
        return pAcc->accSelect((SELFLAG_TAKEFOCUS | SELFLAG_TAKESELECTION), varChild);
    }
    return S_FALSE;
}

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