StopPenInput

2.0

Terminates collection of pen input.

int StopPenInput( HPCM hpcm, UINT idEvent, int nTermReason )

Parameters
hpcm

Handle to the collection of the pen data gathered during the input session. HPCM stands for "handle to a pen collection mode."

idEvent

The identifier of the packet in the task-specific queue at which the pen input should be terminated. If this value is PID_CURRENT, pen input stops immediately (that is, at the latest position in the task queue) and no further input is collected. The idEvent parameter is the low-order word of the value returned from the Windows GetMessageExtraInfo function when processing a WM_LBUTTONDOWN message.

nTermReason

The reason for termination. This value is passed to the termination message PE_TERMINATED. It can be one of the following:

Constant	Description
PCMR_APPTERMINATED	Application terminated input.
PCMR_TERMBOUND	Pen was pressed outside bounding rectangle or region.
PCMR_TERMEX	Pen was pressed inside exclusion rectangle or region.
PCMR_TERMPENUP	Pen was lifted from the tablet.
PCMR_TERMRANGE	Pen left the tablet's range of sensitivity.
PCMR_TERMTIMEOUT	Time-out expired.

Return Value
Returns PCMR_OK if successful; otherwise, the return value can be one of the following:

Constant	Description
PCMR_INVALIDCOLLECTION	The hpcm handle is invalid because the calling application did not start input with StartPenInput.
PCMR_INVALID_PACKETID	idEvent is invalid.

Comments
This function allows an application to explicitly terminate pen collection without waiting for one of the conditions specified by StartPenInput in the dwPcm member of PCMINFO.

Due to the asynchronous nature of pen input messages, the application should wait for the WM_PENEVENT message with wParam set to PE_TERMINATED to make sure that the pen input process has completely terminated. This does not apply if the application is using the polling method of pen input.