StartPenInput
2.0
Begins
collecting information from the pen input stream.
HPCM StartPenInput( HWND hwnd, UINT idEvent,
LPPCMINFO lppcmInfo, LPINT lpiErrRet )
Parameters
hwnd
Handle of the
window that receives the WM_PENEVENT messages generated by StartPenInput.
idEvent
Identifies
the packet in the global queue of pen packets maintained internally by the
system. The idEvent is the low-order word of the value returned from the
GetMessageExtraInfo
function when processing a WM_LBUTTONDOWN message. For a definition of pen
packet, see the description for SetPenHook.
lppcmInfo
Address of a PCMINFO structure. If NULL, the
system creates a default PCMINFO structure with the following values:
|
Constant |
Description |
|
dwPcm |
PCM_RECTBOUND
| PCM_TIMEOUT | PCM_TAPNHOLD |
|
rectBound |
The
bounding rectangle of the window identified by hwnd These
values determine that the input session (a) terminates when pen activity
ceases for a specified time-out period; (b) terminates when the pen moves
outside the bounds of the window; or (c) does not begin at all if the user
taps and holds the pen for a specified time-out period (about one-half
second). This tap-and-hold gesture switches the system from input mode to
selection mode. Usually, the cursor changes from a pen (indicating input) to
an upside-down arrow (indicating selection) to acknowledge the switch.
Subsequent pen movement then behaves as a mouse with the left button held
down. This allows the user to make selections as though dragging the mouse. |
lpiErrRet
Address of an
integer that receives a return code when StartPenInput terminates. If
NULL, no return code is provided. If not NULL, the return code is one of the
following values:
|
Constant |
Description |
|
PCMR_OK |
Pen
collection was successfully started. |
|
PCMR_ALREADYCOLLECTING |
StartPenInput has already been called for this session. |
|
PCMR_ERROR |
Illegal
parameter or unspecified error. |
|
PCMR_INVALID_PACKETID |
Invalid idEvent
parameter. |
|
PCMR_SELECT |
Tap-and-hold
gesture detected. Collection is not started, as described in the description
of the lppcmInfo parameter. |
|
PCMR_TAP |
The pen has
briefly tapped the tablet. This event may be inadvertent and in any case does
not indicate that the user has started to write; therefore, collection is not
started. |
Return Value
Returns a
handle to the application s queue of pen packets, if successful. Returns NULL
to indicate an error or the detection of a tap or press-and-hold condition.
Comments
When this
function returns successfully, Windows creates a queue of pen packets for the
calling application. All subsequent pen packets from the pen device, beginning
with the packet identified by the idEvent argument, are placed into the
queue. Until a termination condition occurs (as specified in the lppcmInfo
parameter), or until the application calls StopPenInput, the queue continues to
receive all the packets generated by the pen device as the pen moves.
An
application can retrieve all the pen input in its queue of pen packets but
should never destroy the queue.
In event mode
(the default mode), the collection session specified by the hpcm of the GetPenInput function becomes invalid
when the WM_PENEVENT message (with the PE_TERMINATED submessage) is removed
from the application s message queue. This message is posted to the
application s message queue either as a consequence of automatic termination or
a call to StopPenInput.
In polling
mode, the application s queue of pen packets is destroyed (and the hpcm
of GetPenInput becomes invalid) after a successful call to StopPenInput
or a termination return value from the GetPenInput function.
If lppcmInfo
is NULL, a default PCMINFO
structure is established with the dwPcm member set to PCM_RECTBOUND |
PCM_TIMEOUT | PCM_TAPHOLD, the rectBound member set to the bounds of hwnd,
and the dwTimeout member set to the default system time out.
If the dwPcm
member of PCMINFO does not have the PCM_DOPOLLING flag set, WM_PENEVENT
messages are sent to the specified window for significant events such as pen
down, pen up, or after some threshold number of points has been received.
Otherwise, the application should poll for data using GetPenInput.
Other bits in
the dwPcm member of PCMINFO can be used to determine which
conditions, if any, terminate pen input. An application can also call StopPenInput to explicitly terminate the
input.
Example
The following
example initiates pen input in a window procedure on detection of pen down:
static HPCM vhpcm;
//... omitted ...
switch (message)
{
case WM_LBUTTONDOWN:
{
//
Get extra info associated with event:
DWORD
dwExtraInfo = GetMessageExtraInfo();
if
(IsPenEvent( message, dwExtraInfo )) //
Checks PDK bits
{
PCMINFO
pcminfo; // Pen collection mode
structure
pcminfo.cbSize = sizeof( PCMINFO );
pcminfo.dwPcm = PCM_RECTBOUND | PCM_TIMEOUT;
pcminfo.dwTimeout
= dwTimeOutDefault; // 1 second
//
Set inclusion rect to client area, but in screen coords:
GetClientRect(
hwnd, &pcminfo.rectBound );
ClientToScreen(
hwnd, (LPPOINT) &pcminfo.rectBound );
ClientToScreen(
hwnd, (LPPOINT) &pcminfo.rectBound.right );
//
Start gathering input:
if
(vhpcm = StartPenInput( hwnd,
LOWORD(
dwExtraInfo ), &pcminfo, NULL ))
return
1L; // We handled
it
}
//
Else fall into DefWindowProc below...
}
break;
See Also