1 /**
2  * @file lv_event.h
3  *
4  */
5 
6 #ifndef LV_EVENT_H
7 #define LV_EVENT_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*********************
14  *      INCLUDES
15  *********************/
16 #include "lv_types.h"
17 #include "../lv_conf_internal.h"
18 
19 #include "lv_array.h"
20 
21 /*********************
22  *      DEFINES
23  *********************/
24 
25 /**********************
26  *      TYPEDEFS
27  **********************/
28 
29 typedef void (*lv_event_cb_t)(lv_event_t * e);
30 
31 /**
32  * Type of event being sent to Widget
33  */
34 typedef enum {
35     LV_EVENT_ALL = 0,
36 
37     /** Input device events*/
38     LV_EVENT_PRESSED,             /**< Widget has been pressed */
39     LV_EVENT_PRESSING,            /**< Widget is being pressed (sent continuously while pressing)*/
40     LV_EVENT_PRESS_LOST,          /**< Widget is still being pressed but slid cursor/finger off Widget */
41     LV_EVENT_SHORT_CLICKED,       /**< Widget was pressed for a short period of time, then released. Not sent if scrolled. */
42     LV_EVENT_SINGLE_CLICKED,      /**< Sent for first short click within a small distance and short time */
43     LV_EVENT_DOUBLE_CLICKED,      /**< Sent for second short click within small distance and short time */
44     LV_EVENT_TRIPLE_CLICKED,      /**< Sent for third short click within small distance and short time */
45     LV_EVENT_LONG_PRESSED,        /**< Object has been pressed for at least `long_press_time`.  Not sent if scrolled. */
46     LV_EVENT_LONG_PRESSED_REPEAT, /**< Sent after `long_press_time` in every `long_press_repeat_time` ms.  Not sent if scrolled. */
47     LV_EVENT_CLICKED,             /**< Sent on release if not scrolled (regardless to long press)*/
48     LV_EVENT_RELEASED,            /**< Sent in every cases when Widget has been released */
49     LV_EVENT_SCROLL_BEGIN,        /**< Scrolling begins. The event parameter is a pointer to the animation of the scroll. Can be modified */
50     LV_EVENT_SCROLL_THROW_BEGIN,
51     LV_EVENT_SCROLL_END,          /**< Scrolling ends */
52     LV_EVENT_SCROLL,              /**< Scrolling */
53     LV_EVENT_GESTURE,             /**< A gesture is detected. Get gesture with `lv_indev_get_gesture_dir(lv_indev_active());` */
54     LV_EVENT_KEY,                 /**< A key is sent to Widget. Get key with `lv_indev_get_key(lv_indev_active());`*/
55     LV_EVENT_ROTARY,              /**< An encoder or wheel was rotated. Get rotation count with `lv_event_get_rotary_diff(e);`*/
56     LV_EVENT_FOCUSED,             /**< Widget received focus */
57     LV_EVENT_DEFOCUSED,           /**< Widget's focus has been lost */
58     LV_EVENT_LEAVE,               /**< Widget's focus has been lost but is still selected */
59     LV_EVENT_HIT_TEST,            /**< Perform advanced hit-testing */
60     LV_EVENT_INDEV_RESET,         /**< Indev has been reset */
61     LV_EVENT_HOVER_OVER,          /**< Indev hover over object */
62     LV_EVENT_HOVER_LEAVE,         /**< Indev hover leave object */
63 
64     /** Drawing events */
65     LV_EVENT_COVER_CHECK,         /**< Check if Widget fully covers an area. The event parameter is `lv_cover_check_info_t *`. */
66     LV_EVENT_REFR_EXT_DRAW_SIZE,  /**< Get required extra draw area around Widget (e.g. for shadow). The event parameter is `int32_t *` to store the size. */
67     LV_EVENT_DRAW_MAIN_BEGIN,     /**< Starting the main drawing phase */
68     LV_EVENT_DRAW_MAIN,           /**< Perform the main drawing */
69     LV_EVENT_DRAW_MAIN_END,       /**< Finishing the main drawing phase */
70     LV_EVENT_DRAW_POST_BEGIN,     /**< Starting the post draw phase (when all children are drawn)*/
71     LV_EVENT_DRAW_POST,           /**< Perform the post draw phase (when all children are drawn)*/
72     LV_EVENT_DRAW_POST_END,       /**< Finishing the post draw phase (when all children are drawn)*/
73     LV_EVENT_DRAW_TASK_ADDED,     /**< Adding a draw task */
74 
75     /** Special events */
76     LV_EVENT_VALUE_CHANGED,       /**< Widget's value has changed (i.e. slider moved)*/
77     LV_EVENT_INSERT,              /**< Text has been inserted into Widget. The event data is `char *` being inserted. */
78     LV_EVENT_REFRESH,             /**< Notify Widget to refresh something on it (for user)*/
79     LV_EVENT_READY,               /**< A process has finished */
80     LV_EVENT_CANCEL,              /**< A process has been cancelled */
81 
82     /** Other events */
83     LV_EVENT_CREATE,              /**< Object is being created */
84     LV_EVENT_DELETE,              /**< Object is being deleted */
85     LV_EVENT_CHILD_CHANGED,       /**< Child was removed, added, or its size, position were changed */
86     LV_EVENT_CHILD_CREATED,       /**< Child was created, always bubbles up to all parents */
87     LV_EVENT_CHILD_DELETED,       /**< Child was deleted, always bubbles up to all parents */
88     LV_EVENT_SCREEN_UNLOAD_START, /**< A screen unload started, fired immediately when scr_load is called */
89     LV_EVENT_SCREEN_LOAD_START,   /**< A screen load started, fired when the screen change delay is expired */
90     LV_EVENT_SCREEN_LOADED,       /**< A screen was loaded */
91     LV_EVENT_SCREEN_UNLOADED,     /**< A screen was unloaded */
92     LV_EVENT_SIZE_CHANGED,        /**< Object coordinates/size have changed */
93     LV_EVENT_STYLE_CHANGED,       /**< Object's style has changed */
94     LV_EVENT_LAYOUT_CHANGED,      /**< A child's position position has changed due to a layout recalculation */
95     LV_EVENT_GET_SELF_SIZE,       /**< Get internal size of a widget */
96 
97     /** Events of optional LVGL components */
98     LV_EVENT_INVALIDATE_AREA,
99     LV_EVENT_RESOLUTION_CHANGED,
100     LV_EVENT_COLOR_FORMAT_CHANGED,
101     LV_EVENT_REFR_REQUEST,
102     LV_EVENT_REFR_START,
103     LV_EVENT_REFR_READY,
104     LV_EVENT_RENDER_START,
105     LV_EVENT_RENDER_READY,
106     LV_EVENT_FLUSH_START,
107     LV_EVENT_FLUSH_FINISH,
108     LV_EVENT_FLUSH_WAIT_START,
109     LV_EVENT_FLUSH_WAIT_FINISH,
110 
111     LV_EVENT_VSYNC,
112 
113     LV_EVENT_LAST,                 /** Number of default events */
114 
115     LV_EVENT_PREPROCESS = 0x8000,   /** This is a flag that can be set with an event so it's processed
116                                       before the class default event processing */
117     LV_EVENT_MARKED_DELETING = 0x10000,
118 } lv_event_code_t;
119 
120 typedef struct {
121     lv_array_t array;
122     uint8_t is_traversing: 1;          /**< True: the list is being nested traversed */
123     uint8_t has_marked_deleting: 1;    /**< True: the list has marked deleting objects
124                                          when some of events are marked as deleting */
125 } lv_event_list_t;
126 
127 /**
128  * @brief Event callback.
129  * Events are used to notify the user of some action being taken on Widget.
130  * For details, see ::lv_event_t.
131  */
132 
133 lv_result_t lv_event_send(lv_event_list_t * list, lv_event_t * e, bool preprocess);
134 
135 lv_event_dsc_t * lv_event_add(lv_event_list_t * list, lv_event_cb_t cb, lv_event_code_t filter, void * user_data);
136 bool lv_event_remove_dsc(lv_event_list_t * list, lv_event_dsc_t * dsc);
137 
138 uint32_t lv_event_get_count(lv_event_list_t * list);
139 
140 lv_event_dsc_t * lv_event_get_dsc(lv_event_list_t * list, uint32_t index);
141 
142 lv_event_cb_t lv_event_dsc_get_cb(lv_event_dsc_t * dsc);
143 
144 void * lv_event_dsc_get_user_data(lv_event_dsc_t * dsc);
145 
146 bool lv_event_remove(lv_event_list_t * list, uint32_t index);
147 
148 void lv_event_remove_all(lv_event_list_t * list);
149 
150 /**
151  * Get Widget originally targeted by the event. It's the same even if event was bubbled.
152  * @param e     pointer to the event descriptor
153  * @return      the target of the event_code
154  */
155 void * lv_event_get_target(lv_event_t * e);
156 
157 /**
158  * Get current target of the event. It's the Widget for which the event handler being called.
159  * If the event is not bubbled it's the same as "normal" target.
160  * @param e     pointer to the event descriptor
161  * @return      pointer to the current target of the event_code
162  */
163 void * lv_event_get_current_target(lv_event_t * e);
164 
165 /**
166  * Get event code of an event.
167  * @param e     pointer to the event descriptor
168  * @return      the event code. (E.g. `LV_EVENT_CLICKED`, `LV_EVENT_FOCUSED`, etc)
169  */
170 lv_event_code_t lv_event_get_code(lv_event_t * e);
171 
172 /**
173  * Get parameter passed when event was sent.
174  * @param e     pointer to the event descriptor
175  * @return      pointer to the parameter
176  */
177 void * lv_event_get_param(lv_event_t * e);
178 
179 /**
180  * Get user_data passed when event was registered on Widget.
181  * @param e     pointer to the event descriptor
182  * @return      pointer to the user_data
183  */
184 void * lv_event_get_user_data(lv_event_t * e);
185 
186 /**
187  * Stop event from bubbling.
188  * This is only valid when called in the middle of an event processing chain.
189  * @param e     pointer to the event descriptor
190  */
191 void lv_event_stop_bubbling(lv_event_t * e);
192 
193 /**
194  * Stop processing this event.
195  * This is only valid when called in the middle of an event processing chain.
196  * @param e     pointer to the event descriptor
197  */
198 void lv_event_stop_processing(lv_event_t * e);
199 
200 /**
201  * Register a new, custom event ID.
202  * It can be used the same way as e.g. `LV_EVENT_CLICKED` to send custom events
203  * @return      the new event id
204  *
205  * Example:
206  * @code
207  * uint32_t LV_EVENT_MINE = 0;
208  * ...
209  * e = lv_event_register_id();
210  * ...
211  * lv_obj_send_event(obj, LV_EVENT_MINE, &some_data);
212  * @endcode
213  */
214 uint32_t lv_event_register_id(void);
215 
216 /**
217  * Get the name of an event code.
218  * @param code  the event code
219  * @return      the name of the event code as a string
220  */
221 const char * lv_event_code_get_name(lv_event_code_t code);
222 
223 /**********************
224  *      MACROS
225  **********************/
226 
227 #ifdef __cplusplus
228 } /*extern "C"*/
229 #endif
230 
231 #endif /* LV_EVENT_H */
232