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 |
object.md (9939B)
1 ```eval_rst 2 .. include:: /header.rst 3 :github_url: |github_link_base|/overview/object.md 4 ``` 5 # Objects 6 7 In LVGL the **basic building blocks** of a user interface are the objects, also called *Widgets*. 8 For example a [Button](/widgets/core/btn), [Label](/widgets/core/label), [Image](/widgets/core/img), [List](/widgets/extra/list), [Chart](/widgets/extra/chart) or [Text area](/widgets/core/textarea). 9 10 You can see all the [Object types](/widgets/index) here. 11 12 All objects are referenced using an `lv_obj_t` pointer as a handle. This pointer can later be used to set or get the attributes of the object. 13 14 ## Attributes 15 16 ### Basic attributes 17 18 All object types share some basic attributes: 19 - Position 20 - Size 21 - Parent 22 - Styles 23 - Event handlers 24 - Etc 25 26 You can set/get these attributes with `lv_obj_set_...` and `lv_obj_get_...` functions. For example: 27 28 ```c 29 /*Set basic object attributes*/ 30 lv_obj_set_size(btn1, 100, 50); /*Set a button's size*/ 31 lv_obj_set_pos(btn1, 20,30); /*Set a button's position*/ 32 ``` 33 34 To see all the available functions visit the [Base object's documentation](/widgets/obj). 35 36 ### Specific attributes 37 38 The object types have special attributes too. For example, a slider has 39 - Minimum and maximum values 40 - Current value 41 42 For these special attributes, every object type may have unique API functions. For example for a slider: 43 44 ```c 45 /*Set slider specific attributes*/ 46 lv_slider_set_range(slider1, 0, 100); /*Set the min. and max. values*/ 47 lv_slider_set_value(slider1, 40, LV_ANIM_ON); /*Set the current value (position)*/ 48 ``` 49 50 The API of the widgets is described in their [Documentation](/widgets/index) but you can also check the respective header files (e.g. *widgets/lv_slider.h*) 51 52 ## Working mechanisms 53 54 ### Parent-child structure 55 56 A parent object can be considered as the container of its children. Every object has exactly one parent object (except screens), but a parent can have any number of children. 57 There is no limitation for the type of the parent but there are objects which are typically a parent (e.g. button) or a child (e.g. label). 58 59 ### Moving together 60 61 If the position of a parent changes, the children will move along with it. 62 Therefore, all positions are relative to the parent. 63 64 ![](/misc/par_child1.png "Objects are moving together 1") 65 66 ```c 67 lv_obj_t * parent = lv_obj_create(lv_scr_act()); /*Create a parent object on the current screen*/ 68 lv_obj_set_size(parent, 100, 80); /*Set the size of the parent*/ 69 70 lv_obj_t * obj1 = lv_obj_create(parent); /*Create an object on the previously created parent object*/ 71 lv_obj_set_pos(obj1, 10, 10); /*Set the position of the new object*/ 72 ``` 73 74 Modify the position of the parent: 75 76 ![](/misc/par_child2.png "Graphical objects are moving together 2") 77 78 ```c 79 lv_obj_set_pos(parent, 50, 50); /*Move the parent. The child will move with it.*/ 80 ``` 81 82 (For simplicity the adjusting of colors of the objects is not shown in the example.) 83 84 ### Visibility only on the parent 85 86 If a child is partially or fully outside its parent then the parts outside will not be visible. 87 88 ![](/misc/par_child3.png "A graphical object is visible on its parent") 89 90 ```c 91 lv_obj_set_x(obj1, -30); /*Move the child a little bit off the parent*/ 92 ``` 93 94 This behavior can be overwritten with `lv_obj_add_flag(obj, LV_OBJ_FLAG_OVERFLOW_VISIBLE);` which allow the children to be drawn out of the parent. 95 96 97 ### Create and delete objects 98 99 In LVGL, objects can be created and deleted dynamically at run time. It means only the currently created (existing) objects consume RAM. 100 101 This allows for the creation of a screen just when a button is clicked to open it, and for deletion of screens when a new screen is loaded. 102 103 UIs can be created based on the current environment of the device. For example one can create meters, charts, bars and sliders based on the currently attached sensors. 104 105 Every widget has its own **create** function with a prototype like this: 106 ```c 107 lv_obj_t * lv_<widget>_create(lv_obj_t * parent, <other parameters if any>); 108 ``` 109 110 Typically, the create functions only have a *parent* parameter telling them on which object to create the new widget. 111 112 The return value is a pointer to the created object with `lv_obj_t *` type. 113 114 115 There is a common **delete** function for all object types. It deletes the object and all of its children. 116 117 ```c 118 void lv_obj_del(lv_obj_t * obj); 119 ``` 120 121 `lv_obj_del` will delete the object immediately. 122 If for any reason you can't delete the object immediately you can use `lv_obj_del_async(obj)` which will perform the deletion on the next call of `lv_timer_handler()`. 123 This is useful e.g. if you want to delete the parent of an object in the child's `LV_EVENT_DELETE` handler. 124 125 You can remove all the children of an object (but not the object itself) using `lv_obj_clean(obj)`. 126 127 You can use `lv_obj_del_delayed(obj, 1000)` to delete an object after some time. The delay is expressed in milliseconds. 128 129 130 ## Screens 131 132 ### Create screens 133 The screens are special objects which have no parent object. So they can be created like: 134 ```c 135 lv_obj_t * scr1 = lv_obj_create(NULL); 136 ``` 137 138 Screens can be created with any object type. For example, a [Base object](/widgets/obj) or an image to make a wallpaper. 139 140 ### Get the active screen 141 There is always an active screen on each display. By default, the library creates and loads a "Base object" as a screen for each display. 142 143 To get the currently active screen use the `lv_scr_act()` function. 144 145 ### Load screens 146 147 To load a new screen, use `lv_scr_load(scr1)`. 148 149 ### Layers 150 There are two automatically generated layers: 151 - top layer 152 - system layer 153 154 They are independent of the screens and they will be shown on every screen. The *top layer* is above every object on the screen and the *system layer* is above the *top layer*. 155 You can add any pop-up windows to the *top layer* freely. But, the *system layer* is restricted to system-level things (e.g. mouse cursor will be placed there with `lv_indev_set_cursor()`). 156 157 The `lv_layer_top()` and `lv_layer_sys()` functions return pointers to the top and system layers respectively. 158 159 Read the [Layer overview](/overview/layer) section to learn more about layers. 160 161 162 #### Load screen with animation 163 164 A new screen can be loaded with animation by using `lv_scr_load_anim(scr, transition_type, time, delay, auto_del)`. The following transition types exist: 165 - `LV_SCR_LOAD_ANIM_NONE` Switch immediately after `delay` milliseconds 166 - `LV_SCR_LOAD_ANIM_OVER_LEFT/RIGHT/TOP/BOTTOM` Move the new screen over the current towards the given direction 167 - `LV_SCR_LOAD_ANIM_OUT_LEFT/RIGHT/TOP/BOTTOM` Move out the old screen over the current towards the given direction 168 - `LV_SCR_LOAD_ANIM_MOVE_LEFT/RIGHT/TOP/BOTTOM` Move both the current and new screens towards the given direction 169 - `LV_SCR_LOAD_ANIM_FADE_IN/OUT` Fade the new screen over the old screen, or vice versa 170 171 Setting `auto_del` to `true` will automatically delete the old screen when the animation is finished. 172 173 The new screen will become active (returned by `lv_scr_act()`) when the animation starts after `delay` time. 174 All inputs are disabled during the screen animation. 175 176 ### Handling multiple displays 177 Screens are created on the currently selected *default display*. 178 The *default display* is the last registered display with `lv_disp_drv_register`. You can also explicitly select a new default display using `lv_disp_set_default(disp)`. 179 180 `lv_scr_act()`, `lv_scr_load()` and `lv_scr_load_anim()` operate on the default screen. 181 182 Visit [Multi-display support](/overview/display) to learn more. 183 184 ## Parts 185 186 The widgets are built from multiple parts. For example a [Base object](/widgets/obj) uses the main and scrollbar parts but a [Slider](/widgets/core/slider) uses the main, indicator and knob parts. 187 Parts are similar to *pseudo-elements* in CSS. 188 189 The following predefined parts exist in LVGL: 190 - `LV_PART_MAIN` A background like rectangle 191 - `LV_PART_SCROLLBAR` The scrollbar(s) 192 - `LV_PART_INDICATOR` Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox 193 - `LV_PART_KNOB` Like a handle to grab to adjust the value 194 - `LV_PART_SELECTED` Indicate the currently selected option or section 195 - `LV_PART_ITEMS` Used if the widget has multiple similar elements (e.g. table cells) 196 - `LV_PART_TICKS` Ticks on scales e.g. for a chart or meter 197 - `LV_PART_CURSOR` Mark a specific place e.g. text area's or chart's cursor 198 - `LV_PART_CUSTOM_FIRST` Custom parts can be added from here. 199 200 The main purpose of parts is to allow styling the "components" of the widgets. 201 They are described in more detail in the [Style overview](/overview/style) section. 202 203 ## States 204 The object can be in a combination of the following states: 205 - `LV_STATE_DEFAULT` Normal, released state 206 - `LV_STATE_CHECKED` Toggled or checked state 207 - `LV_STATE_FOCUSED` Focused via keypad or encoder or clicked via touchpad/mouse 208 - `LV_STATE_FOCUS_KEY` Focused via keypad or encoder but not via touchpad/mouse 209 - `LV_STATE_EDITED` Edit by an encoder 210 - `LV_STATE_HOVERED` Hovered by mouse (not supported now) 211 - `LV_STATE_PRESSED` Being pressed 212 - `LV_STATE_SCROLLED` Being scrolled 213 - `LV_STATE_DISABLED` Disabled state 214 - `LV_STATE_USER_1` Custom state 215 - `LV_STATE_USER_2` Custom state 216 - `LV_STATE_USER_3` Custom state 217 - `LV_STATE_USER_4` Custom state 218 219 The states are usually automatically changed by the library as the user interacts with an object (presses, releases, focuses, etc.). 220 However, the states can be changed manually too. 221 To set or clear given state (but leave the other states untouched) use `lv_obj_add/clear_state(obj, LV_STATE_...)` 222 In both cases OR-ed state values can be used as well. E.g. `lv_obj_add_state(obj, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED)`. 223 224 To learn more about the states read the related section of the [Style overview](/overview/style). 225 226 ## Snapshot 227 A snapshot image can be generated for an object together with its children. Check details in [Snapshot](/others/snapshot).