IViewObjectEx::QueryHitPoint (Compact 2013)

3/26/2014

This method indicates whether a point is within a given aspect of an object.

Syntax

HRESULT QueryHitPoint(
  DWORD dwAspect,
  LPRECT pRectBounds,
  POINTL ptlLoc,
  LONG lCloseHint,
  DWORD* pHitResult
);

Parameters

• dwAspect
  [in] Requested drawing aspect.

• pRectBounds
  [in] Long pointer to the object-bounding rectangle, in client coordinates, of the containing window. The container computes and passes this rectangle so that the object can meaningfully interpret the hit location.

• ptlLoc
  [in] Hit location, in client coordinates, of the containing window.

• lCloseHint
  [in] Suggested distance, in HIMETRIC units, that the container considers close. This value is a hint, and objects can interpret it in their own way. Objects can also use this hint to roughly infer output resolution to choose the expansiveness of hit-test implementation.

• pHitResult
  [out] Pointer to returned information about the hit, expressed as the HITRESULT enumeration values.

Return Value

The following table shows the possible return values.

Remarks

To support hit detection on non-rectangular objects, the container needs a reliable way to determine from an object whether a given location is inside one of its drawing aspects. The IViewObjectEx::QueryHitPoint method provides this functionality.

Because this method is part of the IViewObjectEx interface, the container can determine whether a mouse hit is over an object without necessarily having to start the server. If the hit happens to be inside the object, it is likely that the object will be activated in place and the server started.

Typically, the container first quickly determines whether a given location is within the bounding rectangle of an object. If it is, the container calls QueryHitPoint to get confirmation that the location is actually inside the object itself.

The hit location is passed in client coordinates of the container window. Because the object might be inactive when this method is called, the bounding rectangle of the object in the same coordinate system is also passed to this method, in a manner similar to what happens in IPointerInactive::OnInactiveSetCursor.

Possible returned values include the following:

• Outside, on a transparent region
• Close enough to be considered a hit (which can be used by small or thin objects)
• Hit

QueryHitPoint is not concerned with the sub-objects of the object it is called for; it merely indicates whether the mouse hit was within the object.

QueryHitPoint can be called for any of the drawing aspects an object supports. If it is not supported for the requested drawing aspect, it should fail.

With transparent objects, it might be best to implement a complex hit-detection mechanism where the user can select either the transparent object or an object behind it, depending on where exactly the click happens inside the object. For example, a transparent text box that shows large enough text might let the user select the object behind a bitmap when the user clicks between the characters.

To accommodate complex hit-detection mechanisms, the information that QueryHitPoint returns includes indication of whether the hit happens on an opaque or transparent region.

The following illustrations show a transparent circle object with a line object behind it. Each image illustrates the different hit-detection results caused by the tip of the mouse pointer on the circle object. Gray regions are not part of the objects, but they are shown to indicate the area around each object that is considered close to that object.

Outside	Close
Hit	Transparent Note: The bottom arrow is in the Transparent area of the circle, but in the Close area of the line.

Each object implements its own definition of close, but is assisted by a hint that the container provides so that closeness can be adjusted as images zoom larger or smaller.

In the previous illustration, the points marked Hit, Close, and Transparent are all hits of varying strength on the circle, with the exception of the one marked Transparent, (but for the line, Close).

The illustration shows the effect of the different strength of hits. Because the circle responds to the Transparent hit while the line claims the Close hit, and Transparent is weaker than Close, the line takes the hit.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

An object that supports IViewObjectEx is required to implement this method at least for the DVASPECT_CONTENT aspect. The object should not take any action in response to this method other than to return the information; there should be no side effects such as visually changing the object or modifying the internal data to change future behavior.

Requirements

See Also

Reference

IViewObjectEx
HITRESULT