Collecting and Displaying Data - Microsoft Windows Pen API Programmer's Reference (penapi.hlp)

Microsoft Windows Pen API
Programmer's Reference

Collecting and Displaying Data

After initializing the necessary structures, the application calls StartPenInput to begin the process of collecting ink data:

hpcm = StartPenInput( hwnd, LOWORD (lExtraInfo),

(LPPCMINFO) &pcm, NULL );

The returned value hpcm is a handle to the pen collection mode

that is, the input session

that StartPenInput begins. The variable lExtraInfo is the value returned by GetMessageExtraInfo called when first processing the message WM_LBUTTONDOWN (see the preceding code fragment). Note that the StartPenInput call initiates ink collection, not ink display. The application must take separate steps to begin inking immediately after StartPenInput returns.

Inking is the process of displaying a trail of bits behind the tip of the pen as it moves across the surface of the digitizer, simulating the ink dropped by a real pen. If necessary, an application can take on the burden of real-time inking by hooking hardware interrupts with SetPenHook and calling the appropriate graphics device interface (GDI) functions to incrementally display ink. However, the Pen API provides a much simpler and more convenient method with the StartInking function.

As the PCMINFO structure governs StartPenInput, the INKINGINFO structure determines how StartInking operates. To turn on inking with StartInking, an application supplies the handle returned by StartPenInput and a pointer to the initialized INKINGINFO structure, like this:

iRet = StartInking( hpcm, LOWORD (lExtraInfo),

(LPINKINGINFO) &ink );

StartInking offers flexibility in how it displays ink. By modifying values in the INKINGINFO structure, an application can change ink color as the pen moves over a specified screen area or it can prevent ink from overwriting a screen object. With the wFlags member of INKINGINFO, an application can request automatic screen restoration to erase the ink. In this case, Windows replaces the ink trail with the original screen contents overwritten by the ink. This is much faster and simpler than repainting an entire window. Alternatively, an application can prevent ink erasure when pen input ends if, for example, it wants to preserve annotations or other handwritten notes on the screen. The StartInking function allows both scenarios.

When StartPenInput returns, a stream of WM_PENEVENT messages begins to arrive at the application window procedure. These messages contain submessages that represent current pen activity, such as PE_TERMINATING, PE_PENMOVE, PE_PENDOWN, and PE_PENUP. These submessages represent milestones in the system's ongoing process of collecting data from the pen driver. Each message affords an application the opportunity to gather the raw pen data that has accumulated since the last WM_PENEVENT message.

Windows maintains an internal buffer for data collection, informally named "the ten-second buffer" as a reminder of its limitations. An application should regularly drain the internal buffer by copying data from it at every opportunity afforded by the WM_PENEVENT messages. If it responds to no other event, the application must at least collect data when it receives the PE_BUFFERWARNING submessage, which indicates the internal buffer is more than half full.

To gather the data, an application calls GetPenInput. This can be done either in a polling model or in an event-driven model.

In the polling model, the application must repeatedly call GetPenInput to get data. It is important for the application to yield periodically; for example, by calling the PeekMessage function. 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 in response to each WM_PENEVENT message. The following fragment shows a typical message handler that accumulates ink coordinates in an array of POINT structures. The example assumes StartPenInput has already been called:

POINT rgPt[MAX_POINTS]; // Array of POINT structures

STROKEINFO si; // Receives pen stroke info

switch (wParam) // Process WM_PENEVENT message

{

case PE_PENDOWN: // On any of these events,

case PE_PENMOVE: // get all points currently

case PE_PENUP: // in the internal buffer

case PE_TERMINATING:

case PE_BUFFERWARNING:

GetPenInput( hpcm, (LPPOINT) rgPt, NULL, NULL,

MAX_POINTS, (LPSTROKEINFO) &si );

// Latest batch of pen coordinates is now collected

// into rgPt array. At this point, the coordinates can be:

// (1) Passed to a recognizer (or recognizers)

// (2) Passed to a target or control

// (3) Placed into an HPENDATA object

break;

case PE_TERMINATED:

// Input session has ended. Do any required

// clean-up work and display the results.

break;

The example continually calls GetPenInput while the pen is in motion until it receives a PE_TERMINATING submessage, indicating the data flow is about to stop. Windows sends a PE_TERMINATING message when it detects one of the termination conditions specified in the PCMINFO structure. Typically, the input session ends when the user taps the pen outside a given tablet area or when a specified period of pen inactivity elapses.

An application may need to call StopPenInput to stop further data collection. The call to StopPenInput is not necessary if the input session ends because of a condition defined in the PCMINFO structure. In this case, the system calls StopPenInput internally. However, if the application terminates the input session for any other reason, it must call StopPenInput explicitly. Unless your application defines all possible termination conditions in a PCMINFO structure, it should call StopPenInput on detection of a condition that requires termination. Even if the system has already called the function, subsequent calls do no harm.

The preceding description also applies to StopInking, provided the application has called StartInking to display ink. The system calls StopInking automatically if it detects one of the termination conditions defined in the PCMINFO structure; otherwise, the application should call StopInking explicitly when required.

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
OLE Programmer's Reference (ole.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (tapi.hlp)
Unix Manual Pages

greatis just4fun network