github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(object) update to v8

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi
2021-04-22 17:47:36 +02:00
parent d7735a486b
commit 21489eddc8
1 changed files with 70 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
docs/overview/object.md
View File

@@ -9,6 +9,8 @@ For example a [Button](/widgets/btn), [Label](/widgets/label), [Image](/widgets/
Check all the [Object types](/widgets/index) here.
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.
## Attributes
### Basic attributes
@@ -17,59 +19,56 @@ All object types share some basic attributes:
- Position
- Size
- Parent
- Drag enable
- Click enable etc.
- Styles
- Event handlers
- Etc
You can set/get these attributes with `lv_obj_set_...` and `lv_obj_get_...` functions. For example:
```c
/*Set basic object attributes*/
lv_obj_set_size(btn1, 100, 50); /*Button size*/
lv_obj_set_pos(btn1, 20,30); /*Button position*/
lv_obj_set_size(btn1, 100, 50); /*Set a button's size*/
lv_obj_set_pos(btn1, 20,30); /*Set a button's position*/
```
To see all the available functions visit the Base object's [documentation](/widgets/obj).
To see all the available functions visit the [Base object's documentation](/widgets/obj).
### Specific attributes
The object types have special attributes too. For example, a slider has
- Min. max. values
- Minimum and maximum values
- Current value
- Custom styles
For these attributes, every object type have unique API functions. For example for a slider:
```c
/*Set slider specific attributes*/
lv_slider_set_range(slider1, 0, 100); /*Set min. and max. values*/
lv_slider_set_value(slider1, 40, LV_ANIM_ON); /*Set the current value (position)*/
lv_slider_set_action(slider1, my_action); /*Set a callback function*/
lv_slider_set_range(slider1, 0, 100); /*Set the min. and max. values*/
lv_slider_set_value(slider1, 40, LV_ANIM_ON); /*Set the current value (position)*/
```
The API of the object types are described in their [Documentation](/widgets/index) but you can also check the respective header files (e.g. *lv_objx/lv_slider.h*)
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*)
## Working mechanisms
### Parent-child structure
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 an unlimited number of children.
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.
There is no limitation for the type of the parent but, there are typical parent (e.g. button) and typical child (e.g. label) objects.
### Moving together
If the position of the parent is changed the children will move with the parent.
If the position of the parent changes the children will move with the parent.
Therefore all positions are relative to the parent.
The (0;0) coordinates mean the objects will remain in the top left-hand corner of the parent independently from the position of the parent.
![](/misc/par_child1.png "Objects are moving together 1")
```c
lv_obj_t * par = lv_obj_create(lv_scr_act(), NULL); /*Create a parent object on the current screen*/
lv_obj_set_size(par, 100, 80); /*Set the size of the parent*/
lv_obj_t * parent = lv_obj_create(lv_scr_act()); /*Create a parent object on the current screen*/
lv_obj_set_size(parent, 100, 80); /*Set the size of the parent*/
lv_obj_t * obj1 = lv_obj_create(par, NULL); /*Create an object on the previously created parent object*/
lv_obj_set_pos(obj1, 10, 10); /*Set the position of the new object*/
lv_obj_t * obj1 = lv_obj_create(parent); /*Create an object on the previously created parent object*/
lv_obj_set_pos(obj1, 10, 10); /*Set the position of the new object*/
```
Modify the position of the parent:
@@ -77,7 +76,7 @@ Modify the position of the parent:
![](/misc/par_child2.png "Graphical objects are moving together 2")
```c
lv_obj_set_pos(par, 50, 50); /*Move the parent. The child will move with it.*/
lv_obj_set_pos(parent, 50, 50); /*Move the parent. The child will move with it.*/
```
(For simplicity the adjusting of colors of the objects is not shown in the example.)
@@ -89,28 +88,27 @@ If a child is partially or fully out of its parent then the parts outside will n
![](/misc/par_child3.png "A graphical object is visible on its parent")
```c
lv_obj_set_x(obj1, -30); /*Move the child a little bit of the parent*/
lv_obj_set_x(obj1, -30); /*Move the child a little bit off the parent*/
```
### Create - delete objects
### Create and delete objects
In LVGL objects can be created and deleted dynamically in run-time.
It means only the currently created objects consume RAM.
For example, if you need a chart, you can create it when required and delete it when it is not visible or necessary.
In LVGL objects can be created and deleted dynamically in run time. It means only the currently created (exisiting) objects consume RAM.
Every object type has its own **create** function with a unified prototype.
It needs two parameters:
- A pointer to the *parent* object. To create a screen give *NULL* as parent.
- Optionally, a pointer to *copy* object with the same type to copy it. This *copy* object can be *NULL* to avoid the copy operation.
All objects are referenced in C code using an `lv_obj_t` pointer as a handle. This pointer can later be used to set or get the attributes of the object.
The create functions look like this:
It allows to create a screen just when a button is clicked to open it. A delete the screen when a new screen is loaded.
Or the UI can be created based on the current enviroment of the device. For example create meter, charts, bars, slider etc according to the currently attached sensors.
Every widget has its own **create** function with a protype like this:
```c
lv_obj_t * lv_ <type>_create(lv_obj_t * parent, lv_obj_t * copy);
lv_obj_t * lv_<widget>_create(lv_obj_t * parent, <other paramaters if any>);
```
In most of the cases the create functions have only a *parent* paramter that tells on which object create the new widget.
The return value is a poinr to the created oject with `lv_obj_t *` type.
There is a common **delete** function for all object types. It deletes the object and all of its children.
```c
@@ -118,27 +116,24 @@ void lv_obj_del(lv_obj_t * obj);
```
`lv_obj_del` will delete the object immediately.
If for any reason you can't delete the object immediately you can use `lv_obj_del_async(obj)`.
If for any reason you can't delete the object immediately you can use `lv_obj_del_async(obj)` that will perefome the deletion on hte next call of `lv_timer_handler()`.
It is useful e.g. if you want to delete the parent of an object in the child's `LV_EVENT_DELETE` signal.
You can remove all the children of an object (but not the object itself) using `lv_obj_clean`:
You can remove all the children of an object (but not the object itself) using `lv_obj_clean(obj)`.
```c
void lv_obj_clean(lv_obj_t * obj);
```
## Screens
### Create screens
The screens are special objects which have no parent object. So they can be created like:
```c
lv_obj_t * scr1 = lv_obj_create(NULL, NULL);
lv_obj_t * scr1 = lv_obj_create(NULL);
```
Screens can be created with any object type. For example, a [Base object](/widgets/obj) or an image to make a wallpaper.
### Get the active screen
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.
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.
To get the currently active screen use the `lv_scr_act()` function.
@@ -149,9 +144,9 @@ To load a new screen, use `lv_scr_load(scr1)`.
#### Load screen with animation
A new screen can be loaded with animation too using `lv_scr_load_anim(scr, transition_type, time, delay, auto_del)`. The following transition types exist:
- `LV_SCR_LOAD_ANIM_NONE`: switch immediately after `delay` ms
- `LV_SCR_LOAD_ANIM_OVER_LEFT/RIGHT/TOP/BOTTOM` move the new screen over the other towards the given direction
- `LV_SCR_LOAD_ANIM_MOVE_LEFT/RIGHT/TOP/BOTTOM` move both the old and new screens towards the given direction
- `LV_SCR_LOAD_ANIM_NONE`: switch immediately after `delay` milliseconds
- `LV_SCR_LOAD_ANIM_OVER_LEFT/RIGHT/TOP/BOTTOM` move the new screen over the current towards the given direction
- `LV_SCR_LOAD_ANIM_MOVE_LEFT/RIGHT/TOP/BOTTOM` move both the current and new screens towards the given direction
- `LV_SCR_LOAD_ANIM_FADE_ON` fade the new screen over the old screen
Setting `auto_del` to `true` will automatically delete the old screen when the animation is finished.
@@ -168,28 +163,43 @@ Visit [Multi-display support](/overview/display) to learn more.
## Parts
The widgets can have multiple parts. For example a [Button](/widgets/btn) has only a main part but a [Slider](/widgets/slider) is built from a background, an indicator and a knob.
The widgets are built from multiple parts. For example a [Base object](/widgets/obj) uses the main aand scrollbar parts but a [Slider](/widgets/slider) uses the main, the indicator and the knob parts.
Parts are similar to *pseudo elements* in CSS.
The name of the parts is constructed like `LV_ + <TYPE> _PART_ <NAME>`. For example `LV_BTN_PART_MAIN` or `LV_SLIDER_PART_KNOB`. The parts are usually used when styles are add to the objects.
Using parts different styles can be assigned to the different parts of the objects.
To learn more about the parts read the related section of the [Style overview](/overview/style#parts).
The following predefined parts exist in LVGL:
- `LV_PART_MAIN` A background like rectangle*/
- `LV_PART_SCROLLBAR` The scrollbar(s)
- `LV_PART_INDICATOR` Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox
- `LV_PART_KNOB` Like a handle to grab to adjust the value*/
- `LV_PART_SELECTED` Indicate the currently selected option or section
- `LV_PART_ITEMS` Used if the widget has multiple similar elements (e.g. tabel cells)*/
- `LV_PART_TICKS` Ticks on scales e.g. for a chart or meter
- `LV_PART_CURSOR` Mark a specific place e.g. text area's or chart's cursor
- `LV_PART_CUSTOM_FIRST` Custom parts can be added from here.
The main purpose of parts to allow styleing the "components" of the widgets.
Therefore the parts are described in more dteal in the [Style overview](/overview/style) section.
## States
The object can be in a combinations of the following states:
- **LV_STATE_DEFAULT** Normal, released
- **LV_STATE_CHECKED** Toggled or checked
- **LV_STATE_FOCUSED** Focused via keypad or encoder or clicked via touchpad/mouse
- **LV_STATE_EDITED**  Edit by an encoder
- **LV_STATE_HOVERED** Hovered by mouse (not supported now)
- **LV_STATE_PRESSED** Pressed
- **LV_STATE_DISABLED** Disabled or inactive
- `LV_STATE_DEFAULT` Normal, released state
- `LV_STATE_CHECKED` Toggled or checked state
- `LV_STATE_FOCUSED` Focused via keypad or encoder or clicked via touchpad/mouse
- `LV_STATE_FOCUS_KEY` Focused via keypad or encoder but not via touchpad/mouse
- `LV_STATE_EDITED` Edit by an encoder
- `LV_STATE_HOVERED` Hovered by mouse (not supported now)
- `LV_STATE_PRESSED` Being pressed
- `LV_STATE_SCROLLED` Being scrolled
- `LV_STATE_DISABLED` Disabled state
- `LV_STATE_USER_1` Custom state
- `LV_STATE_USER_2` Custom state
- `LV_STATE_USER_3` Custom state
- `LV_STATE_USER_4` Custom state
The states are usually automatically changed by the library as the user presses, releases, focuses etc an object.
However, the states can be changed manually too. To completely overwrite the current state use `lv_obj_set_state(obj, part, LV_STATE...)`.
To set or clear given state (but leave to other states untouched) use `lv_obj_add/clear_state(obj, part, LV_STATE_...)`
In both cases ORed state values can be used as well. E.g. `lv_obj_set_state(obj, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED)`.
However, the states can be changed manually too.
To set or clear given state (but leave the other states untouched) use `lv_obj_add/clear_state(obj, LV_STATE_...)`
In both cases ORed state values can be used as well. E.g. `lv_obj_add_state(obj, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED)`.
To learn more about the states read the related section of the [Style overview](/overview/style#states).
To learn more about the states read the related section of the [Style overview](/overview/style).