IViewObjectEx::QueryHitRect

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method indicates whether any point in a rectangle is within a given drawing aspect of an object.

Syntax

HRESULT QueryHitRect(
  DWORD dwAspect,
  LPRECT pRectBounds,
  LPRECT pRectLoc,
  LONG lCloseHint,
  DWORD* pHitResult
);

Parameters

• dwAspect
  [in] Requested drawing aspect.

• pRectBounds
  [in] Object bounding rectangle in client coordinates of the containing window. This rectangle is computed and passed by the container so that the object can meaningfully interpret the hit location.

• pRectLoc
  [in] Hit test rectangle specified in HIMETRIC units, relative to the top-left corner of the object.

• 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

If the method returns S_OK, the hit information was successfully returned in pHitResult.

If E_FAIL is returned, this method is not implemented for the requested aspect. Use DVASPECT_CONTENT instead.

Remarks

Containers may need to test whether an object overlaps a given drawing aspect of another object. They can determine whether the objects overlap by requesting a region or at least a bounding rectangle of the aspect in question.

However, a quicker way to do this is to call IViewObjectEx::QueryHitRect to ask the object whether a given rectangle intersects one of its drawing aspects.

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

Note to Implementers

An object supporting the IViewObjectEx interface is required to implement this method at least for the DVASPECT_CONTENT aspect. The object should not take any other action in response to this method other than to return the information; there should be no side effects.

If there is any ambiguity about whether a point is a hit, for example due to coordinates not converting exactly, the object should return HITRESULT_HIT whenever any point in the rectangle might be a hit on the object. That is, it is permissible to claim a hit for a point that is not actually rendered, but never correct to claim a miss for any point that is in the rendered image of the object.

Requirements

See Also

Reference

HITRESULT