System Events and Mouse Messages
Your application incorporates optimal design and usage of the tablet pen by sending both Microsoft Windows mouse messages and system events. Applications receive both sets of events for each pen movement or action. The application then chooses the appropriate event to use based on the context of the action. Windows mouse messages work well for pointing and selecting activities, and you should use them for activities that involve interaction with user interface (UI) elements. Pen events work well for real-time ink application, pen actions, and handwriting.
Note
Both pen events and mouse messages are sent to an application, regardless of whether the pen or the mouse is used.
Distinguishing Pen Input from Mouse and Touch
When your application receives a mouse message (such as WM_LBUTTONDOWN), it may call the GetMessageExtraInfo function to evaluate whether the message originated from a pen or a mouse device.
The value returned from GetMessageExtraInfo needs to be mask-checked against 0xFFFFFF00, and then compared with 0xFF515700. The following definitions may make this clearer:
#define MI_WP_SIGNATURE 0xFF515700
#define SIGNATURE_MASK 0xFFFFFF00
#define IsPenEvent(dw) (((dw) & SIGNATURE_MASK) == MI_WP_SIGNATURE
If the comparison is true, then this mouse message was generated by a Tablet PC pen or touch screen. In all other cases, you can assume that this message was generated by a mouse device.
The lower 8 bits returned from GetMessageExtraInfo are variable. Of those bits, 7 (the lower 7, masked by 0x7F) are used to represent the cursor ID, zero for the mouse or a variable value for the pen ID. Additionally, in Windows Vista, the eighth bit, masked by 0x80, is used to differentiate touch input from pen input (0 = pen, 1 = touch).
See Pointer Device Input and Touch Input for more info.
Supported System Gestures
The following table lists system gestures currently included in Windows XP Tablet PC Edition, details the corresponding pen actions and system events, and shows how they relate to traditional mouse actions.
| Pen gesture | Mouse action | Pen gesture description | Event messages | Mouse messages | Behaviors in Windows-based applications |
|---|---|---|---|---|---|
| Tap |
Left-click |
Tap the screen once with the pen. |
ISG_TAP sent when pen is lifted. |
WM_LBUTTONDOWN and WM_LBUTTONUP sent when pen lifted. |
Choose command from menu or toolbar, take action if command chosen, set insertion point (IP), show selection feedback. |
| Double-tap |
Double-click |
Tap screen twice in quick succession. |
ISG_DOUBLETAP sent on second tap (down). ISG_TAP event sent on the first tap. |
WM_LBUTTONDBLCLK sent on second tap (down). WM_LBUTTONDOWN and WM_LBUTTONUP sent on first tap (up) as for a single tap. |
Select word, open file or folder. |
| Press and hold |
Right-click |
Tap the screen and hold until a mouse icon appears, and then lift the pen to display a shortcut menu. An application could choose to perform an action different from showing a right-click menu when the pen is lifted. |
ISG_HOLDENTER sent when the pen has been down long enough. ISG_RIGHTTAP sent when pen is lifted and right-click occurs. |
WM_RBUTTONDOWN and WM_RBUTTONUP sent when right click occurs (when pen is lifted). |
Show shortcut menu. |
| Hold-through |
Left-click |
Tap the screen and hold until the mouse icon appears and disappears. Users are likely to do this when they accident-tally press and hold and want to revert to just tap. |
ISG_TAP sent when pen is lifted. |
WM_LBUTTONDOWN and WM_LBUTTONUP sent when pen is lifted. |
Left-click for a long time. No mouse equivalent exists. This is a fallback for when a user performs press-and-hold for a long time. The event reverts to being a tap. |
| Drag |
Left-drag |
Tap the screen to select the object that is to be moved, and then drag after the object is selected. |
ISG_DRAG sent when drag starts. |
WM_LBUTTONDOWN sent when drag starts, followed by a series of mouse move messages, and followed by a WM_LBUTTONUP event. |
Drag-select, as in Microsoft Word when starting with an IP; select multiple words; drag, as when dragging an object in Windows; scrolling. |
| Press and hold followed by a drag |
Right-drag |
Tap the screen to select the object that is to be moved. Hold until the mouse icon appears, and then drag to move the object. Lift the pen to display a shortcut menu. |
ISG_HOLDENTER sent when pen has been down for some time. ISG_RIGHTDRAG sent when drag starts. |
WM_RBUTTONDOWN sent when drag starts, followed by a series of mouse move messages, followed by a WM_RBUTTONUP event. |
Drag, as when dragging an object or selection followed by a context menu. |
| Pen hover |
Mouse hover |
Hold the pen steady at a small distance from the screen. |
ISG_HOVERENTER event sent initially. When hover interval is completed, ISG_HOVERLEAVEis sent. |
No mouse message equivalent. |
Show ToolTip, roll-over effects, and other mouse hover behaviors. |
| In-air shake |
Show Tablet PC Input Panel. No mouse equivalent. |
Move the pen quickly from side to side, holding the tip above, but within range of, the screen. |
Event is not passed to the application. |
No mouse message equivalent. |
New, specific to Tablet PC. |
Specifying Stylus and Touch Interactions
By default, your window will receive all system gesture events and use the default interaction model. Some pieces of this model may interfere with your application, so you may disable them selectively by responding to the WM_TABLET_QUERYSYSTEMGESTURESTATUS Message in your WndProc.