TOUCHINPUT structure (winuser.h)

Encapsulates data for touch input.

Syntax

typedef struct tagTOUCHINPUT {
  LONG      x;
  LONG      y;
  HANDLE    hSource;
  DWORD     dwID;
  DWORD     dwFlags;
  DWORD     dwMask;
  DWORD     dwTime;
  ULONG_PTR dwExtraInfo;
  DWORD     cxContact;
  DWORD     cyContact;
} TOUCHINPUT, *PTOUCHINPUT;

Members

x

The x-coordinate (horizontal point) of the touch input. This member is indicated in hundredths of a pixel of physical screen coordinates.

y

The y-coordinate (vertical point) of the touch input. This member is indicated in hundredths of a pixel of physical screen coordinates.

hSource

A device handle for the source input device. Each device is given a unique provider at run time by the touch input provider. See Examples section below.

dwID

A touch point identifier that distinguishes a particular touch input. This value stays consistent in a touch contact sequence from the point a contact comes down until it comes back up. An ID may be reused later for subsequent contacts.

dwFlags

A set of bit flags that specify various aspects of touch point press, release, and motion. The bits in this member can be any reasonable combination of the values in the Remarks section.

dwMask

A set of bit flags that specify which of the optional fields in the structure contain valid values. The availability of valid information in the optional fields is device-specific. Applications should use an optional field value only when the corresponding bit is set in dwMask. This field may contain a combination of the dwMask flags mentioned in the Remarks section.

dwTime

The time stamp for the event, in milliseconds. The consuming application should note that the system performs no validation on this field; when the TOUCHINPUTMASKF_TIMEFROMSYSTEM flag is not set, the accuracy and sequencing of values in this field are completely dependent on the touch input provider.

dwExtraInfo

An additional value associated with the touch event.

cxContact

The width of the touch contact area in hundredths of a pixel in physical screen coordinates. This value is only valid if the dwMask member has the TOUCHEVENTFMASK_CONTACTAREA flag set.

cyContact

The height of the touch contact area in hundredths of a pixel in physical screen coordinates. This value is only valid if the dwMask member has the TOUCHEVENTFMASK_CONTACTAREA flag set.

Remarks

The following table lists the flags for the dwFlags member.

A touch point is designated as primary when it is the first touch point to be established from a previous state of no touch points. The TOUCHEVENTF_PRIMARY flag continues to be set for all subsequent events for the primary touch point until the primary touch point is released. Note that a TOUCHEVENTF_UP event on the primary touch point does not necessarily designate the end of a Windows Touch operation; the current Windows Touch operation proceeds from the establishment of the primary touch point until the last touch point is released.

Note that a solitary touch point or, in a set of simultaneous touch points, the first to be detected, is designated the primary. The system mouse position follows the primary touch point and, in addition to touch messages, also generates WM_LBUTTONDOWN, WM_MOUSEMOVE, and WM_LBUTTONUP messages in response to actions on a primary touch point. The primary touch point can also generate WM_RBUTTONDOWN and WM_RBUTTONUP messages using the press and hold gesture.

Note that the touch point identifier may be dynamic and is associated with a given touch point only as long as the touch point persists. If contact is broken and then resumed (for example, if a finger is removed from the surface and then pressed down again), the same touch point (the same finger, pen, or other such device) may receive a different touch point identifier.

The following type is defined to represent a constant pointer to a TOUCHINPUT structure.

   typedef TOUCHINPUT const * PCTOUCHINPUT;
    

Examples

UINT cInputs = LOWORD(wParam);
PTOUCHINPUT pInputs = new TOUCHINPUT[cInputs];
if (NULL != pInputs)
{
    if (GetTouchInputInfo((HTOUCHINPUT)lParam,
                          cInputs,
                          pInputs,
                          sizeof(TOUCHINPUT)))
    {
        // process pInputs
        if (!CloseTouchInputHandle((HTOUCHINPUT)lParam))
        {
            // error handling
        }
    }
    else
    {
        // GetLastError() and error handling
    }
    delete [] pInputs;
}
else
{
    // error handling, presumably out of memory
}
return DefWindowProc(hWnd, message, wParam, lParam);

The following example shows how to get the device information from the hSource member. This example uses GetRawInputDevice to retrieve information about the device.

for (UINT i = 0; i < cInputs; i++){
  TOUCHINPUT ti = pInputs[i];      
  RID_DEVICE_INFO info;
  ZeroMemory(&info, sizeof(RID_DEVICE_INFO));
  info.cbSize = sizeof(RID_DEVICE_INFO);
  UINT size = 0;
  if (GetRawInputDeviceInfo(ti.hSource, RIDI_DEVICEINFO, &info, &size)){
  }else{
    DWORD err = GetLastError();
  }
}

Requirements

See also

GetTouchInputInfo

Structures