nf-ocidl-iviewobjectex-queryhitrect.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:ocidl.IViewObjectEx.QueryHitRect	IViewObjectEx::QueryHitRect (ocidl.h)	Indicates whether any point in a rectangle is within a given drawing aspect of an object.	IViewObjectEx interface [COM] QueryHitRect method IViewObjectEx.QueryHitRect IViewObjectEx::QueryHitRect QueryHitRect QueryHitRect method [COM] QueryHitRect method [COM] IViewObjectEx interface _ole_iviewobjectex_queryhitrect com.iviewobjectex_queryhitrect ocidl/IViewObjectEx::QueryHitRect	com\iviewobjectex_queryhitrect.htm	com	eb155424-e74c-497f-a9c0-33ed3b2b5513	12/05/2018	IViewObjectEx interface [COM],QueryHitRect method, IViewObjectEx.QueryHitRect, IViewObjectEx::QueryHitRect, QueryHitRect, QueryHitRect method [COM], QueryHitRect method [COM],IViewObjectEx interface, _ole_iviewobjectex_queryhitrect, com.iviewobjectex_queryhitrect, ocidl/IViewObjectEx::QueryHitRect	ocidl.h		Windows	Windows 2000 Professional [desktop apps only]	Windows 2000 Server [desktop apps only]					OCIdl.idl								Windows			19H1	IViewObjectEx::QueryHitRect ocidl/IViewObjectEx::QueryHitRect	c++	APIRef kbSyntax	COM	OCIdl.h	IViewObjectEx.QueryHitRect

IViewObjectEx::QueryHitRect

-description

Indicates whether any point in a rectangle is within a given drawing aspect of an object.

-parameters

-param dwAspect [in]

The requested drawing aspect.

-param pRectBounds [in]

An 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.

-param pRectLoc [in]

The hit test rectangle, specified in HIMETRIC units, relative to the top-left corner of the object.

-param lCloseHint [in]

The 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 expansiveness of hit test implementation.

-param pHitResult [out]

A pointer to returned information about the hit expressed as the HITRESULT enumeration values.

-returns

This method returns S_OK on success. Other possible return values include the following.

Return code	Description
E_FAIL	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.

 

Notes to Implementers

An object supporting IViewObjectEx 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 instance 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.

-see-also

HITRESULT

IViewObjectEx