Collecting and Displaying Data - Microsoft Windows Pen API Programmer's Reference

Microsoft Windows Pen API Programmer's Reference

Custom Search

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.

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