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).