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 GetMessageExtraInfo3P040HC function when processing a WM_LBUTTONDOWN message. For a definition of pen packet, see the description for SetPenHook232HBDD.

lppcmInfo

Address of a PCMINFO1AOCX8 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 StopPenInput1AOCU8, 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 GetPenInput1AOBY7 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 PCMINFO1AOCX8 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 GetPenInput1AOBY7.

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 StopPenInput1AOCU8 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

GetPenInput, StopPenInput, PCMINFO