Touch Panel Callback to GWES (Compact 2013)
3/26/2014
In order to support multi-touch, the touch proxy driver exports the TouchPanelEnableEx function. GWES calls this function to register its callback function. The touch driver calls the callback function to provide multi-touch data to GWES.
If GWES finds that there is no TouchPanelEnableEx function, it calls TouchPanelEnable instead. This is the function that Windows Embedded CE 6.0 provides for registering a callback function for single-touch data. When TouchPanelEnable exists but TouchPanelEnableEx does not, it means that the driver is a Windows Embedded CE 6.0 driver running under Compact 2013. In this case, GWES will only receive single-touch data even if the hardware is capable of providing multi-touch data.
The following example code shows the prototype of the multi-touch callback function provided to TouchPanelEnableEx.
typedef BOOL (* PFN_TOUCH_PANEL_CALLBACK_EX) (
DWORD cInputs,
PCETOUCHINPUT pInputs,
DWORD cbSize
);
The touch data is in the array of CETOUCHINPUT contact points that are pointed to by pInputs. Integer cInputs provides the number of elements of the contact points array. This can be one, two, or more. The driver supports more than two contact points, but GWES supports two at most and will ignore any more than that.
This is the CETOUCHINPUT structure defined in header file Tchddi.h.
typedef struct {
LONG x;
LONG y;
HANDLE hSource;
DWORD dwID;
DWORD dwFlags;
DWORD dwMask;
DWORD dwTime;
DWORD cxContact;
DWORD cyContact;
DWORD dwPropertyOffset;
DWORD cbProperty;
} CETOUCHINPUT, *PCETOUCHINPUT;
The structure and its members are described in detail in CETOUCHINPUT. Here is a brief description of some of the members:
- x and y give the location of the touch point.
- dwFlags is a bit mask that provides various characteristics of this touch point. The following flag values for this bit mask are defined in Winuser.h:
- TOUCHEVENTF_PRIMARY. The primary touch point, which is the first touch point after a previous state of no touch points. The flag is set for all events for the touch point. The touch proxy driver determines the setting of this flag.
GWES generates mouse messages WM_LBUTTONDOWN, WM_LBUTTONUP and WM_MOUSEMOVE for the primary touch point. - TOUCHEVENTF_CALIBRATED. The point does not need further calibration (used by the input system).
- TOUCHEVENTF_SYMMETRIC. The touch point is associated with a symmetric (rather than true) multi-touch screen. See Types of Touch Panels for an explanation of why the x and y values may not be accurate for this type of controller.
- TOUCHEVENTF_MOVE. Movement occurred. This flag cannot be set in the same sample as TOUCHEVENTF_DOWN.
- TOUCHEVENTF_DOWN. The corresponding touch point was established through a new contact. This flag cannot be set in the same sample as TOUCHEVENTF_MOVE or TOUCHEVENTF_UP.
- TOUCHEVENTF_UP. A touch contact for the touch point has ended.
- TOUCHEVENTF_PRIMARY. The primary touch point, which is the first touch point after a previous state of no touch points. The flag is set for all events for the touch point. The touch proxy driver determines the setting of this flag.
- dwID is a touch contact index that uniquely identifies this touch point. This identifier must remain the same for a touch point from the time the touch begins until it ends. The driver must properly maintain this identifier, because gesture and application software depend on it. For single-touch this can always be 0. For multi-touch, do not use the same ID for two different touch points that are active at the same time (after a touch ends its identifier can be re-used).
- dwTime is the event timestamp in milliseconds. The driver must properly maintain this timestamp because gesture and application software depend on it to determine the length of time of a hold, and the speed of a movement.
The Tchddi.h header file defines the callback function prototype PFN_TOUCH_PANEL_CALLBACK_EX and for the CETOUCHINPUT structure.