1 /*******************************************************************
2  *
3  * @file lv_indev_gesture.h
4  *
5  * Copyright (c) 2024 EDGEMTech Ltd.
6  *
7  * Author EDGEMTech Ltd, (erik.tagirov@edgemtech.ch)
8  *
9  ******************************************************************/
10 
11 #ifndef LV_INDEV_GESTURE_H
12 #define LV_INDEV_GESTURE_H
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 /*********************
19  *      INCLUDES
20  *********************/
21 #include "../core/lv_obj.h"
22 
23 #if LV_USE_GESTURE_RECOGNITION
24 
25 #if LV_USE_FLOAT == 0
26 #error "LV_USE_FLOAT is required for gesture detection."
27 #endif
28 
29 /*********************
30  *      DEFINES
31  *********************/
32 
33 /**********************
34  *      TYPEDEFS
35  **********************/
36 
37 /* Opaque types defined in the private header */
38 struct lv_indev_gesture;
39 struct lv_indev_gesture_configuration;
40 
41 typedef struct lv_indev_gesture lv_indev_gesture_t;
42 typedef struct lv_indev_gesture_configuration lv_indev_gesture_configuration_t;
43 
44 /* The states of a gesture recognizer */
45 typedef enum {
46     LV_INDEV_GESTURE_STATE_NONE = 0,    /* Beginning & end */
47     LV_INDEV_GESTURE_STATE_ONGOING,     /* Set when there is a probability */
48     LV_INDEV_GESTURE_STATE_RECOGNIZED,  /* Recognized, the event will contain touch info */
49     LV_INDEV_GESTURE_STATE_ENDED,       /* A recognized gesture has ended */
50     LV_INDEV_GESTURE_STATE_CANCELED,    /* Canceled - usually a finger is lifted */
51 } lv_indev_gesture_state_t;
52 
53 /* Data structures for touch events - used to repsensent a libinput event */
54 /* Emitted by devices capable of tracking identifiable contacts (type B) */
55 typedef struct {
56     lv_point_t point;                   /* Coordinates of the touch */
57     lv_indev_state_t state;             /* The state i.e PRESSED or RELEASED */
58     uint8_t id;                         /* Identification/slot of the contact point */
59     uint32_t timestamp;                 /* Timestamp in milliseconds */
60 } lv_indev_touch_data_t;
61 
62 /* Gesture recognizer */
63 typedef struct {
64     lv_indev_gesture_type_t type;       /* The detected gesture type */
65     lv_indev_gesture_state_t state;     /* The gesture state ongoing, recognized */
66     lv_indev_gesture_t * info;          /* Information on the motion of each touch point */
67     float scale;                        /* Relevant for the pinch gesture */
68     float rotation;                     /* Relevant for rotation */
69     float distance;                     /* Relevant for swipes */
70     float speed;
71 
72     lv_indev_gesture_configuration_t * config;
73 
74 } lv_indev_gesture_recognizer_t;
75 
76 /**********************
77  * GLOBAL PROTOTYPES
78  **********************/
79 
80 
81 /* PINCH Gesture */
82 
83 /**
84  * Detects a pinch gesture
85  * @param recognizer        pointer to a gesture recognizer
86  * @param touches           pointer to the first element of the collected touch events
87  * @param touch_cnt         length of passed touch event array.
88  */
89 void lv_indev_gesture_detect_pinch(lv_indev_gesture_recognizer_t * recognizer, lv_indev_touch_data_t * touches,
90                                    uint16_t touch_cnt);
91 
92 
93 /**
94  * Set the threshold for the pinch gesture scale up, when the scale factor of gesture
95  * reaches the threshold events get sent
96  * @param recognizer        pointer to a gesture recognizer
97  * @param touches           pointer to the first element of the collected touch events
98  * @param touch_cnt         length of passed touch event array.
99  */
100 void lv_indev_set_pinch_up_threshold(lv_indev_gesture_recognizer_t * recognizer, float threshold);
101 
102 /**
103  * Set the threshold for the pinch gesture scale down, when the scale factor of gesture
104  * reaches the threshold events get sent
105  * @param recognizer        pointer to a gesture recognizer
106  * @param touches           pointer to the first element of the collected touch events
107  * @param touch_cnt         length of passed touch event array.
108  */
109 void lv_indev_set_pinch_down_threshold(lv_indev_gesture_recognizer_t * recognizer, float threshold);
110 
111 /**
112  * Obtains the current scale of a pinch gesture
113  * @param gesture_event     pointer to a gesture recognizer event
114  * @return                  the scale of the current gesture
115  */
116 float lv_event_get_pinch_scale(lv_event_t * gesture_event);
117 
118 /**
119  * Sets the state of the recognizer to a indev data structure,
120  * it is usually called from the indev read callback
121  * @param data the indev data
122  * @param recognizer pointer to a gesture recognizer
123  */
124 void lv_indev_set_gesture_data(lv_indev_data_t * data, lv_indev_gesture_recognizer_t * recognizer);
125 
126 /**
127  * Obtains the center point of a gesture
128  * @param gesture_event     pointer to a gesture recognizer event
129  * @param point             pointer to a point
130  */
131 void lv_indev_get_gesture_center_point(lv_indev_gesture_recognizer_t * recognizer, lv_point_t * point);
132 
133 /**
134  * Obtains the current state of the gesture recognizer attached to an event
135  * @param gesture_event     pointer to a gesture recognizer event
136  * @return                  current state of the gesture recognizer
137  */
138 lv_indev_gesture_state_t lv_event_get_gesture_state(lv_event_t * gesture_event);
139 
140 /**
141  * Obtains the coordinates of the current primary point
142  * @param recognizer        pointer to a gesture recognizer
143  * @param point             pointer to a point
144  */
145 void lv_indev_get_gesture_primary_point(lv_indev_gesture_recognizer_t * recognizer, lv_point_t * point);
146 
147 /**
148  * Allows to determine if there is an are ongoing gesture
149  * @param recognizer        pointer to a gesture recognizer
150  * @return                  false if there are no contact points, or the gesture has ended - true otherwise
151  */
152 bool lv_indev_recognizer_is_active(lv_indev_gesture_recognizer_t * recognizer);
153 
154 
155 /**********************
156  *      MACROS
157  **********************/
158 
159 #endif /* END LV_USE_RECOGNITION */
160 
161 #ifdef __cplusplus
162 } /*extern "C"*/
163 #endif
164 
165 #endif /* END LV_INDEV_GESTURE_H */
166