IViewObjectEx::QueryHitRect
A version of this page is also available for
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.
Note
Unlike IViewObjectEx::QueryHitPoint, this method does not return HITRESULT_TRANSPARENT or HITRESULT_CLOSE. It is strictly hit or miss, returning HITRESULT_OUTSIDE if no point in the rectangle is hit and HITRESULT_HIT if at least one point in the rectangle is a hit.
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
| Header | ocidl.h, ocidl.idl |
| Library | ole32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |