Gestures Module
The Gestures module in Microchip’s Touch Modular Library provides advanced gesture recognition capabilities for 2D touch surfaces. It enables detection of common gestures such as tap, swipe, wheel, pinch, and zoom, supporting both single- and dual-finger operation depending on the surface configuration.
Gestures Module Data Structures
qtm_gestures_2d_control_t
{
qtm_gestures_2d_data_t *qtm_gestures_data;
qtm_gestures_2d_config_t *qtm_gestures_config;
} qtm_gestures_2d_control_t;
Description: The qtm_gestures_2d_control_t data interface is a container structure that controls the input and output of this module.
More Info: Here is a description of each of the elements in this structure:
| Field | Unit | Range/Options | Parameter |
|---|---|---|---|
| qtm_gestures_2d_data | qtm_gestures_2d_data _t* | Pointer | Pointer to the gestures data structure |
| qtm_gestures_2d_config | qtm_gestures_2d_config _t* | Pointer | Pointer to the gestures config structure |
qtm_gestures_2d_config _t
{
uint16_t *horiz_position0;
uint16_t *vertical_position0;
uint8_t *surface_status0;
uint16_t *horiz_position1;
uint16_t *vertical_position1;
uint8_t *surface_status1;
uint8_t surface_resolution;
uint8_t tapReleaseTimeout;
uint8_t tapHoldTimeout;
uint8_t swipeTimeout;
uint8_t xSwipeDistanceThreshold;
uint8_t ySwipeDistanceThreshold;
uint8_t edgeSwipeDistanceThreshold;
uint8_t tapDistanceThreshold;
uint8_t seqTapDistanceThreshold;
uint8_t edgeBoundary;
int8_t wheelPostscaler;
int8_t wheelStartQuadrantCount;
int8_t wheelReverseQuadrantCount;
uint8_t pinchZoomThreshold;
} qtm_gestures_2d_config_t;
Description: The qtm_gestures_2d_config _t data structure is the configuration structure passed to the module.
More Info: Here is a description of each of the elements in this structure:
| Field | Unit | Range/Options | Parameter |
|---|---|---|---|
| horiz_position0 | uint16_t | Pointer | Pointer to the horizontal contact 0 position |
| vertical_position0 | uint16_t | Pointer | Pointer to the vertical contact 0 position |
| surface_status0 | uint8_t | Pointer | Pointer to the status of contact 0 |
| horiz_position1 | uint16_t | Pointer | Pointer to the horizontal contact 1 position |
| vertical_position1 | uint16_t | Pointer | Pointer to the vertical contact 1 position |
| surface_status1 | uint8_t | Pointer | Pointer to the status of contact 1 |
| surface_resolution | uint8_t | 0 to 255 | This parameter defines the resolution of surface |
| tapReleaseTimeout | uint8_t | 0 to 255 | This parameter limits the amount of time allowed between the initial finger press and the liftoff. Exceeding this value will cause the firmware to not consider the gesture as a tap gesture |
| tapHoldTimeout | uint8_t | 0 to 255 | If a finger stays within the bounds set by TAP_AREA and is not removed, the firmware will report a Tap Hold gesture once the gesture timer exceeds this value |
| swipeTimeout | uint8_t | 0 to 255 | This value limits the amount of time allowed for the swipe gesture (initial finger press, moving in a particular direction, crossing the distance threshold and the liftoff) |
| xSwipeDistanceThreshold | uint8_t | 0 to 255 | This controls the distance traveled in the X-axis direction for detecting Left and Right Swipe gestures |
| ySwipeDistanceThreshold | uint8_t | 0 to 255 | This controls the distance traveled in the Y-axis direction for detecting Up and Down Swipe gestures |
| edgeSwipeDistanceThreshold | uint8_t | 0 to 255 | This controls the distance traveled for Edge Swipe gestures |
| tapDistanceThreshold | uint8_t | 0 to 255 | This parameter bounds the finger to an area it must stay within to be considered a Tap gesture when the finger is removed and Tap and Hold gesture if the finger is not removed for some time |
| seqTapDistanceThreshold | uint8_t | 0 to 255 | This parameter limits the allowable distance of the current touch’s initial press from the liftoff position of the previous touch. It is used for multiple taps (double-tap, triple-tap, etc.). If the taps following the first are within this threshold, then the tap counter will be incremented If the following tap gestures exceed this threshold, the previous touch is sent as a single tap, and the current touch will reset the tap counter |
| edgeBoundary | uint8_t | 0 to 255 | The firmware can also be modified to define an edge region along the border of the touch sensor. With this defined, Swipe gestures that start in an edge region will be reported as Edge Swipe gestures in place of normal Swipe gestures |
| wheelPostscaler | int8_t | -128 to 127 | This parameter adjusts the rate at which the Wheel gesture is updated in the Graphical User Interface (GUI) |
| wheelStartQuadrantCount | int8_t | -128 to 127 | The Wheel gesture movement can be broken down into 90° arcs. The firmware watches for a certain number of arcs to occur in a circular pattern before starting to report Wheel gesture information. The number of arcs that must be first detected is determined by this parameter. Lower values for this parameter make it faster to start a wheel gesture, but it also makes the firmware prone to prematurely reporting wheel gesture information |
| wheelReverseQuadrantCount | int8_t | -128 to 127 | This parameter functions like wheelStartQuadrantCount, except it is used when changing the direction of the wheel instead of starting it new. This is used to prevent quick toggling between directions |
| pinchZoomThreshold | uint8_t | 0 to 255 | This parameter limits the allowable distance between the two fingers to detect the pinch and the zoom gestures. After crossing this parameter value, if the distance between the contacts is reducing, then the gesture is reported as PINCH. After crossing this parameter value, if the distance between the contacts is increasing, then the gesture is reported as ZOOM |
qtm_gestures_2d_data_t
{
uint8_t gestures_status;
uint8_t gestures_which_gesture;
uint8_t gestures_info;
} qtm_gestures_2d_data_t;
Description: The qtm_gestures_2d_data_t data structure is used internally within the module to identify the gesture and to store the status and information.
More Info: Here is a description of each of the elements in this structure:
| Field | Unit | Range/Options | Parameter |
|---|---|---|---|
| gestures_status | uint8_t | 0 or 1 | This indicates if a gesture has been decoded or not |
| gestures_which_gesture | uint8_t | 0 to 255 | This contains the current, decoded gesture |
| gestures_info | uint8_t | 0 to 255 | This contains the additional gesture information |
Gesture Module Application Programming Interfaces (APIs)
qtm_gestures_2d_clearGesture
Description: This clears the previously reported gesture. The application can clear the gesture after reading it. Otherwise, the gesture will be reported continuously.
Parameter: void
Return: void
qtm_init_gestures_2d
Description: Gesture engine processes updated touch info
Parameter: qtm_gestures_2d_control_t* - Pointer to Gesture Module Control Structure.
Return: touch_ret_t - Touch Library Return Status
qtm_update_gesture_2d_timer
Description: The internal time tracking variable will be updated and used for gesture detection timings. We recommend calling this function periodically (for example, 1 msec and pass 1 as the value).
Parameter: uint16_t - Timelapse since last call in milliseconds
Return: void
qtm_get_gesture_2d_module_id
Description: Returns the module ID
Parameter: void
Return: uint16_t - Module ID
qtm_get_gesture_2d_module_ver
Description: Returns the module Firmware version
Parameter: void
Return: uint8_t - Module Version