acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

lv_event.h (15643B)

      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*/