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

Artículo
03/08/2023

El método IAccessible::accHitTest recupera el elemento secundario o el objeto secundario que se muestra en un punto específico de la pantalla. Todos los objetos visuales admiten este método, pero los objetos de sonido no. Las aplicaciones cliente rara vez llaman directamente a este método; para obtener el objeto accesible que se muestra en un momento, use la función AccessibleObjectFromPoint , que llama a este método internamente.

Sintaxis

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

Parámetros

[in] xLeft

Tipo: long

Especifica las coordenadas de pantalla del punto al que se ha alcanzado la prueba. Las coordenadas x aumentan de izquierda a derecha. Tenga en cuenta que cuando se usan coordenadas de pantalla, el origen es la esquina superior izquierda de la pantalla.

[in] yTop

Tipo: long

Especifica las coordenadas de pantalla del punto al que se ha alcanzado la prueba. Las coordenadas y aumentan de arriba a abajo. Tenga en cuenta que cuando se usan coordenadas de pantalla, el origen es la esquina superior izquierda de la pantalla.

[out, retval] pvarChild

Tipo: VARIANT*

[out, retval] Dirección de un variant que identifica el objeto mostrado en el punto especificado por xLeft e yTop. La información devuelta en pvarID depende de la ubicación del punto especificado en relación con el objeto al que se llama al método accHitTest .

Ubicación de punto	Miembro vt	Miembro de valor
Fuera de los límites del objeto y dentro o fuera del rectángulo delimitador del objeto.	VT_EMPTY	Ninguno.
Dentro del objeto pero no dentro de un elemento secundario o un objeto secundario.	VT_I4	lVal es CHILDID_SELF.
Dentro de un elemento secundario.	VT_I4	lVal contiene el identificador secundario.
Dentro de un objeto secundario.	VT_DISPATCH	pdispVal se establece en el puntero de interfaz IDispatch del objeto secundario.

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.

Error	Descripción
S_FALSE	El punto está fuera de los límites del objeto. El miembro vt de pvarID es VT_EMPTY.
DISP_E_MEMBERNOTFOUND	El objeto no admite este método.
E_INVALIDARG	Un argumento no es válido.

Tenga en cuenta a los desarrolladores cliente: Aunque los servidores devuelven S_FALSE si el miembro vt de pvarID es VT_EMPTY, los clientes también deben controlar el caso en el que pvarID-vt> es VT_EMPTY y el valor devuelto es S_OK.

Comentarios

Si el punto probado está en uno de los elementos secundarios del objeto y este elemento secundario admite la propia interfaz IAccessible , este método debe devolver un puntero de interfaz IAccessible . Sin embargo, los clientes deben estar preparados para controlar un puntero de interfaz IAccessible o un identificador secundario. Para obtener más información, vea Cómo se usan los identificadores secundarios en parámetros.

Dado que accLocation devuelve un rectángulo delimitador, no todos los puntos de ese rectángulo estarán dentro de los límites reales del objeto. Es posible que algunos puntos dentro del rectángulo delimitador no estén en el objeto . En el caso de objetos no rectangulares, como los elementos de vista de lista en modo de icono grande donde un único elemento tiene un rectángulo para el icono y otro rectángulo para el texto del icono, las coordenadas del rectángulo delimitador del objeto recuperado por IAccessible::accLocation podrían producir un error si se prueba con accHitTest .

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

Cuando se usa este método en determinadas situaciones, se aplican notas de uso adicionales. Para obtener más información, vea Navegación a través de pruebas de posicionamiento y ubicación de pantalla.

Ejemplo de servidor

En el código de ejemplo siguiente se muestra una posible implementación de un cuadro de lista personalizado.


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

Ejemplo de cliente

La siguiente función de ejemplo selecciona el elemento en un punto especificado de la pantalla dentro de la lista representada por pAcc. Se supone que se desea una única selección.


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