NearestPoint Method [InkDisp Class]

  • Article

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)

Applies To