NearestPoint Method [InkDisp Class]
NearestPoint Method [InkDisp Class] |
Retrieves the IInkStrokeDisp within the InkDisp object that is nearest to a known point, optionally providing the index of the nearest point and the distance to the stroke from the specified point.
Declaration
[C++]
HRESULT NearestPoint(
[in] long X,
[in] long Y,
[in, out, optional, defaultvalue(0)] float * pointOnStroke,
[in, out, optional, defaultvalue(0)] float *distanceFromPacket,
[out, retval] IInkStrokeDisp **Stroke
);
[Microsoft® Visual Basic® 6.0]
Public Function NearestPoint( _
X As Long, _
Y As Long, _
[pointOnStroke As Single], _
[distanceFromPacket As Single] _
) As IInkStrokeDisp
Parameters
X
[in] The x-position in ink space of the point.
Y
[in] Specifies the y-position in ink space of the point.
pointOnStroke
[in, out] Retrieves the point on the line of the stroke that is closest to the specified point within the InkDisp object. For example, a value of 1.5 indicates that the point falls halfway between the first and second packets of the stroke. This parameter can be NULL (vbNull in Visual Basic 6.0, which must be specified if using late binding).
distanceFromPacket
[in, out] Retrieves the distance between the specified point in ink space and the nearest stroke in the InkDisp object. This parameter can be NULL (vbNull in Visual Basic 6.0, which must be specified if using late binding).
Stroke
[out] Returns the IInkStrokeDisp that contains a point that is closest to the specified point in the InkDisp object. If more than one stroke contains a point that is the same distance from the specified point, the value of this result is arbitrary.
Return Value
| HRESULT value | Description |
|---|---|
| S_OK | Success. |
| E_POINTER | A parameter contained an invalid pointer. |
| E_FAIL | An unspecified error occurred. |
| E_INK_EXCEPTION | An exception occurred inside the method. |
| E_OUTOFMEMORY | Cannot allocate memory operation. |
Remarks
The output point parameter is defined as a floating-point number because the point on the line of the stroke can fall between two physical coordinate points. Use this value to split the stroke with the Split method, or round the value up or down to index a packet in the stroke.
The distanceFromPacket parameter describes the distance from the point to the envelope of the stroke. This is the distance between the two points minus half the width of the stroke.
Example
[Visual Basic 6.0]
This Visual Basic 6.0 example shows how to find the nearest stroke to a known point in ink space, along with the location of the nearest point in the stroke in thePointInStroke and the distance in ink space between the known point and the nearest point on the stroke in theDistance.
Dim thePointInStroke As Single
Dim theDistance As Single
Dim theNearestStroke As IInkStrokeDisp
Set theNearestStroke = theInkCollector.Ink.NearestPoint(X, Y, _
thePointInStroke, theDistance)