IInkDisp::NearestPoint method (msinkaut.h)

Article
02/22/2024

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.

Syntax

HRESULT NearestPoint(
  [in]                long           X,
  [in]                long           Y,
  [in, out, optional] float          *PointOnStroke,
  [in, out, optional] float          *DistanceFromPacket,
  [out, retval]       IInkStrokeDisp **Stroke
);

Parameters

[in] X

The x- position in ink space of the point.

[in] Y

Specifies the y- position in ink space of the point.

[in, out, optional] PointOnStroke

Optional. 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. The default value is 0.

[in, out, optional] DistanceFromPacket

Optional. Retrieves the distance between the specified point in ink space and the nearest stroke in the InkDisp object. This parameter can be NULL. the default value is 0.

[out, retval] Stroke

When this method returns, contains 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

This method can return one of these values.

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

Requirements

Requirement	Value
Minimum supported client	Windows XP Tablet PC Edition [desktop apps only]
Minimum supported server	None supported
Target Platform	Windows
Header	msinkaut.h
Library	InkObj.dll