IStylusPlugin::StylusDown method (rtscom.h)

Article
02/22/2024

Notifies the implementing plug-in that the tablet pen has touched the digitizer surface.

Syntax

HRESULT StylusDown(
  [in]      IRealTimeStylus  *piRtsSrc,
  [in]      const StylusInfo *pStylusInfo,
  [in]      ULONG            cPropCountPerPkt,
  [in]      LONG             *pPacket,
  [in, out] LONG             **ppInOutPkt
);

Parameters

[in] piRtsSrc

The RealTimeStylus Class (RTS) object that sent the notification.

[in] pStylusInfo

A StylusInfo Structure containing the information about the RTS that is associated with the stylus.

[in] cPropCountPerPkt

Number of properties per packet. Valid values are 0 through 32, inclusive.

[in] pPacket

The start of the packet data.

[in, out] ppInOutPkt

A pointer to the modified stylus data packet. The plug-in can use this parameter to feed modified packet data to downstream packets. A value other than NULL indicates that the packet has been modified and RTS will send this data down to plug-ins by using the pPacket parameter.

Return value

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

Remarks

You can return an array of modified packets in the buffer, ppInOutPkt. Packets used by the IStylusPlugin::StylusUp Method and IStylusPlugin::StylusDown Method methods can only be changed. Packets used by the IStylusPlugin::Packets Method and IStylusPlugin::InAirPackets Method methods can be deleted.

If you modify packets, then cPropCountPerPkt, which is the number of LONGs in ppInOutPkt, must be divisible by the current desired packet properties (DPP) available on the current input device.

You can modify packets by updating the cPropCountPerPkt and ppInOutPkts parameters. Change cPropCountPerPkt to a valid total packet property count and change ppInOutPkts to pointer to a valid data buffer accounting for values for each DPP in every packet. Only one packet can be present at that location for IStylusPlugin::StylusUp Method and IStylusPlugin::StylusDown Method.

For example, if you add three packets and your DPP is currently X,Y and Pressure, then you must have nine LONG values in this buffer and set cPropCountPerPkt to 9.

The cPropCountPerPkt value is useful to help clarify the boundaries between packets in the flat array of integers that comes in for events such as the NewPackets Event event. Packets can be bundled in order to be more efficient with data transfer, such that it is not required that a plug-in is called once per packet.

Examples

The following C++ code example implements a StylusDown method that calls a helper function, ModifyPacket, to change the value of the X,Y data to make it fall within a specified rectangle. This is the same functionality that is implemented in the C# sample, RealTimeStylus Plug-in Sample. The second code snippet is the ModifyPacket function.

STDMETHODIMP CPacketModifier::StylusDown( 
            /* [in] */ IRealTimeStylus *piRtsSrc,
            /* [in] */ const StylusInfo *pStylusInfo,
            /* [in] */ ULONG cPropCountPerPkt,
            /* [size_is][in] */ LONG *pPacket,
            /* [out][in] */ LONG **ppInOutPkt)
{
	return ModifyPacket(cPropCountPerPkt, pPacket, ppInOutPkt);
}

// Helper method to modify a single packet
// Called from StylusDown() and StylusUp()
HRESULT CPacketModifier::ModifyPacket(
            /* [in] */ ULONG cPropCountPerPkt,
            /* [size_is][in] */ LONG *pPacket,
            /* [out][in] */ LONG **ppInOutPkt)
{
	// Pointer to a buffer to hold changed packet values
	LONG* pTempOutPkt = NULL;
	
	// X and Y come first (0 and 1), 
	// other properties follow
	ULONG iOtherProps = 2;

	if (cPropCountPerPkt > 0)
	{
		pTempOutPkt = (LONG*)CoTaskMemAlloc(sizeof(LONG)*cPropCountPerPkt);

		if (NULL != pTempOutPkt)
		{
			// Packet data always has x followed by y followed by the rest.
			LONG x = pPacket[0];
			LONG y = pPacket[1];

			// In the packet data, check whether
			// its X,Y values fall outside of the specified rectangle.
			// If so, replace them with the nearest point that still
			// falls within the rectangle.
			x = (x < m_filterRect.left ? m_filterRect.left : x);
			x = (x > m_filterRect.right ? m_filterRect.right : x);
			y = (y < m_filterRect.top ? m_filterRect.top : y);
			y = (y > m_filterRect.bottom ? m_filterRect.bottom : y);

			// If necessary, modify the x,y packet data
			if ((x != pPacket[0]) || (y != pPacket[1]))
			{
				pTempOutPkt[0] = x;
				pTempOutPkt[1] = y;

				// Copy the properties that we haven't modified
				while (iOtherProps < cPropCountPerPkt)
				{
					pTempOutPkt[iOtherProps] = pPacket[iOtherProps++];
				}

				*ppInOutPkt = pTempOutPkt;
			}
			else
			{
				CoTaskMemFree(pTempOutPkt);
			}
		}
	}

	return S_OK;
}

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