IViewObjectEx::QueryHitPoint-Methode (ocidl.h)

Artikel
08/25/2023

Gibt an, ob sich ein Punkt innerhalb eines bestimmten Aspekts eines Objekts befindet.

Syntax

HRESULT QueryHitPoint(
  [in]  DWORD   dwAspect,
  [in]  LPCRECT pRectBounds,
  [in]  POINT   ptlLoc,
  [in]  LONG    lCloseHint,
  [out] DWORD   *pHitResult
);

Parameter

[in] dwAspect

Der angeforderte Zeichnungsaspekt.

[in] pRectBounds

Ein umschließendes Objektrechteck in Clientkoordinaten des enthaltenden Fensters. Dieses Rechteck wird berechnet und vom Container übergeben, damit das Objekt die Trefferposition sinnvoll interpretieren kann.

[in] ptlLoc

Die Trefferposition in Clientkoordinaten des enthaltenden Fensters.

[in] lCloseHint

Vorgeschlagene Entfernung in HIMETRIC-Einheiten , die vom Container als nahe betrachtet werden. Dieser Wert ist ein Hinweis, und Objekte können ihn auf eigene Weise interpretieren. Objekte können diesen Hinweis auch verwenden, um die Ausgabeauflösung grob abzuleiten, um die Erweiterbarkeit der Treffertestimplementierung auszuwählen.

[out] pHitResult

Ein Zeiger auf zurückgegebene Informationen zum Treffer, ausgedrückt als HITRESULT-Enumerationswerte .

Rückgabewert

Diese Methode gibt bei Erfolg S_OK zurück. Weitere mögliche Rückgabewerte:

Rückgabecode	Beschreibung
E_FAIL	Diese Methode ist für den angeforderten Aspekt nicht implementiert. Verwenden Sie stattdessen DVASPECT_CONTENT .

Hinweise

Um die Treffererkennung für nicht rechteckige Objekte zu unterstützen, benötigt der Container eine zuverlässige Möglichkeit, ein Objekt zu fragen, ob sich eine bestimmte Position in einem seiner Zeichnungsaspekte befindet. Diese Funktion wird von IViewObjectEx::QueryHitPoint bereitgestellt.

Hinweis Da diese Methode Teil der IViewObjectEx-Schnittstelle ist, kann der Container ermitteln, ob ein Maustreffer über ein Objekt erfolgt, ohne den Server unbedingt starten zu müssen. Wenn sich der Treffer im Objekt befindet, wird das Objekt wahrscheinlich direkt aktiviert und der Server gestartet.

In der Regel bestimmt der Container zunächst schnell, ob sich eine bestimmte Position innerhalb des rechteckigen Bereichs eines Objekts befindet. Wenn sich die Position innerhalb der rechteckigen Ausdehnung eines Objekts befindet, ruft der Container IViewObjectEx::QueryHitPoint auf, um die Bestätigung zu erhalten, dass sich die Position tatsächlich innerhalb des Objekts befindet. Die Trefferposition wird in Clientkoordinaten des Containerfensters übergeben. Da das Objekt beim Aufrufen dieser Methode möglicherweise inaktiv ist, wird das umgebende Rechteck des Objekts im selben Koordinatensystem ebenfalls an diese Methode übergeben, ähnlich wie in IPointerInactive::OnInactiveSetCursor.

Mögliche zurückgegebene Werte sind:

Außen, in einer transparenten Region
Nah genug, um als Treffer angesehen zu werden (kann von kleinen oder dünnen Objekten verwendet werden)
Getroffen

IViewObjectEx::QueryHitPoint ist von den Unterobjekten des Objekts, für das es aufgerufen wird, nicht betroffen. Sie gibt lediglich an, ob der Maustreffer innerhalb des Objekts war oder nicht.

IViewObjectEx::QueryHitPoint kann für alle Zeichnungsaspekte aufgerufen werden, die von einem Objekt unterstützt werden. Es sollte ein Fehler auftreten, wenn der für den angeforderten Zeichnungsaspekt nicht unterstützt wird.

Transparente Objekte möchten möglicherweise einen komplexen Mechanismus zur Treffererkennung implementieren, bei dem der Benutzer entweder das transparente Objekt oder ein Objekt dahinter auswählen kann, je nachdem, wo genau der Klick innerhalb des Objekts erfolgt. Ein transparentes Textfeld mit ausreichend großem Text kann es dem Benutzer beispielsweise ermöglichen, das dahinter enthaltene Objekt auszuwählen, z. B. eine Bitmap, wenn der Benutzer zwischen den Zeichen klickt. Aus diesem Grund enthalten die von IViewObjectEx::QueryHitPoint zurückgegebenen Informationen Hinweise darüber, ob der Treffer in einem undurchsichtigen oder transparenten Bereich erfolgt.

Ein Beispiel für die nicht rechteckige und transparente Treffererkennung ist ein transparentes Kreissteuerelement mit einem Objekt dahinter (eine Zeile im folgenden Beispiel):

Diagramm eines Kreises mit einer diagonalen Linie, die die Treffererkennungswerte für die Bereiche innerhalb und außerhalb des Kreises und in der Nähe der Linie zeigt.

Die angezeigten Werte sind für Treffertests am Kreis; Graubereiche sind nicht Teil des Steuerelements, werden aber hier angezeigt, um einen Bereich um das Bild anzuzeigen, das als nah angesehen wird. Jedes Objekt implementiert seine eigene Definition von close, wird jedoch von einem Hinweis unterstützt, der vom Container bereitgestellt wird, sodass die Nähe angepasst werden kann, wenn Bilder vergrößert oder verkleinern.

In der obigen Abbildung wären die punkte, die als Treffer, Schließen und Transparent gekennzeichnet sind, alle Treffer mit unterschiedlicher Stärke auf dem Kreis, mit Ausnahme des als Transparent markierten Punktes (für die Linie jedoch schließend). Dies veranschaulicht die Wirkung der unterschiedlichen Trefferstärke. Da der Kreis transparent reagiert, während die Linie geschlossen werden soll und transparent schwächer als schließen ist, nimmt die Linie den Treffer.

Hinweise für Implementierer

Ein Objekt, das IViewObjectEx unterstützt, ist erforderlich, um diese Methode zumindest für den DVASPECT_CONTENT Aspekt zu implementieren. Das Objekt sollte als Reaktion auf diese Methode keine andere Aktion ausführen, außer die Informationen zurückzugeben. es sollte keine Nebenwirkungen geben.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ocidl.h

Weitere Informationen

HITRESULT

IPointerInactive::OnInactiveSetCursor

IViewObjectEx

Freigeben über