IAccessible::accHitTest-Methode (oleacc.h)

Artikel
03/04/2024

Die IAccessible::accHitTest-Methode ruft das untergeordnete Element oder untergeordnete Objekt ab, das an einem bestimmten Punkt auf dem Bildschirm angezeigt wird. Alle visuellen Objekte unterstützen diese Methode, Soundobjekte jedoch nicht. Clientanwendungen rufen diese Methode selten direkt auf. Um das barrierefreie Objekt abzurufen, das an einem Punkt angezeigt wird, verwenden Sie die AccessibleObjectFromPoint-Funktion , die diese Methode intern aufruft.

Syntax

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

Parameter

[in] xLeft

Typ: long

Gibt die Bildschirmkoordinaten des Punkts an, der getestet wird. Die x-Koordinaten erhöhen sich von links nach rechts. Beachten Sie, dass bei Verwendung von Bildschirmkoordinaten der Ursprung die obere linke Ecke des Bildschirms ist.

[in] yTop

Typ: long

Gibt die Bildschirmkoordinaten des Punkts an, der getestet wird. Die y-Koordinaten erhöhen sich von oben nach unten. Beachten Sie, dass bei Verwendung von Bildschirmkoordinaten der Ursprung die obere linke Ecke des Bildschirms ist.

[out, retval] pvarChild

Typ: VARIANT*

[out, retval] Adresse eines VARIANT-Objekts , das das Objekt identifiziert, das an dem von xLeft und yTop angegebenen Punkt angezeigt wird. Die in pvarID zurückgegebenen Informationen hängen von der Position des angegebenen Punkts in Bezug auf das Objekt ab, dessen accHitTest-Methode aufgerufen wird.

Punktposition	vt-Member	Wertelement
Außerhalb der Grenzen des Objekts und entweder innerhalb oder außerhalb des umgebenden Rechtecks des Objekts.	VT_EMPTY	Keine.
Innerhalb des -Objekts, aber nicht in einem untergeordneten Element oder einem untergeordneten Objekt.	VT_I4	lVal ist CHILDID_SELF.
Innerhalb eines untergeordneten Elements.	VT_I4	lVal enthält die untergeordnete ID.
Innerhalb eines untergeordneten Objekts.	VT_DISPATCH	pdispVal ist auf den IDispatch-Schnittstellenzeiger des untergeordneten Objekts festgelegt.

Rückgabewert

Typ: HRESULT

Gibt bei Erfolg S_OK zurück.

Wenn dies nicht erfolgreich ist, gibt einen der Werte in der folgenden Tabelle oder einen anderen COM-Standardfehlercode zurück. Server geben diese Werte zurück, aber Clients müssen ausgabeparameter immer überprüfen, um sicherzustellen, dass sie gültige Werte enthalten. Weitere Informationen finden Sie unter Überprüfen von IAccessible-Rückgabewerten.

Fehler	BESCHREIBUNG
S_FALSE	Der Punkt befindet sich außerhalb der Objektgrenzen. Das vt-Element von pvarID ist VT_EMPTY.
DISP_E_MEMBERNOTFOUND	Diese Methode wird vom -Objekt nicht unterstützt.
E_INVALIDARG	Ein Argument ist ungültig.

Hinweis für Cliententwickler: Obwohl Server S_FALSE zurückgeben, wenn das vt-Member von pvarID VT_EMPTY ist, müssen Clients auch den Fall behandeln, in dem pvarID-vt> VT_EMPTY und der Rückgabewert S_OK ist.

Hinweise

Wenn sich der getestete Punkt auf einem der untergeordneten Elemente des Objekts befindet und dieses untergeordnete Element die IAccessible-Schnittstelle selbst unterstützt, sollte diese Methode einen IAccessible-Schnittstellenzeiger zurückgeben. Clients sollten jedoch darauf vorbereitet sein, einen IAccessible-Schnittstellenzeiger oder eine untergeordnete ID zu verarbeiten. Weitere Informationen finden Sie unter Verwenden untergeordneter IDs in Parametern.

Da accLocation ein umgebendes Rechteck zurückgibt, sind nicht alle Punkte in diesem Rechteck innerhalb der tatsächlichen Begrenzungen des Objekts. Einige Punkte innerhalb des begrenzungsenden Rechtecks sind möglicherweise nicht auf dem Objekt. Bei nicht rechteckigen Objekten, z. B. Listenansichtselementen im Modus mit großen Symbolen, bei denen ein einzelnes Element über ein Rechteck für das Symbol und ein anderes Rechteck für den Text des Symbols verfügt, können die Koordinaten des umgebenden Rechtecks des Objekts, das von IAccessible::accLocation abgerufen wird, fehlschlagen, wenn sie mit accHitTest getestet wurden.

Wie bei anderen IAccessible-Methoden und Funktionen erhalten Clients aufgrund einer Benutzeraktion möglicherweise Fehler für IAccessible-Schnittstellenzeiger . Weitere Informationen finden Sie unter Empfangen von Fehlern für IAccessible-Schnittstellenzeiger.

Wenn diese Methode in bestimmten Situationen verwendet wird, gelten zusätzliche Verwendungshinweise. Weitere Informationen finden Sie unter Navigation durch Treffertests und Bildschirmstandort.

Serverbeispiel

Der folgende Beispielcode zeigt eine mögliche Implementierung für ein benutzerdefiniertes Listenfeld.


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

Clientbeispiel

Die folgende Beispielfunktion wählt das Element an einem angegebenen Punkt auf dem Bildschirm innerhalb der liste aus, die von pAcc dargestellt wird. Es wird davon ausgegangen, dass eine einzelne Auswahl gewünscht ist.


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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	oleacc.h
Bibliothek	Oleacc.lib
DLL	Oleacc.dll
Verteilbare Komponente	Active Accessibility 1.3 RDK unter Windows NT 4.0 mit SP6 und höher und Windows 95