From dd27c3530432ea0b09f01e604bf577f31d8ef841 Mon Sep 17 00:00:00 2001 From: jacqueline Date: Thu, 1 Jun 2023 15:41:47 +1000 Subject: convert lvgl from submodule to a plain old directory --- lib/lvgl | 1 - lib/lvgl/docs/overview/event.md | 173 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 173 insertions(+), 1 deletion(-) delete mode 160000 lib/lvgl create mode 100644 lib/lvgl/docs/overview/event.md (limited to 'lib/lvgl/docs/overview/event.md') diff --git a/lib/lvgl b/lib/lvgl deleted file mode 160000 index 0732400e..00000000 --- a/lib/lvgl +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 0732400e7b564dd0e7dc4a924619d8e19c5b23a0 diff --git a/lib/lvgl/docs/overview/event.md b/lib/lvgl/docs/overview/event.md new file mode 100644 index 00000000..e6dd730a --- /dev/null +++ b/lib/lvgl/docs/overview/event.md @@ -0,0 +1,173 @@ +# Events + +Events are triggered in LVGL when something happens which might be interesting to the user, e.g. when an object +- is clicked +- is scrolled +- has its value changed +- is redrawn, etc. + +## Add events to the object + +The user can assign callback functions to an object to see its events. In practice, it looks like this: +```c +lv_obj_t * btn = lv_btn_create(lv_scr_act()); +lv_obj_add_event_cb(btn, my_event_cb, LV_EVENT_CLICKED, NULL); /*Assign an event callback*/ + +... + +static void my_event_cb(lv_event_t * event) +{ + printf("Clicked\n"); +} +``` +In the example `LV_EVENT_CLICKED` means that only the click event will call `my_event_cb`. See the [list of event codes](#event-codes) for all the options. +`LV_EVENT_ALL` can be used to receive all events. + +The last parameter of `lv_obj_add_event_cb` is a pointer to any custom data that will be available in the event. It will be described later in more detail. + +More events can be added to an object, like this: +```c +lv_obj_add_event_cb(obj, my_event_cb_1, LV_EVENT_CLICKED, NULL); +lv_obj_add_event_cb(obj, my_event_cb_2, LV_EVENT_PRESSED, NULL); +lv_obj_add_event_cb(obj, my_event_cb_3, LV_EVENT_ALL, NULL); /*No filtering, receive all events*/ +``` + +Even the same event callback can be used on an object with different `user_data`. For example: +```c +lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num1); +lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num2); +``` + +The events will be called in the order as they were added. + + +Other objects can use the same *event callback*. + + +## Remove event(s) from an object + +Events can be removed from an object with the `lv_obj_remove_event_cb(obj, event_cb)` function or `lv_obj_remove_event_dsc(obj, event_dsc)`. `event_dsc` is a pointer returned by `lv_obj_add_event_cb`. + +## Event codes + +The event codes can be grouped into these categories: +- Input device events +- Drawing events +- Other events +- Special events +- Custom events + +All objects (such as Buttons/Labels/Sliders etc.) regardless their type receive the *Input device*, *Drawing* and *Other* events. + +However, the *Special events* are specific to a particular widget type. See the [widgets' documentation](/widgets/index) to learn when they are sent, + +*Custom events* are added by the user and are never sent by LVGL. + +The following event codes exist: + +### Input device events +- `LV_EVENT_PRESSED` An object has been pressed +- `LV_EVENT_PRESSING` An object is being pressed (called continuously while pressing) +- `LV_EVENT_PRESS_LOST` An object is still being pressed but slid cursor/finger off of the object +- `LV_EVENT_SHORT_CLICKED` An object was pressed for a short period of time, then released. Not called if scrolled. +- `LV_EVENT_LONG_PRESSED` An object has been pressed for at least the `long_press_time` specified in the input device driver. Not called if scrolled. +- `LV_EVENT_LONG_PRESSED_REPEAT` Called after `long_press_time` in every `long_press_repeat_time` ms. Not called if scrolled. +- `LV_EVENT_CLICKED` Called on release if an object did not scroll (regardless of long press) +- `LV_EVENT_RELEASED` Called in every case when an object has been released +- `LV_EVENT_SCROLL_BEGIN` Scrolling begins. The event parameter is `NULL` or an `lv_anim_t *` with a scroll animation descriptor that can be modified if required. +- `LV_EVENT_SCROLL_END` Scrolling ends. +- `LV_EVENT_SCROLL` An object was scrolled +- `LV_EVENT_GESTURE` A gesture is detected. Get the gesture with `lv_indev_get_gesture_dir(lv_indev_get_act());` +- `LV_EVENT_KEY` A key is sent to an object. Get the key with `lv_indev_get_key(lv_indev_get_act());` +- `LV_EVENT_FOCUSED` An object is focused +- `LV_EVENT_DEFOCUSED` An object is unfocused +- `LV_EVENT_LEAVE` An object is unfocused but still selected +- `LV_EVENT_HIT_TEST` Perform advanced hit-testing. Use `lv_hit_test_info_t * a = lv_event_get_hit_test_info(e)` and check if `a->point` can click the object or not. If not set `a->res = false` + + +### Drawing events +- `LV_EVENT_COVER_CHECK` Check if an object fully covers an area. The event parameter is `lv_cover_check_info_t *`. +- `LV_EVENT_REFR_EXT_DRAW_SIZE` Get the required extra draw area around an object (e.g. for a shadow). The event parameter is `lv_coord_t *` to store the size. Only overwrite it with a larger value. +- `LV_EVENT_DRAW_MAIN_BEGIN` Starting the main drawing phase. +- `LV_EVENT_DRAW_MAIN` Perform the main drawing +- `LV_EVENT_DRAW_MAIN_END` Finishing the main drawing phase +- `LV_EVENT_DRAW_POST_BEGIN` Starting the post draw phase (when all children are drawn) +- `LV_EVENT_DRAW_POST` Perform the post draw phase (when all children are drawn) +- `LV_EVENT_DRAW_POST_END` Finishing the post draw phase (when all children are drawn) +- `LV_EVENT_DRAW_PART_BEGIN` Starting to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. Learn more [here](/overview/drawing). +- `LV_EVENT_DRAW_PART_END` Finishing to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. Learn more [here](/overview/drawing). + +In `LV_EVENT_DRAW_...` events it's not allowed to adjust the widgets' properties. E.g. you can not call `lv_obj_set_width()`. +In other words only `get` functions can be called. + +### Other events +- `LV_EVENT_DELETE` Object is being deleted +- `LV_EVENT_CHILD_CHANGED` Child was removed/added +- `LV_EVENT_CHILD_CREATED` Child was created, always bubbles up to all parents +- `LV_EVENT_CHILD_DELETED` Child was deleted, always bubbles up to all parents +- `LV_EVENT_SIZE_CHANGED` Object coordinates/size have changed +- `LV_EVENT_STYLE_CHANGED` Object's style has changed +- `LV_EVENT_BASE_DIR_CHANGED` The base dir has changed +- `LV_EVENT_GET_SELF_SIZE` Get the internal size of a widget +- `LV_EVENT_SCREEN_UNLOAD_START` A screen unload started, fired immediately when lv_scr_load/lv_scr_load_anim is called +- `LV_EVENT_SCREEN_LOAD_START` A screen load started, fired when the screen change delay is expired +- `LV_EVENT_SCREEN_LOADED` A screen was loaded, called when all animations are finished +- `LV_EVENT_SCREEN_UNLOADED` A screen was unloaded, called when all animations are finished + +### Special events +- `LV_EVENT_VALUE_CHANGED` The object's value has changed (i.e. slider moved) +- `LV_EVENT_INSERT` Text is being inserted into the object. The event data is `char *` being inserted. +- `LV_EVENT_REFRESH` Notify the object to refresh something on it (for the user) +- `LV_EVENT_READY` A process has finished +- `LV_EVENT_CANCEL` A process has been canceled + + +### Custom events +Any custom event codes can be registered by `uint32_t MY_EVENT_1 = lv_event_register_id();` + +They can be sent to any object with `lv_event_send(obj, MY_EVENT_1, &some_data)` + +## Sending events + +To manually send events to an object, use `lv_event_send(obj, &some_data)`. + +For example, this can be used to manually close a message box by simulating a button press (although there are simpler ways to do this): +```c +/*Simulate the press of the first button (indexes start from zero)*/ +uint32_t btn_id = 0; +lv_event_send(mbox, LV_EVENT_VALUE_CHANGED, &btn_id); +``` + +### Refresh event + +`LV_EVENT_REFRESH` is a special event because it's designed to let the user notify an object to refresh itself. Some examples: +- notify a label to refresh its text according to one or more variables (e.g. current time) +- refresh a label when the language changes +- enable a button if some conditions are met (e.g. the correct PIN is entered) +- add/remove styles to/from an object if a limit is exceeded, etc + +## Fields of lv_event_t + +`lv_event_t` is the only parameter passed to the event callback and it contains all data about the event. The following values can be gotten from it: +- `lv_event_get_code(e)` get the event code +- `lv_event_get_current_target(e)` get the object to which an event was sent. I.e. the object whose event handler is being called. +- `lv_event_get_target(e)` get the object that originally triggered the event (different from `lv_event_get_target` if [event bubbling](#event-bubbling) is enabled) +- `lv_event_get_user_data(e)` get the pointer passed as the last parameter of `lv_obj_add_event_cb`. +- `lv_event_get_param(e)` get the parameter passed as the last parameter of `lv_event_send` + + +## Event bubbling + +If `lv_obj_add_flag(obj, LV_OBJ_FLAG_EVENT_BUBBLE)` is enabled all events will be sent to an object's parent too. If the parent also has `LV_OBJ_FLAG_EVENT_BUBBLE` enabled the event will be sent to its parent and so on. + +The *target* parameter of the event is always the current target object, not the original object. To get the original target call `lv_event_get_original_target(e)` in the event handler. + + + +## Examples + +```eval_rst + +.. include:: ../../examples/event/index.rst + +``` -- cgit v1.2.3