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 <stdbool.h> 17 18 /********************* 19 * DEFINES 20 *********************/ 21 22 /********************** 23 * TYPEDEFS 24 **********************/ 25 26 struct _lv_obj_t; 27 struct _lv_event_dsc_t; 28 29 /** 30 * Type of event being sent to the object. 31 */ 32 typedef enum { 33 LV_EVENT_ALL = 0, 34 35 /** Input device events*/ 36 LV_EVENT_PRESSED, /**< The object has been pressed*/ 37 LV_EVENT_PRESSING, /**< The object is being pressed (called continuously while pressing)*/ 38 LV_EVENT_PRESS_LOST, /**< The object is still being pressed but slid cursor/finger off of the object */ 39 LV_EVENT_SHORT_CLICKED, /**< The object was pressed for a short period of time, then released it. Not called if scrolled.*/ 40 LV_EVENT_LONG_PRESSED, /**< Object has been pressed for at least `long_press_time`. Not called if scrolled.*/ 41 LV_EVENT_LONG_PRESSED_REPEAT, /**< Called after `long_press_time` in every `long_press_repeat_time` ms. Not called if scrolled.*/ 42 LV_EVENT_CLICKED, /**< Called on release if not scrolled (regardless to long press)*/ 43 LV_EVENT_RELEASED, /**< Called in every cases when the object has been released*/ 44 LV_EVENT_SCROLL_BEGIN, /**< Scrolling begins. The event parameter is a pointer to the animation of the scroll. Can be modified*/ 45 LV_EVENT_SCROLL_END, /**< Scrolling ends*/ 46 LV_EVENT_SCROLL, /**< Scrolling*/ 47 LV_EVENT_GESTURE, /**< A gesture is detected. Get the gesture with `lv_indev_get_gesture_dir(lv_indev_get_act());` */ 48 LV_EVENT_KEY, /**< A key is sent to the object. Get the key with `lv_indev_get_key(lv_indev_get_act());`*/ 49 LV_EVENT_FOCUSED, /**< The object is focused*/ 50 LV_EVENT_DEFOCUSED, /**< The object is defocused*/ 51 LV_EVENT_LEAVE, /**< The object is defocused but still selected*/ 52 LV_EVENT_HIT_TEST, /**< Perform advanced hit-testing*/ 53 54 /** Drawing events*/ 55 LV_EVENT_COVER_CHECK, /**< Check if the object fully covers an area. The event parameter is `lv_cover_check_info_t *`.*/ 56 LV_EVENT_REFR_EXT_DRAW_SIZE, /**< Get the required extra draw area around the object (e.g. for shadow). The event parameter is `lv_coord_t *` to store the size.*/ 57 LV_EVENT_DRAW_MAIN_BEGIN, /**< Starting the main drawing phase*/ 58 LV_EVENT_DRAW_MAIN, /**< Perform the main drawing*/ 59 LV_EVENT_DRAW_MAIN_END, /**< Finishing the main drawing phase*/ 60 LV_EVENT_DRAW_POST_BEGIN, /**< Starting the post draw phase (when all children are drawn)*/ 61 LV_EVENT_DRAW_POST, /**< Perform the post draw phase (when all children are drawn)*/ 62 LV_EVENT_DRAW_POST_END, /**< Finishing the post draw phase (when all children are drawn)*/ 63 LV_EVENT_DRAW_PART_BEGIN, /**< Starting to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. */ 64 LV_EVENT_DRAW_PART_END, /**< Finishing to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. */ 65 66 /** Special events*/ 67 LV_EVENT_VALUE_CHANGED, /**< The object's value has changed (i.e. slider moved)*/ 68 LV_EVENT_INSERT, /**< A text is inserted to the object. The event data is `char *` being inserted.*/ 69 LV_EVENT_REFRESH, /**< Notify the object to refresh something on it (for the user)*/ 70 LV_EVENT_READY, /**< A process has finished*/ 71 LV_EVENT_CANCEL, /**< A process has been cancelled */ 72 73 /** Other events*/ 74 LV_EVENT_DELETE, /**< Object is being deleted*/ 75 LV_EVENT_CHILD_CHANGED, /**< Child was removed, added, or its size, position were changed */ 76 LV_EVENT_CHILD_CREATED, /**< Child was created, always bubbles up to all parents*/ 77 LV_EVENT_CHILD_DELETED, /**< Child was deleted, always bubbles up to all parents*/ 78 LV_EVENT_SCREEN_UNLOAD_START, /**< A screen unload started, fired immediately when scr_load is called*/ 79 LV_EVENT_SCREEN_LOAD_START, /**< A screen load started, fired when the screen change delay is expired*/ 80 LV_EVENT_SCREEN_LOADED, /**< A screen was loaded*/ 81 LV_EVENT_SCREEN_UNLOADED, /**< A screen was unloaded*/ 82 LV_EVENT_SIZE_CHANGED, /**< Object coordinates/size have changed*/ 83 LV_EVENT_STYLE_CHANGED, /**< Object's style has changed*/ 84 LV_EVENT_LAYOUT_CHANGED, /**< The children position has changed due to a layout recalculation*/ 85 LV_EVENT_GET_SELF_SIZE, /**< Get the internal size of a widget*/ 86 87 _LV_EVENT_LAST, /** Number of default events*/ 88 89 90 LV_EVENT_PREPROCESS = 0x80, /** This is a flag that can be set with an event so it's processed 91 before the class default event processing */ 92 } lv_event_code_t; 93 94 typedef struct _lv_event_t { 95 struct _lv_obj_t * target; 96 struct _lv_obj_t * current_target; 97 lv_event_code_t code; 98 void * user_data; 99 void * param; 100 struct _lv_event_t * prev; 101 uint8_t deleted : 1; 102 uint8_t stop_processing : 1; 103 uint8_t stop_bubbling : 1; 104 } lv_event_t; 105 106 /** 107 * @brief Event callback. 108 * Events are used to notify the user of some action being taken on the object. 109 * For details, see ::lv_event_t. 110 */ 111 typedef void (*lv_event_cb_t)(lv_event_t * e); 112 113 /** 114 * Used as the event parameter of ::LV_EVENT_HIT_TEST to check if an `point` can click the object or not. 115 * `res` should be set like this: 116 * - If already set to `false` an other event wants that point non clickable. If you want to respect it leave it as `false` or set `true` to overwrite it. 117 * - If already set `true` and `point` shouldn't be clickable set to `false` 118 * - If already set to `true` you agree that `point` can click the object leave it as `true` 119 */ 120 typedef struct { 121 const lv_point_t * point; /**< A point relative to screen to check if it can click the object or not*/ 122 bool res; /**< true: `point` can click the object; false: it cannot*/ 123 } lv_hit_test_info_t; 124 125 /** 126 * Used as the event parameter of ::LV_EVENT_COVER_CHECK to check if an area is covered by the object or not. 127 * In the event use `const lv_area_t * area = lv_event_get_cover_area(e)` to get the area to check 128 * and `lv_event_set_cover_res(e, res)` to set the result. 129 */ 130 typedef struct { 131 lv_cover_res_t res; 132 const lv_area_t * area; 133 } lv_cover_check_info_t; 134 135 /********************** 136 * GLOBAL PROTOTYPES 137 **********************/ 138 139 /** 140 * Send an event to the object 141 * @param obj pointer to an object 142 * @param event_code the type of the event from `lv_event_t` 143 * @param param arbitrary data depending on the widget type and the event. (Usually `NULL`) 144 * @return LV_RES_OK: `obj` was not deleted in the event; LV_RES_INV: `obj` was deleted in the event_code 145 */ 146 lv_res_t lv_event_send(struct _lv_obj_t * obj, lv_event_code_t event_code, void * param); 147 148 /** 149 * Used by the widgets internally to call the ancestor widget types's event handler 150 * @param class_p pointer to the class of the widget (NOT the ancestor class) 151 * @param e pointer to the event descriptor 152 * @return LV_RES_OK: the target object was not deleted in the event; LV_RES_INV: it was deleted in the event_code 153 */ 154 lv_res_t lv_obj_event_base(const lv_obj_class_t * class_p, lv_event_t * e); 155 156 /** 157 * Get the object originally targeted by the event. It's the same even if the event is bubbled. 158 * @param e pointer to the event descriptor 159 * @return the target of the event_code 160 */ 161 struct _lv_obj_t * lv_event_get_target(lv_event_t * e); 162 163 /** 164 * Get the current target of the event. It's the object which event handler being called. 165 * If the event is not bubbled it's the same as "normal" target. 166 * @param e pointer to the event descriptor 167 * @return pointer to the current target of the event_code 168 */ 169 struct _lv_obj_t * lv_event_get_current_target(lv_event_t * e); 170 171 /** 172 * Get the event code of an event 173 * @param e pointer to the event descriptor 174 * @return the event code. (E.g. `LV_EVENT_CLICKED`, `LV_EVENT_FOCUSED`, etc) 175 */ 176 lv_event_code_t lv_event_get_code(lv_event_t * e); 177 178 /** 179 * Get the parameter passed when the event was sent 180 * @param e pointer to the event descriptor 181 * @return pointer to the parameter 182 */ 183 void * lv_event_get_param(lv_event_t * e); 184 185 /** 186 * Get the user_data passed when the event was registered on the object 187 * @param e pointer to the event descriptor 188 * @return pointer to the user_data 189 */ 190 void * lv_event_get_user_data(lv_event_t * e); 191 192 /** 193 * Stop the event from bubbling. 194 * This is only valid when called in the middle of an event processing chain. 195 * @param e pointer to the event descriptor 196 */ 197 void lv_event_stop_bubbling(lv_event_t * e); 198 199 /** 200 * Stop processing this event. 201 * This is only valid when called in the middle of an event processing chain. 202 * @param e pointer to the event descriptor 203 */ 204 void lv_event_stop_processing(lv_event_t * e); 205 206 /** 207 * Register a new, custom event ID. 208 * It can be used the same way as e.g. `LV_EVENT_CLICKED` to send custom events 209 * @return the new event id 210 * @example 211 * uint32_t LV_EVENT_MINE = 0; 212 * ... 213 * e = lv_event_register_id(); 214 * ... 215 * lv_event_send(obj, LV_EVENT_MINE, &some_data); 216 */ 217 uint32_t lv_event_register_id(void); 218 219 /** 220 * Nested events can be called and one of them might belong to an object that is being deleted. 221 * Mark this object's `event_temp_data` deleted to know that its `lv_event_send` should return `LV_RES_INV` 222 * @param obj pointer to an object to mark as deleted 223 */ 224 void _lv_event_mark_deleted(struct _lv_obj_t * obj); 225 226 227 /** 228 * Add an event handler function for an object. 229 * Used by the user to react on event which happens with the object. 230 * An object can have multiple event handler. They will be called in the same order as they were added. 231 * @param obj pointer to an object 232 * @param filter and event code (e.g. `LV_EVENT_CLICKED`) on which the event should be called. `LV_EVENT_ALL` can be sued the receive all the events. 233 * @param event_cb the new event function 234 * @param user_data custom data data will be available in `event_cb` 235 * @return a pointer the event descriptor. Can be used in ::lv_obj_remove_event_dsc 236 */ 237 struct _lv_event_dsc_t * lv_obj_add_event_cb(struct _lv_obj_t * obj, lv_event_cb_t event_cb, lv_event_code_t filter, 238 void * user_data); 239 240 /** 241 * Remove an event handler function for an object. 242 * @param obj pointer to an object 243 * @param event_cb the event function to remove, or `NULL` to remove the firstly added event callback 244 * @return true if any event handlers were removed 245 */ 246 bool lv_obj_remove_event_cb(struct _lv_obj_t * obj, lv_event_cb_t event_cb); 247 248 /** 249 * Remove an event handler function with a specific user_data from an object. 250 * @param obj pointer to an object 251 * @param event_cb the event function to remove, or `NULL` only `user_data` matters. 252 * @param event_user_data the user_data specified in ::lv_obj_add_event_cb 253 * @return true if any event handlers were removed 254 */ 255 bool lv_obj_remove_event_cb_with_user_data(struct _lv_obj_t * obj, lv_event_cb_t event_cb, 256 const void * event_user_data); 257 258 /** 259 * DEPRECATED because doesn't work if multiple event handlers are added to an object. 260 * Remove an event handler function for an object. 261 * @param obj pointer to an object 262 * @param event_dsc pointer to an event descriptor to remove (returned by ::lv_obj_add_event_cb) 263 * @return true if any event handlers were removed 264 */ 265 bool lv_obj_remove_event_dsc(struct _lv_obj_t * obj, struct _lv_event_dsc_t * event_dsc); 266 267 /** 268 * The user data of an event object event callback. Always the first match with `event_cb` will be returned. 269 * @param obj pointer to an object 270 * @param event_cb the event function 271 * @return the user_data 272 */ 273 void * lv_obj_get_event_user_data(struct _lv_obj_t * obj, lv_event_cb_t event_cb); 274 275 /** 276 * Get the input device passed as parameter to indev related events. 277 * @param e pointer to an event 278 * @return the indev that triggered the event or NULL if called on a not indev related event 279 */ 280 lv_indev_t * lv_event_get_indev(lv_event_t * e); 281 282 /** 283 * Get the part draw descriptor passed as parameter to `LV_EVENT_DRAW_PART_BEGIN/END`. 284 * @param e pointer to an event 285 * @return the part draw descriptor to hook the drawing or NULL if called on an unrelated event 286 */ 287 lv_obj_draw_part_dsc_t * lv_event_get_draw_part_dsc(lv_event_t * e); 288 289 /** 290 * Get the draw context which should be the first parameter of the draw functions. 291 * Namely: `LV_EVENT_DRAW_MAIN/POST`, `LV_EVENT_DRAW_MAIN/POST_BEGIN`, `LV_EVENT_DRAW_MAIN/POST_END` 292 * @param e pointer to an event 293 * @return pointer to a draw context or NULL if called on an unrelated event 294 */ 295 lv_draw_ctx_t * lv_event_get_draw_ctx(lv_event_t * e); 296 297 /** 298 * Get the old area of the object before its size was changed. Can be used in `LV_EVENT_SIZE_CHANGED` 299 * @param e pointer to an event 300 * @return the old absolute area of the object or NULL if called on an unrelated event 301 */ 302 const lv_area_t * lv_event_get_old_size(lv_event_t * e); 303 304 /** 305 * Get the key passed as parameter to an event. Can be used in `LV_EVENT_KEY` 306 * @param e pointer to an event 307 * @return the triggering key or NULL if called on an unrelated event 308 */ 309 uint32_t lv_event_get_key(lv_event_t * e); 310 311 /** 312 * Get the animation descriptor of a scrolling. Can be used in `LV_EVENT_SCROLL_BEGIN` 313 * @param e pointer to an event 314 * @return the animation that will scroll the object. (can be modified as required) 315 */ 316 lv_anim_t * lv_event_get_scroll_anim(lv_event_t * e); 317 318 /** 319 * Set the new extra draw size. Can be used in `LV_EVENT_REFR_EXT_DRAW_SIZE` 320 * @param e pointer to an event 321 * @param size The new extra draw size 322 */ 323 void lv_event_set_ext_draw_size(lv_event_t * e, lv_coord_t size); 324 325 /** 326 * Get a pointer to an `lv_point_t` variable in which the self size should be saved (width in `point->x` and height `point->y`). 327 * Can be used in `LV_EVENT_GET_SELF_SIZE` 328 * @param e pointer to an event 329 * @return pointer to `lv_point_t` or NULL if called on an unrelated event 330 */ 331 lv_point_t * lv_event_get_self_size_info(lv_event_t * e); 332 333 /** 334 * Get a pointer to an `lv_hit_test_info_t` variable in which the hit test result should be saved. Can be used in `LV_EVENT_HIT_TEST` 335 * @param e pointer to an event 336 * @return pointer to `lv_hit_test_info_t` or NULL if called on an unrelated event 337 */ 338 lv_hit_test_info_t * lv_event_get_hit_test_info(lv_event_t * e); 339 340 /** 341 * Get a pointer to an area which should be examined whether the object fully covers it or not. 342 * Can be used in `LV_EVENT_HIT_TEST` 343 * @param e pointer to an event 344 * @return an area with absolute coordinates to check 345 */ 346 const lv_area_t * lv_event_get_cover_area(lv_event_t * e); 347 348 /** 349 * Set the result of cover checking. Can be used in `LV_EVENT_COVER_CHECK` 350 * @param e pointer to an event 351 * @param res an element of ::lv_cover_check_info_t 352 */ 353 void lv_event_set_cover_res(lv_event_t * e, lv_cover_res_t res); 354 355 /********************** 356 * MACROS 357 **********************/ 358 359 #ifdef __cplusplus 360 } /*extern "C"*/ 361 #endif 362 363 #endif /*LV_EVENT_H*/ 364
