Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
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 HITRESULTenumeration 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::QueryHitRectto 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 IViewObjectExinterface 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

See Also

Reference

HITRESULT