Gesture Parameters
DO_NOT_REMOVE
Microchip’s touch libraries provide robust gesture recognition capabilities for 2D touch surfaces. These features enable intuitive user interfaces with gestures like tap, swipe, wheel, and pinch/zoom, supporting both single- and dual-finger operation.
This section covers parameters that control gesture module behaviors. Two kinds of gesture detection are possible, namely:
- One finger
- One or two fingers
TAP_RELEASE_TIMEOUT
Description: The TAP_RELEASE_TIMEOUT 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.
Range: 3 to 255
Units: x10 ms
More Info: TAP_RELEASE_TIMEOUT should be less than TAP_HOLD_TIMEOUT and SWIPE_TIMEOUT.
Example: If TAP_RELEASE_TIMEOUT is configured as three, then the user should finish tapping within 30 ms to qualify the gesture as a tap.
TAP_HOLD_TIMEOUT
Description: 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 the TAP_HOLD_TIMEOUT value.
Range: 0 to 255
Units: x10 ms
More Info: HOLD_TAP is a single finger gesture, whereas HOLD_TAP_DUAL is a dual finger gesture. Ideally, TAP_HOLD_TIMEOUT should be greater than the TAP_RELEASE_TIMEOUT and SWIPE_TIMEOUT.
Example: If TAP_HOLD_TIMEOUT is configured as six, then the user should tap and hold inside the TAP_AREA for 60 ms to qualify the gesture as tap and hold.
SWIPE_TIMEOUT
Description: The SWIPE_TIMEOUT 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).
Range: 0 to 255
Units: x10 ms
More Info: Ideally, SWIPE_TIMEOUT should be greater than TAP_RELEASE_TIMEOUT, but smaller than the TAP_HOLD_TIMEOUT.
Example: If SWIPE_TIMEOUT is configured as five, then the user should swipe in a particular direction and liftoff within 50 ms to qualify the gesture as a swipe.
HORIZONTAL_SWIPE_DISTANCE_THRESHOLD
Description: This parameter defines the distance travelled in the X axis direction for detecting left and right swipe gestures.
Range: 0 to 255
Units: Position, X-coordinate
More Info: Example: If HORIZONTAL_SWIPE_DISTANCE_THRESHOLD is configured as 50, and a user places their finger at x-coordinate 100, they must move to at least x-coordinate 50 to record a left swipe gesture.
VERTICAL_SWIPE_DISTANCE_THRESHOLD
Description: This parameter defines the distance traveled in the Y-axis direction for detecting up and down swipe gestures.
Range: 0 to 255
Units: Position, Y-coordinate
More Info: Example: if VERTICAL_SWIPE_DISTANCE_THRESHOLD is configured as 30, and a user places their finger at y-coordinate 100, they must move to at least y-coordinate 70 to record a down swipe gesture.
TAP_AREA
Description: The TAP_AREA 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 sometime.
Range: 0 to 255
Units: Position
More Info: Example: If TAP_AREA is configured as 20, then the user should not move the tap more than 20 coordinates to detect the tap gesture.
SEQ_TAP_DIST_THRESHOLD
Description: This parameter limits the allowable distance of the current touch's initial press from the *liftoff position of the previous touch.
Range: 0 to 255
Units: Position
More Info: 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.
Example: If SEQ_TAP_DIST_THRESHOLD is configured as 20, after the first tap, if the user taps again within 20 coordinates, it is considered a double-tap gesture.
EDGE_BOUNDARY
Description: With Edge Boundary defined, swipe gestures that start in an edge region will be reported as edge swipe gestures in place of normal swipe gestures.
Range: 0 to 255
Unit: Position
More Info: To create an edge region, the EDGE_BOUNDARY is set with the size (in touch coordinates) of the edge region.
Example: Setting the EDGE_BOUNDARY parameter to 10 will designate the area 10 positions from each edge as the edge region.
PINCH_ZOOM_THRESHOLD
Description: PINCH_ZOOM_THRESHOLD limits the allowable distance between the two fingers to detect the pinch and the zoom gestures.
Range: 0 to 255
Unit: Position, coordinates
More Info: This parameter is valid only if two-finger gesture is selected. After crossing the PINCH_ZOOM_THRESHOLD, if the distance between the contacts is reducing, then the gesture is reported as "PINCH". After crossing the PINCH_ZOOM_THRESHOLD, if the distance between the contacts is increasing, then the gesture is reported as "ZOOM".
Example: If PINCH_ZOOM_THRESHOLD is configured as 20, then after crossing 20 coordinates, it will be reported as the pinch gesture or the zoom gesture.
WHEEL_POSTSCALER
Description: This parameter defines the number of swipe arcs to be added to the WHEEL_START_QUADRANT_COUNT to detect a wheel swipe gesture.
Range: 0 to 255
More Info: The clockwise wheel is performed with four swipes (right > down > left > up). Similarly, the anti-clockwise wheel is performed with four swipes (left > down > right > up). To detect a wheel, the minimum number of swipes required is WHEEL_START_QUADRANT_COUNT + WHEEL_POSTSCALER. Once the wheel is detected, for WHEEL_POSTSCALER number of swipe detections, the wheel counter will be incremented by one.
Example: If WHEEL_POSTSCALER is two, then for every two swipes detected, the wheel counter will be incremented by one.
WHEEL_START_QUADRANT_COUNT
Description: This parameter defines the minimum number of 90-degree arc swipes that must be detected before the gesture is reported as a wheel.
Range: 2 to 255
More Info: The wheel gesture movement can be broken down into 90-degree 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 first be detected is determined by the WHEEL_START_QUADRANT_COUNT 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.
Example: If WHEEL_START_QUADRANT_COUNT is configured as two, then after 180 degrees, the gesture is updated as wheel.
WHEEL_REVERSE_QUADRANT_COUNT
Description: This parameter defines the number of arc swipes to be counted after a direction change before counting it as a wheel gesture in that direction.
Range: 2 to 255
More Info: WHEEL_REVERSE_QUADRANT_COUNT performs a similar function as WHEEL_START_QUADRANT_COUNT, except it is used when changing the direction of the wheel instead of starting it anew. This is used to prevent quick toggling between directions.
Example: If WHEEL_REVERSE_QUADRANT_COUNT is set to four, and after some wheel gestures, if the user changes the direction of rotation, then only after 360 degrees, it will be detected as one wheel gesture.