1# Events
2
3Events are triggered in LVGL when something happens which might be interesting to the user, e.g. when an object
4- is clicked
5- is scrolled
6- has its value changed
7- is redrawn, etc.
8
9## Add events to the object
10
11The user can assign callback functions to an object to see its events. In practice, it looks like this:
12```c
13lv_obj_t * btn = lv_btn_create(lv_scr_act());
14lv_obj_add_event_cb(btn, my_event_cb, LV_EVENT_CLICKED, NULL);   /*Assign an event callback*/
15
16...
17
18static void my_event_cb(lv_event_t * event)
19{
20    printf("Clicked\n");
21}
22```
23In 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.
24`LV_EVENT_ALL` can be used to receive all events.
25
26The 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.
27
28More events can be added to an object, like this:
29```c
30lv_obj_add_event_cb(obj, my_event_cb_1, LV_EVENT_CLICKED, NULL);
31lv_obj_add_event_cb(obj, my_event_cb_2, LV_EVENT_PRESSED, NULL);
32lv_obj_add_event_cb(obj, my_event_cb_3, LV_EVENT_ALL, NULL);		/*No filtering, receive all events*/
33```
34
35Even the same event callback can be used on an object with different `user_data`. For example:
36```c
37lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num1);
38lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num2);
39```
40
41The events will be called in the order as they were added.
42
43
44Other objects can use the same *event callback*.
45
46
47## Remove event(s) from an object
48
49Events 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`.
50
51## Event codes
52
53The event codes can be grouped into these categories:
54- Input device events
55- Drawing events
56- Other events
57- Special events
58- Custom events
59
60All objects (such as Buttons/Labels/Sliders etc.) regardless their type receive the *Input device*, *Drawing* and *Other* events.
61
62However, the *Special events* are specific to a particular widget type. See the [widgets' documentation](/widgets/index) to learn when they are sent,
63
64*Custom events* are added by the user and are never sent by LVGL.
65
66The following event codes exist:
67
68### Input device events
69- `LV_EVENT_PRESSED`      An object has been pressed
70- `LV_EVENT_PRESSING`     An object is being pressed (called continuously while pressing)
71- `LV_EVENT_PRESS_LOST`   An object is still being pressed but slid cursor/finger off of the object
72- `LV_EVENT_SHORT_CLICKED`    An object was pressed for a short period of time, then released. Not called if scrolled.
73- `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.
74- `LV_EVENT_LONG_PRESSED_REPEAT`  Called after `long_press_time` in every `long_press_repeat_time` ms.  Not called if scrolled.
75- `LV_EVENT_CLICKED`      Called on release if an object did not scroll (regardless of long press)
76- `LV_EVENT_RELEASED`     Called in every case when an object has been released
77- `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.
78- `LV_EVENT_SCROLL_END`   Scrolling ends.
79- `LV_EVENT_SCROLL`       An object was scrolled
80- `LV_EVENT_GESTURE`      A gesture is detected. Get the gesture with `lv_indev_get_gesture_dir(lv_indev_get_act());`
81- `LV_EVENT_KEY`          A key is sent to an object. Get the key with `lv_indev_get_key(lv_indev_get_act());`
82- `LV_EVENT_FOCUSED`      An object is focused
83- `LV_EVENT_DEFOCUSED`    An object is unfocused
84- `LV_EVENT_LEAVE`        An object is unfocused but still selected
85- `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`
86
87
88### Drawing events
89- `LV_EVENT_COVER_CHECK` Check if an object fully covers an area. The event parameter is `lv_cover_check_info_t *`.
90- `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.
91- `LV_EVENT_DRAW_MAIN_BEGIN` Starting the main drawing phase.
92- `LV_EVENT_DRAW_MAIN`   Perform the main drawing
93- `LV_EVENT_DRAW_MAIN_END`   Finishing the main drawing phase
94- `LV_EVENT_DRAW_POST_BEGIN` Starting the post draw phase (when all children are drawn)
95- `LV_EVENT_DRAW_POST`   Perform the post draw phase (when all children are drawn)
96- `LV_EVENT_DRAW_POST_END`   Finishing the post draw phase (when all children are drawn)
97- `LV_EVENT_DRAW_PART_BEGIN` Starting to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. Learn more [here](/overview/drawing).
98- `LV_EVENT_DRAW_PART_END`   Finishing to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. Learn more [here](/overview/drawing).
99
100In `LV_EVENT_DRAW_...` events it's not allowed to adjust the widgets' properties. E.g. you can not call `lv_obj_set_width()`.
101In other words only `get` functions can be called.
102
103### Other events
104- `LV_EVENT_DELETE`       Object is being deleted
105- `LV_EVENT_CHILD_CHANGED`    Child was removed/added
106- `LV_EVENT_CHILD_CREATED`    Child was created, always bubbles up to all parents
107- `LV_EVENT_CHILD_DELETED`    Child was deleted, always bubbles up to all parents
108- `LV_EVENT_SIZE_CHANGED`    Object coordinates/size have changed
109- `LV_EVENT_STYLE_CHANGED`    Object's style has changed
110- `LV_EVENT_BASE_DIR_CHANGED` The base dir has changed
111- `LV_EVENT_GET_SELF_SIZE`    Get the internal size of a widget
112- `LV_EVENT_SCREEN_UNLOAD_START` A screen unload started, fired immediately when lv_scr_load/lv_scr_load_anim is called
113- `LV_EVENT_SCREEN_LOAD_START` A screen load started, fired when the screen change delay is expired
114- `LV_EVENT_SCREEN_LOADED`    A screen was loaded, called when all animations are finished
115- `LV_EVENT_SCREEN_UNLOADED`  A screen was unloaded, called when all animations are finished
116
117### Special events
118- `LV_EVENT_VALUE_CHANGED`    The object's value has changed (i.e. slider moved)
119- `LV_EVENT_INSERT`       Text is being inserted into the object. The event data is `char *` being inserted.
120- `LV_EVENT_REFRESH`      Notify the object to refresh something on it (for the user)
121- `LV_EVENT_READY`        A process has finished
122- `LV_EVENT_CANCEL`       A process has been canceled
123
124
125### Custom events
126Any custom event codes can be registered by `uint32_t MY_EVENT_1 = lv_event_register_id();`
127
128They can be sent to any object with `lv_event_send(obj, MY_EVENT_1, &some_data)`
129
130## Sending events
131
132To manually send events to an object, use `lv_event_send(obj, <EVENT_CODE> &some_data)`.
133
134For example, this can be used to manually close a message box by simulating a button press (although there are simpler ways to do this):
135```c
136/*Simulate the press of the first button (indexes start from zero)*/
137uint32_t btn_id = 0;
138lv_event_send(mbox, LV_EVENT_VALUE_CHANGED, &btn_id);
139```
140
141### Refresh event
142
143`LV_EVENT_REFRESH` is a special event because it's designed to let the user notify an object to refresh itself. Some examples:
144- notify a label to refresh its text according to one or more variables (e.g. current time)
145- refresh a label when the language changes
146- enable a button if some conditions are met (e.g. the correct PIN is entered)
147- add/remove styles to/from an object if a limit is exceeded, etc
148
149## Fields of lv_event_t
150
151`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:
152- `lv_event_get_code(e)` get the event code
153- `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.
154- `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)
155- `lv_event_get_user_data(e)` get the pointer passed as the last parameter of `lv_obj_add_event_cb`.
156- `lv_event_get_param(e)` get the parameter passed as the last parameter of `lv_event_send`
157
158
159## Event bubbling
160
161If `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.
162
163The *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.
164
165
166
167## Examples
168
169```eval_rst
170
171.. include:: ../../examples/event/index.rst
172
173```
174