IStrokeBuilder::BeginStroke method (rtscom.h)

Article
02/22/2024

Begins a stroke on an ink object by using packet data from a RealTimeStylus Class object.

Syntax

HRESULT BeginStroke(
  [in]      TABLET_CONTEXT_ID tcid,
  [in]      STYLUS_ID         sid,
  [in]      const LONG        *pPacket,
  [in]      ULONG             cPacketProperties,
  [in]      PACKET_PROPERTY   *pPacketProperties,
  [in]      FLOAT             fInkToDeviceScaleX,
  [in]      FLOAT             fInkToDeviceScaleY,
  [in, out] IInkStrokeDisp    **ppIInkStroke
);

Parameters

[in] tcid

The tablet context identifier.

[in] sid

The stylus identifier.

[in] pPacket

The start of the packet data. It is read-only.

[in] cPacketProperties

The count of LONGs, which is the number of packets multiplied by the number of properties, in the pPacketProperties buffer.

[in] pPacketProperties

The buffer containing the packet properties.

[in] fInkToDeviceScaleX

The horizontal, or x-axis, conversion factor for the horizontal axis from ink space to digitizer coordinates.

[in] fInkToDeviceScaleY

The vertical, or y-axis, conversion factor for the vertical axis from ink space to digitizer coordinates.

[in, out] ppIInkStroke

A pointer to the new stroke. This value can be NULL.

Return value

For a description of return values, see RealTimeStylus Classes and Interfaces.

Remarks

Used in conjunction with the IStrokeBuilder::AppendPackets Method and IStrokeBuilder::EndStroke Method methods. IStrokeBuilder::BeginStroke Method starts building the stroke. As the motion continues and additional packets are received, the IStrokeBuilder::AppendPackets Method method adds that additional stroke data. When the tablet pen is raised from the surface and there are no more incoming packets, the IStrokeBuilder::EndStroke Method method is called.

Examples

The following C++ example shows the implementation of a IStylusPlugin::StylusDown Method method on an IStylusPlugin Interface object. The plug-in uses a StrokeBuilder object to create a new ink stroke. The IStrokeBuilder::BeginStroke Method method is called from IStylusPlugin::StylusDown Method to initiate the construction of a stroke.

STDMETHODIMP CStrokeBuilderPlugin::StylusDown( 
            /* [in] */ IRealTimeStylus *piRtsSrc,
            /* [in] */ const StylusInfo *pStylusInfo,
            /* [in] */ ULONG cPropCountPerPkt,
            /* [size_is][in] */ LONG *pPacket,
            /* [out][in] */ LONG **ppInOutPkt)
{
	FLOAT fInkToDeviceScaleX;
	FLOAT fInkToDeviceScaleY;
	ULONG cPacketProperties;
	PACKET_PROPERTY* pPacketProperties;

	// Get the info we need to call BeginStroke
	HRESULT hr = piRtsSrc->GetPacketDescriptionData(pStylusInfo->tcid, &fInkToDeviceScaleX, &fInkToDeviceScaleY, 
													&cPacketProperties, &pPacketProperties);

	if (SUCCEEDED(hr))
	{
		// Start creating the stroke
		hr = m_pStrokeBuilder->BeginStroke(pStylusInfo->tcid, pStylusInfo->cid, pPacket, cPropCountPerPkt, 
											pPacketProperties, fInkToDeviceScaleX, fInkToDeviceScaleY, &m_piStroke);
	}
	
	return hr;
}

Requirements

Requirement	Value
Minimum supported client	Windows XP Tablet PC Edition [desktop apps only]
Minimum supported server	None supported
Target Platform	Windows
Header	rtscom.h
DLL	RTSCom.dll