GetPenInput - Microsoft Windows Pen API Programmer's Reference

Microsoft Windows Pen API Programmer's Reference

Home Index About

Custom Search

GetPenInput

Collects data after StartPenInput has started pen input.

int GetPenInput( HPCM hpcm, LPPOINT lppt, LPVOID lpvOem, UINT fuOemFlags, UINT cPntMax, LPSTROKEINFO lpsi )

Parameters
hpcm

Handle to the current collection. This is the return value from StartPenInput.

lppt

Address of an array of POINT structures. The array must consist of at least cPntMax structures.

lpvOem

The address of a buffer of OEM data associated with each point. This parameter can be NULL if the application does not require OEM data.

fuOemFlags

Flags specifying which OEM data to retrieve. If this parameter is NULL, all OEM data provided by the tablet is returned in the order specified by the rgoempeninfo array in PENINFO.

These flags have an implicit order. For example, if pressure and barrel rotation are specified, cPntMax pairs of these data are returned, in the order [pressure, rotation], [pressure, rotation], and so on.

Constant	Description
PHW_PRESSURE	Retrieve pressure data.
PHW_HEIGHT	Retrieve height data.
PHW_ANGLEXY	Retrieve data pertaining to the x- and y-coordinates.
PHW_ANGLEZ	Retrieve data pertaining to the z-coordinates.
PHW_BARRELROTATION	Retrieve barrel-rotation data.
PHW_OEMSPECIFIC	Retrieve OEM-specific data.
PHW_PDK	Retrieve per-point PDK_ information in OEM data.

cPntMax

The number of POINT structures in the array at lppt. This is the maximum number of points to return and also the maximum number of OEM items the buffer at lpvOem can hold.

lpsi

A pointer to a STROKEINFO structure. This structure receives information about the first point of the collection of points placed into the array at lppt. The cbPnts member contains the packet ID of the first point. All returned points in the collection have the same tip polarity (that is, up or down) as the first point.

Return Value
Returns 0 if there are no points available. If the return value is positive, the value is the number of points copied to the lppt (and, optionally, lpvOem) buffers. Otherwise, the return value is one of the following:

Constant	Description
PCMR_APPTERMINATED	Input has already terminated because the application called StopPenInput. There are no more points to retrieve.
PCMR_EVENTLOCK	An event must be taken out of the queue using the Windows functions PeekMessage or GetMessage before any more points can be retrieved using GetPenInput.
PCMR_INVALIDCOLLECTION	The hpcm handle is invalid because the calling application did not start input with StartPenInput.
PCMR_TERMTIMEOUT	Input has already terminated because the specified time-out period has elapsed.
PCMR_TERMRANGE	Input has already terminated because the pen has left the range of the tablet's zone of sensitivity.
PCMR_TERMPENUP	Input has already terminated because the pen was lifted from the tablet.
PCMR_TERMEX	Input has already terminated because the pen went down in a specified exclusion rectangle or region.
PCMR_TERMBOUND	Input has already terminated because the pen went down outside a specified bounding rectangle or region.

Comments
Once an application initiates pen-input collection by calling StartPenInput, the application then calls the GetPenInput function frequently to retrieve the actual data arriving from the pen device. This can be done by responding to hardware events or by continuously polling.

In the polling model, the application repeatedly calls GetPenInput to get data. It is important for the application to yield periodically; for example, by calling PeekMessage. A fast loop can potentially process the points before the system can collect more. In this case, successive calls to GetPenInput return 0 until the user writes some more. Polling is typically terminated when GetPenInput detects and returns a termination condition specified in StartPenInput.

In the event model, the application calls GetPenInput on receipt of a WM_PENEVENT message. All points up to this event are returned to the caller. An application can retrieve all available data in a short loop, until GetPenInput returns PCMR_EVENTLOCK. The application then falls out of the loop and exits the window procedure. The process begins again when the window procedure is called in response to another WM_PENEVENT message in the application's message queue.

If lpvOem is not NULL, the buffer must be large enough to hold cPntMax OEM data packets. The size of each packet is the width specified in the cbOemData member of the PENINFO structure, plus sizeof( UINT ) if PDK_ values are required.

Example
The following code example gathers more pen input for use by the recognizer. Assume the application has already called StartPenInput and is using the messaging collection model.

POINT rgPnt[cbBuffer];

STROKEINFO si;

// ... in WM_PENEVENT message handler:

switch (wParam)

{

case PE_PENUP:

case PE_PENMOVE:

case PE_TERMINATING:

// Get all the points collected since the last message

while ( (iRet = GetPenInput( hpcm, rgPnt, NULL, 0,

cbBuffer, &si) ) > 0)

{

// Add pen data to recognition context and def process

AddPenInputHRC( vhrc, rgPnt, NULL, 0, &si );

ProcessHRC( vhrc, PH_DEFAULT );

}

break;

See Also
PeekPenInput, StartPenInput, PDK_

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 projects

Dmitry Vasiliev (just.dmitry)

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

greatis just4fun network