1 /**
2  * @file lv_indev.h
3  *
4  */
5 
6 #ifndef LV_INDEV_H
7 #define LV_INDEV_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*********************
14  *      INCLUDES
15  *********************/
16 #include "../core/lv_group.h"
17 #include "../misc/lv_area.h"
18 #include "../misc/lv_timer.h"
19 #include "../misc/lv_event.h"
20 
21 /*********************
22  *      DEFINES
23  *********************/
24 
25 /**********************
26  *      TYPEDEFS
27  **********************/
28 
29 /** Possible input device types*/
30 typedef enum {
31     LV_INDEV_TYPE_NONE,    /**< Uninitialized state*/
32     LV_INDEV_TYPE_POINTER, /**< Touch pad, mouse, external button*/
33     LV_INDEV_TYPE_KEYPAD,  /**< Keypad or keyboard*/
34     LV_INDEV_TYPE_BUTTON,  /**< External (hardware button) which is assigned to a specific point of the screen*/
35     LV_INDEV_TYPE_ENCODER, /**< Encoder with only Left, Right turn and a Button*/
36 } lv_indev_type_t;
37 
38 /** States for input devices*/
39 typedef enum {
40     LV_INDEV_STATE_RELEASED = 0,
41     LV_INDEV_STATE_PRESSED
42 } lv_indev_state_t;
43 
44 typedef enum {
45     LV_INDEV_MODE_NONE = 0,
46     LV_INDEV_MODE_TIMER,
47     LV_INDEV_MODE_EVENT,
48 } lv_indev_mode_t;
49 
50 
51 /* Supported types of gestures */
52 typedef enum {
53     LV_INDEV_GESTURE_NONE = 0,
54     LV_INDEV_GESTURE_PINCH,
55     LV_INDEV_GESTURE_SWIPE,
56     LV_INDEV_GESTURE_ROTATE,
57     LV_INDEV_GESTURE_SCROLL,            /* Used with scrollwheels */
58     LV_INDEV_GESTURE_CNT,               /* Total number of gestures types */
59 } lv_indev_gesture_type_t;
60 
61 /** Data structure passed to an input driver to fill*/
62 typedef struct {
63     lv_point_t point; /**< For LV_INDEV_TYPE_POINTER the currently pressed point*/
64     uint32_t key;     /**< For LV_INDEV_TYPE_KEYPAD the currently pressed key*/
65     uint32_t btn_id;  /**< For LV_INDEV_TYPE_BUTTON the currently pressed button*/
66     int16_t enc_diff; /**< For LV_INDEV_TYPE_ENCODER number of steps since the previous read*/
67 
68     lv_indev_state_t state; /**< LV_INDEV_STATE_RELEASED or LV_INDEV_STATE_PRESSED*/
69     bool continue_reading;  /**< If set to true, the read callback is invoked again, unless the device is in event-driven mode*/
70 
71     lv_indev_gesture_type_t gesture_type;
72     void * gesture_data;
73 
74 } lv_indev_data_t;
75 
76 typedef void (*lv_indev_read_cb_t)(lv_indev_t * indev, lv_indev_data_t * data);
77 
78 /**********************
79  * GLOBAL PROTOTYPES
80  **********************/
81 
82 /**
83  * Create an indev
84  * @return Pointer to the created indev or NULL when allocation failed
85  */
86 lv_indev_t * lv_indev_create(void);
87 
88 /**
89  * Remove the provided input device. Make sure not to use the provided input device afterwards anymore.
90  * @param indev pointer to delete
91  */
92 void lv_indev_delete(lv_indev_t * indev);
93 
94 /**
95  * Get the next input device.
96  * @param indev pointer to the current input device. NULL to initialize.
97  * @return the next input device or NULL if there are no more. Provide the first input device when
98  * the parameter is NULL
99  */
100 lv_indev_t * lv_indev_get_next(lv_indev_t * indev);
101 
102 /**
103  * Read data from an input device.
104  * @param indev pointer to an input device
105  */
106 void lv_indev_read(lv_indev_t * indev);
107 
108 /**
109  * Called periodically to read the input devices
110  * @param timer pointer to a timer to read
111  */
112 void lv_indev_read_timer_cb(lv_timer_t * timer);
113 
114 /**
115  * Enable or disable one or all input devices (default enabled)
116  * @param indev pointer to an input device or NULL to enable/disable all of them
117  * @param enable true to enable, false to disable
118  */
119 void lv_indev_enable(lv_indev_t * indev, bool enable);
120 
121 /**
122  * Get the currently processed input device. Can be used in action functions too.
123  * @return pointer to the currently processed input device or NULL if no input device processing
124  * right now
125  */
126 lv_indev_t * lv_indev_active(void);
127 
128 /**
129  * Set the type of an input device
130  * @param indev pointer to an input device
131  * @param indev_type the type of the input device from `lv_indev_type_t` (`LV_INDEV_TYPE_...`)
132  */
133 void lv_indev_set_type(lv_indev_t * indev, lv_indev_type_t indev_type);
134 
135 /**
136  * Set a callback function to read input device data to the indev
137  * @param indev pointer to an input device
138  * @param read_cb pointer to callback function to read input device data
139  */
140 void lv_indev_set_read_cb(lv_indev_t * indev,  lv_indev_read_cb_t read_cb);
141 
142 /**
143  * Set user data to the indev
144  * @param indev pointer to an input device
145  * @param user_data pointer to user data
146  */
147 void lv_indev_set_user_data(lv_indev_t * indev, void * user_data);
148 
149 /**
150  * Set driver data to the indev
151  * @param indev pointer to an input device
152  * @param driver_data pointer to driver data
153  */
154 void lv_indev_set_driver_data(lv_indev_t * indev, void * driver_data);
155 
156 /**
157  * Assign a display to the indev
158  * @param indev pointer to an input device
159  * @param disp pointer to an display
160  */
161 void lv_indev_set_display(lv_indev_t * indev, struct _lv_display_t * disp);
162 
163 /**
164  * Set long press time to indev
165  * @param  indev            pointer to input device
166  * @param  long_press_time  time long press time in ms
167  */
168 void lv_indev_set_long_press_time(lv_indev_t * indev, uint16_t long_press_time);
169 
170 /**
171  * Set long press repeat time to indev
172  * @param  indev            pointer to input device
173  * @param  long_press_repeat_time  long press repeat time in ms
174  */
175 void lv_indev_set_long_press_repeat_time(lv_indev_t * indev, uint16_t long_press_repeat_time);
176 
177 /**
178  * Set scroll limit to the input device
179  * @param indev pointer to an input device
180  * @param scroll_limit the number of pixels to slide before actually drag the object
181  */
182 void lv_indev_set_scroll_limit(lv_indev_t * indev, uint8_t scroll_limit);
183 
184 /**
185  * Set scroll throw slow-down to the indev. Greater value means faster slow-down
186  * @param indev pointer to an input device
187  * @param scroll_throw the slow-down in [%]
188  */
189 void lv_indev_set_scroll_throw(lv_indev_t * indev, uint8_t scroll_throw);
190 
191 /**
192  * Get the type of an input device
193  * @param indev pointer to an input device
194  * @return the type of the input device from `lv_hal_indev_type_t` (`LV_INDEV_TYPE_...`)
195  */
196 lv_indev_type_t lv_indev_get_type(const lv_indev_t * indev);
197 
198 /**
199  * Get the callback function to read input device data to the indev
200  * @param indev pointer to an input device
201  * @return Pointer to callback function to read input device data or NULL if indev is NULL
202  */
203 lv_indev_read_cb_t lv_indev_get_read_cb(lv_indev_t * indev);
204 
205 /**
206  * Get the indev state
207  * @param indev pointer to an input device
208  * @return Indev state or LV_INDEV_STATE_RELEASED if indev is NULL
209  */
210 lv_indev_state_t lv_indev_get_state(const lv_indev_t * indev);
211 
212 /**
213  * Get the indev assigned group
214  * @param indev pointer to an input device
215  * @return Pointer to indev assigned group or NULL if indev is NULL
216  */
217 lv_group_t * lv_indev_get_group(const lv_indev_t * indev);
218 
219 /**
220  * Get a pointer to the assigned display of the indev
221  * @param indev pointer to an input device
222  * @return pointer to the assigned display or NULL if indev is NULL
223  */
224 lv_display_t * lv_indev_get_display(const lv_indev_t * indev);
225 
226 /**
227  * Get a pointer to the user data of the indev
228  * @param indev pointer to an input device
229  * @return pointer to the user data or NULL if indev is NULL
230  */
231 void * lv_indev_get_user_data(const lv_indev_t * indev);
232 
233 /**
234  * Get a pointer to the driver data of the indev
235  * @param indev pointer to an input device
236  * @return pointer to the driver data or NULL if indev is NULL
237  */
238 void * lv_indev_get_driver_data(const lv_indev_t * indev);
239 
240 /**
241  * Get whether indev is moved while pressed
242  * @param indev pointer to an input device
243  * @return true: indev is moved while pressed; false: indev is not moved while pressed
244  */
245 bool lv_indev_get_press_moved(const lv_indev_t * indev);
246 
247 /**
248  * Reset one or all input devices
249  * @param indev pointer to an input device to reset or NULL to reset all of them
250  * @param obj pointer to an object which triggers the reset.
251  */
252 void lv_indev_reset(lv_indev_t * indev, lv_obj_t * obj);
253 
254 /**
255  * Touch and key related events are sent to the input device first and to the widget after that.
256  * If this functions called in an indev event, the event won't be sent to the widget.
257  * @param indev pointer to an input device
258  */
259 void lv_indev_stop_processing(lv_indev_t * indev);
260 
261 /**
262  * Reset the long press state of an input device
263  * @param indev pointer to an input device
264  */
265 void lv_indev_reset_long_press(lv_indev_t * indev);
266 
267 /**
268  * Set a cursor for a pointer input device (for LV_INPUT_TYPE_POINTER and LV_INPUT_TYPE_BUTTON)
269  * @param indev pointer to an input device
270  * @param cur_obj pointer to an object to be used as cursor
271  */
272 void lv_indev_set_cursor(lv_indev_t * indev, lv_obj_t * cur_obj);
273 
274 /**
275  * Set a destination group for a keypad input device (for LV_INDEV_TYPE_KEYPAD)
276  * @param indev pointer to an input device
277  * @param group pointer to a group
278  */
279 void lv_indev_set_group(lv_indev_t * indev, lv_group_t * group);
280 
281 /**
282  * Set the an array of points for LV_INDEV_TYPE_BUTTON.
283  * These points will be assigned to the buttons to press a specific point on the screen
284  * @param indev pointer to an input device
285  * @param points array of points
286  */
287 void lv_indev_set_button_points(lv_indev_t * indev, const lv_point_t points[]);
288 
289 /**
290  * Get the last point of an input device (for LV_INDEV_TYPE_POINTER and LV_INDEV_TYPE_BUTTON)
291  * @param indev pointer to an input device
292  * @param point pointer to a point to store the result
293  */
294 void lv_indev_get_point(const lv_indev_t * indev, lv_point_t * point);
295 
296 /**
297 * Get the current gesture direct
298 * @param indev pointer to an input device
299 * @return current gesture direct
300 */
301 lv_dir_t lv_indev_get_gesture_dir(const lv_indev_t * indev);
302 
303 /**
304  * Get the last pressed key of an input device (for LV_INDEV_TYPE_KEYPAD)
305  * @param indev pointer to an input device
306  * @return the last pressed key (0 on error)
307  */
308 uint32_t lv_indev_get_key(const lv_indev_t * indev);
309 
310 
311 /**
312  * Get the counter for consecutive clicks within a short distance and time.
313  * The counter is updated before LV_EVENT_SHORT_CLICKED is fired.
314  * @param indev pointer to an input device
315  * @return short click streak counter
316  */
317 uint8_t lv_indev_get_short_click_streak(const lv_indev_t * indev);
318 
319 /**
320  * Check the current scroll direction of an input device (for LV_INDEV_TYPE_POINTER and
321  * LV_INDEV_TYPE_BUTTON)
322  * @param indev pointer to an input device
323  * @return LV_DIR_NONE: no scrolling now
324  *         LV_DIR_HOR/VER
325  */
326 lv_dir_t lv_indev_get_scroll_dir(const lv_indev_t * indev);
327 
328 /**
329  * Get the currently scrolled object (for LV_INDEV_TYPE_POINTER and
330  * LV_INDEV_TYPE_BUTTON)
331  * @param indev pointer to an input device
332  * @return pointer to the currently scrolled object or NULL if no scrolling by this indev
333  */
334 lv_obj_t * lv_indev_get_scroll_obj(const lv_indev_t * indev);
335 
336 /**
337  * Get the movement vector of an input device (for LV_INDEV_TYPE_POINTER and
338  * LV_INDEV_TYPE_BUTTON)
339  * @param indev pointer to an input device
340  * @param point pointer to a point to store the types.pointer.vector
341  */
342 void lv_indev_get_vect(const lv_indev_t * indev, lv_point_t * point);
343 
344 /**
345  * Get the cursor object of an input device (for LV_INDEV_TYPE_POINTER only)
346  * @param indev pointer to an input device
347  * @return pointer to the cursor object
348  */
349 lv_obj_t * lv_indev_get_cursor(lv_indev_t * indev);
350 
351 /**
352  * Do nothing until the next release
353  * @param indev pointer to an input device
354  */
355 void lv_indev_wait_release(lv_indev_t * indev);
356 
357 /**
358  * Gets a pointer to the currently active object in the currently processed input device.
359  * @return pointer to currently active object or NULL if no active object
360  */
361 lv_obj_t * lv_indev_get_active_obj(void);
362 
363 /**
364  * Get a pointer to the indev read timer to
365  * modify its parameters with `lv_timer_...` functions.
366  * @param indev pointer to an input device
367  * @return pointer to the indev read refresher timer. (NULL on error)
368  */
369 lv_timer_t * lv_indev_get_read_timer(lv_indev_t * indev);
370 
371 /**
372 * Set the input device's event model: event-driven mode or timer mode.
373 * @param indev pointer to an input device
374 * @param mode the mode of input device
375 */
376 void lv_indev_set_mode(lv_indev_t * indev, lv_indev_mode_t mode);
377 
378 /**
379  * Get the input device's running mode.
380  * @param indev pointer to an input device
381  * @return the running mode for the specified input device.
382  */
383 lv_indev_mode_t lv_indev_get_mode(lv_indev_t * indev);
384 
385 /**
386  * Search the most top, clickable object by a point
387  * @param obj pointer to a start object, typically the screen
388  * @param point pointer to a point for searching the most top child
389  * @return pointer to the found object or NULL if there was no suitable object
390  */
391 lv_obj_t * lv_indev_search_obj(lv_obj_t * obj, lv_point_t * point);
392 
393 /**
394  * Add an event handler to the indev
395  * @param indev          pointer to an indev
396  * @param event_cb      an event callback
397  * @param filter        event code to react or `LV_EVENT_ALL`
398  * @param user_data     optional user_data
399  */
400 void lv_indev_add_event_cb(lv_indev_t * indev, lv_event_cb_t event_cb, lv_event_code_t filter, void * user_data);
401 
402 /**
403  * Get the number of event attached to an indev
404  * @param indev          pointer to an indev
405  * @return              number of events
406  */
407 uint32_t lv_indev_get_event_count(lv_indev_t * indev);
408 
409 /**
410  * Get an event descriptor for an event
411  * @param indev          pointer to an indev
412  * @param index         the index of the event
413  * @return              the event descriptor
414  */
415 lv_event_dsc_t * lv_indev_get_event_dsc(lv_indev_t * indev, uint32_t index);
416 
417 /**
418  * Remove an event
419  * @param indev         pointer to an indev
420  * @param index         the index of the event to remove
421  * @return              true: and event was removed; false: no event was removed
422  */
423 bool lv_indev_remove_event(lv_indev_t * indev, uint32_t index);
424 
425 /**
426  * Remove an event_cb with user_data
427  * @param indev         pointer to a indev
428  * @param event_cb      the event_cb of the event to remove
429  * @param user_data     user_data
430  * @return              the count of the event removed
431  */
432 uint32_t lv_indev_remove_event_cb_with_user_data(lv_indev_t * indev, lv_event_cb_t event_cb, void * user_data);
433 
434 /**
435  * Send an event to an indev
436  * @param indev         pointer to an indev
437  * @param code          an event code. LV_EVENT_...
438  * @param param         optional param
439  * @return              LV_RESULT_OK: indev wasn't deleted in the event.
440  */
441 lv_result_t lv_indev_send_event(lv_indev_t * indev, lv_event_code_t code, void * param);
442 
443 /**********************
444  *      MACROS
445  **********************/
446 
447 #ifdef __cplusplus
448 } /*extern "C"*/
449 #endif
450 
451 #endif /*LV_INDEV_H*/
452