Touch device gesture recognition

Gesture recognition for touch devices. More...

Detailed Description

Gesture recognition for touch devices.

This driver implements a simple gesture recognition with a maximum of two touches for touch devices that use the generic touch device API.

The application that receives the events from the touch device via the callback function registered with touch_dev_set_touch_event_callback must first create and initialize a touch device gesture context of type touch_dev_gesture_ctx_t. For each touch event received from the touch device, it then calls touch_dev_recognize_gesture function with this context so that the gesture recognition fetches the data from the touch device to detect the gestures, for example:

static void _touch_event_cb(void *arg)
{
    // indicate that a touch event occurred
    mutex_unlock(arg);
}
 
void *_input_task(void *arg)
{
    ...
    mutex_t lock = MUTEX_INIT_LOCKED;
 
    touch_dev_t *dev = touch_dev_reg_find_screen(0).dev;
    touch_dev_gesture_ctx_t ctx;
 
    // set the event callback function and initialize the touch device gesture context
    touch_dev_set_touch_event_callback(dev, _touch_event_cb, &lock);
    touch_dev_init_gesture(dev, &ctx);
 
    while (1) {
        // wait for the indication of a touch event
        mutex_lock(&lock);
 
        // call the gesture recognition
        touch_t pos;
        touch_dev_gesture_t gesture = touch_dev_recognize_gesture(&ctx, &pos);
 
        // process recognized gestures
        switch (gesture) {
            case TOUCH_DEV_GEST_SINGLE_TAP:
                if ((pos.x == 50) && (pos.y == 75)) {
                ...
            case TOUCH_DEV_GEST_DOUBLE_TAP:
                ...
            ...
        }
    }
    return NULL;
}

Note

To use this event-driven approach the driver for the touch device has to report the following touch events by interrupt:

• a new touch is detected,
• a touch is released, and
• regularly the current touch positions as long as there are touches.

If the event-driven approach cannot be used because either the touch device does not support all these touch events or the application wants to use the touch device in polling mode, the application must call the touch_dev_recognize_gesture function with the gesture context of the touch device at regular intervals, for example:

#ifndef TOUCH_DEV_POLLING_PERIOD
#define TOUCH_DEV_POLLING_PERIOD     50
#endif
...
 
void *_input_task(void *arg)
{
    ...
 
    touch_dev_t *dev = touch_dev_reg_find_screen(0).dev;
    touch_dev_gesture_ctx_t ctx;
 
    // initialize the touch device gesture context
    touch_dev_init_gesture(dev, &ctx);
 
    while (1) {
        // call the gesture recognition
        touch_t pos;
        touch_dev_gesture_t gesture = touch_dev_recognize_gesture(&ctx, &pos);
 
        // process recognized gestures
        switch (gesture) {
            case TOUCH_DEV_GEST_SINGLE_TAP:
                if ((pos.x == 50) && (pos.y == 75)) {
                ...
            case TOUCH_DEV_GEST_DOUBLE_TAP:
                ...
            ...
        }
 
        // wait the period time for polling
        ztimer_sleep(ZTIMER_MSEC, TOUCH_DEV_POLLING_PERIOD);
    }
    return NULL;
}

The following gestures are supported by the driver:

• TOUCH_DEV_GEST_SINGLE_TAP : a single tap with one touch at the given position
• TOUCH_DEV_GEST_DOUBLE_TAP : a double tap with one touch at the given position
• TOUCH_DEV_GEST_PRESSED : a long press with one touch at the given position
• TOUCH_DEV_GEST_RELEASED : one touch released after a long press at given position
• TOUCH_DEV_GEST_MOVE : moving while pressed with current position
• TOUCH_DEV_GEST_SWIPE_LEFT : swiping left with one touch
• TOUCH_DEV_GEST_SWIPE_RIGHT : swiping right with one touch
• TOUCH_DEV_GEST_SWIPE_UP : swiping up with one touch
• TOUCH_DEV_GEST_SWIPE_DOWN : swiping down with one touch
• TOUCH_DEV_GEST_ZOOM_IN : zooming in (spreading) with two touches
• TOUCH_DEV_GEST_ZOOM_OUT : zooming out (pinching) with two touches

Note

• For technical reasons, a double-tap event is always preceded by a single-tap event, i.e. for a double-tap, the application always receives a single-tap event first and then a double-tap event if the second tap follows.
• Zooming gestures are only available if the touch device supports two touches.

Author

Gunar Schorcht gunar.nosp@m.@sch.nosp@m.orcht.nosp@m..net

Data Structures
struct	touch_dev_gesture_ctx_t
	Context information for a touch device needed for gesture recognition. More...

Macros
#define	TOUCH_DEV_TOUCHES_MAX_NUMOF   2
	Maximum number of touches supported by gesture recognition.
#define	CONFIG_TOUCH_DEV_SWIPE_TRESH   5
	Minimum distance in one direction to recognize a swipe gesture.
#define	CONFIG_TOUCH_DEV_PRESS_TIME_MS   600
	Minimum touch time in milliseconds to detect a long press gesture.
#define	CONFIG_TOUCH_DEV_DOUBLE_TIME_MS   400
	Maximum time in milliseconds between two taps to detect a double tap.

Enumerations
enum	touch_dev_state_t {   TOUCH_DEV_STATE_RELEASED , TOUCH_DEV_STATE_TAPPED_SINGLE , TOUCH_DEV_STATE_TAPPED_MULTIPLE , TOUCH_DEV_STATE_PRESSED ,   TOUCH_DEV_STATE_WAIT_FOR_RELEASE }
	Touch device states used for gesture recognition. More...
enum	touch_dev_gesture_t {   TOUCH_DEV_GEST_NONE , TOUCH_DEV_GEST_SINGLE_TAP , TOUCH_DEV_GEST_DOUBLE_TAP , TOUCH_DEV_GEST_PRESSED ,   TOUCH_DEV_GEST_RELEASED , TOUCH_DEV_GEST_MOVE , TOUCH_DEV_GEST_SWIPE_LEFT , TOUCH_DEV_GEST_SWIPE_RIGHT ,   TOUCH_DEV_GEST_SWIPE_UP , TOUCH_DEV_GEST_SWIPE_DOWN , TOUCH_DEV_GEST_ZOOM_IN , TOUCH_DEV_GEST_ZOOM_OUT }
	Touch gesture events. More...

Functions
void	touch_dev_init_gesture (touch_dev_t *dev, touch_dev_gesture_ctx_t *ctx)
	Initialize gesture recognition.
touch_dev_gesture_t	touch_dev_recognize_gesture (touch_dev_gesture_ctx_t *ctx, touch_t *pos)
	Recognize gestures by handling next touch device event.

Macro Definition Documentation

CONFIG_TOUCH_DEV_DOUBLE_TIME_MS

#define CONFIG_TOUCH_DEV_DOUBLE_TIME_MS   400

Maximum time in milliseconds between two taps to detect a double tap.

Definition at line 179 of file touch_dev_gestures.h.

CONFIG_TOUCH_DEV_PRESS_TIME_MS

#define CONFIG_TOUCH_DEV_PRESS_TIME_MS   600

Minimum touch time in milliseconds to detect a long press gesture.

Definition at line 172 of file touch_dev_gestures.h.

CONFIG_TOUCH_DEV_SWIPE_TRESH

#define CONFIG_TOUCH_DEV_SWIPE_TRESH   5

Minimum distance in one direction to recognize a swipe gesture.

Definition at line 165 of file touch_dev_gestures.h.

TOUCH_DEV_TOUCHES_MAX_NUMOF

#define TOUCH_DEV_TOUCHES_MAX_NUMOF   2

Maximum number of touches supported by gesture recognition.

Definition at line 159 of file touch_dev_gestures.h.

Enumeration Type Documentation

touch_dev_gesture_t

enum touch_dev_gesture_t

Touch gesture events.

Enumerator
TOUCH_DEV_GEST_NONE	No gesture recognized.
TOUCH_DEV_GEST_SINGLE_TAP	Single tap recognized at the given position.
TOUCH_DEV_GEST_DOUBLE_TAP	Double tap recognized at the given position.
TOUCH_DEV_GEST_PRESSED	Long press recognized at the given position.
TOUCH_DEV_GEST_RELEASED	Release after a long press at given position.
TOUCH_DEV_GEST_MOVE	Moving while pressed recognized, current position is given.
TOUCH_DEV_GEST_SWIPE_LEFT	Swipe left recognized, no position is given.
TOUCH_DEV_GEST_SWIPE_RIGHT	Swipe right recognized, no position is given.
TOUCH_DEV_GEST_SWIPE_UP	Swipe up recognized, no position is given.
TOUCH_DEV_GEST_SWIPE_DOWN	Swipe down recognized, no position is given.
TOUCH_DEV_GEST_ZOOM_IN	Zoom in (spread) recognized, no position is given.
TOUCH_DEV_GEST_ZOOM_OUT	Zoom out (pinch) recognized, no position is given.

Definition at line 196 of file touch_dev_gestures.h.

touch_dev_state_t

enum touch_dev_state_t

Touch device states used for gesture recognition.

Enumerator
TOUCH_DEV_STATE_RELEASED	no touches detected, default state
TOUCH_DEV_STATE_TAPPED_SINGLE	a single touch is detected
TOUCH_DEV_STATE_TAPPED_MULTIPLE	a second touch is detected
TOUCH_DEV_STATE_PRESSED	a long press is detected
TOUCH_DEV_STATE_WAIT_FOR_RELEASE	gesture detected, waiting for releasing touches

Definition at line 185 of file touch_dev_gestures.h.

Function Documentation

touch_dev_init_gesture()

void touch_dev_init_gesture	(	touch_dev_t *	dev,
		touch_dev_gesture_ctx_t *	ctx
	)

Initialize gesture recognition.

Parameters

[in]	dev	Pointer to the touch device
[in]	ctx	Pointer to the context information for the touch device

touch_dev_recognize_gesture()

touch_dev_gesture_t touch_dev_recognize_gesture	(	touch_dev_gesture_ctx_t *	ctx,
		touch_t *	pos
	)

Recognize gestures by handling next touch device event.

Parameters

[in]	ctx	Pointer to the context information for the touch device
[out]	pos	Position of the gesture if interested in it (can be NULL)

return the gesture of type touch_dev_gesture_t if one was recognized or TOUCH_DEV_GEST_NONE