|
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
GetPenInput, StopPenInput, PCMINFO WM_PENEVENT, PCM_
| Last news from Greatis Software |
 |
|
Nostalgia .Net |
|
.Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More » |
| Recommended software for developers |
 |
|
Ultimate Pack |
|
Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More » |
 |
|
Form Designer .Net |
|
Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More » |
 |
|
Print Suite .Net |
|
Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More » |
 |
|
Gradient Controls .Net |
|
Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More » |
 |
|
Greatis iGrid |
|
iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More » |
All the contacts and projectsDmitry Vasiliev (just.dmitry)
Related LinksSoftware for Visual Studio .NET developers
Software for Delphi and C++ Builder developers
Software for Visual Basic 6 developers
Delphi Tips&Tricks
MegaDetailed.NET More Online Helps Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages
|
