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

docs update some mroe widgets to v8 + fix links

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi
2021-05-03 17:32:57 +02:00
parent efc5bccbfd
commit 05252b7fe8
21 changed files with 143 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/conf.py
View File

@@ -43,7 +43,7 @@ extensions = ['sphinx.ext.autodoc',
'sphinx_markdown_tables',
'breathe',
'sphinx_sitemap',
'lv_example'
#'lv_example'
]
# Add any paths that contain templates here, relative to this directory.
@@ -76,7 +76,7 @@ author = 'The community of LVGL'
# The short X.Y version.
# embeddedt: extract using scripts/find_version.sh
version = "v10.1" #subprocess.run(["../scripts/find_version.sh"], capture_output=True).stdout.decode("utf-8").strip()
version = subprocess.run(["../scripts/find_version.sh"], capture_output=True).stdout.decode("utf-8").strip()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

29
docs/get-started/quick-overview.md
View File

@@ -172,36 +172,9 @@ You can select the theme to use in `lv_conf.h`.
## Examples
### Button with label
```eval_rst
.. image:: /lv_examples/src/lv_ex_get_started/lv_ex_get_started_1.*
:alt: Simple button with label with LVGL
.. literalinclude:: /lv_examples/src/lv_ex_get_started/lv_ex_get_started_1.c
:language: c
```
### Styling buttons
```eval_rst
.. image:: /lv_examples/src/lv_ex_get_started/lv_ex_get_started_2.*
:alt: Styling buttons with LVGL
.. literalinclude:: /lv_examples/src/lv_ex_get_started/lv_ex_get_started_2.c
:language: c
```
### Slider and alignment
```eval_rst
.. image:: /lv_examples/src/lv_ex_get_started/lv_ex_get_started_3.*
:alt: Create a slider with LVGL
.. literalinclude:: /lv_examples/src/lv_ex_get_started/lv_ex_get_started_3.c
:language: c
.. include:: ../../examples/get_started/index.rst
```
## Micropython

6
docs/index.md
View File

@@ -3,11 +3,6 @@
:github_url: |github_link_base|/index.md
```
```eval_rst
.. include:: /lang.rst
```
# Welcome to the documentation of LVGL!
<img src="_static/img/home_banner.jpg" style="width:100%">
@@ -32,6 +27,7 @@
porting/index
overview/index
widgets/index
layouts/index
contributing/index
```

6
docs/layouts/flex.md
View File

@@ -0,0 +1,6 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/layouts/flex.md
```
# Flex

6
docs/layouts/grid.md
View File

@@ -0,0 +1,6 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/layouts/grid.md
```
# Grid

15
docs/layouts/index.md
View File

@@ -0,0 +1,15 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/layouts/index.md
```
# Layouts
```eval_rst
.. toctree::
:maxdepth: 2
flex
grid
```

27
docs/overview/image.md
View File

@@ -319,24 +319,6 @@ To do this, use `lv_img_cache_invalidate_src(&my_png)`. If `NULL` is passed as a
## API
### Image decoder
```eval_rst
.. doxygenfile:: lv_img_decoder.h
:project: lvgl
```
### Image cache
```eval_rst
.. doxygenfile:: lv_img_cache.h
:project: lvgl
```
### Image buffer
@@ -346,12 +328,3 @@ To do this, use `lv_img_cache_invalidate_src(&my_png)`. If `NULL` is passed as a
:project: lvgl
```
### Image draw
```eval_rst
.. doxygenfile:: lv_draw_img.h
:project: lvgl
```

16
docs/overview/indev.md
View File

@@ -40,8 +40,8 @@ You can fully control the user interface without touchpad or mouse using a keypa
The objects, you want to control with keypad or encoder, needs to be added to a *Group*.
In every group, there is exactly one focused object which receives the pressed keys or the encoder actions.
For example, if a [Text area](/widgets/textarea) is focused and you press some letter on a keyboard, the keys will be sent and inserted into the text area.
Similarly, if a [Slider](/widgets/slider) is focused and you press the left or right arrows, the slider's value will be changed.
For example, if a [Text area](/widgets/core/textarea) is focused and you press some letter on a keyboard, the keys will be sent and inserted into the text area.
Similarly, if a [Slider](/widgets/core/slider) is focused and you press the left or right arrows, the slider's value will be changed.
You need to associate an input device with a group. An input device can send the keys to only one group but, a group can receive data from more than one input device too.
@@ -58,11 +58,11 @@ There are some predefined keys which have special meaning:
- **LV_KEY_DOWN** Decrease value or move downwards
- **LV_KEY_RIGHT** Increase value or move the the right
- **LV_KEY_LEFT** Decrease value or move the the left
- **LV_KEY_ESC** Close or exit (E.g. close a [Drop down list](/widgets/dropdown))
- **LV_KEY_DEL** Delete (E.g. a character on the right in a [Text area](/widgets/textarea))
- **LV_KEY_BACKSPACE** Delete a character on the left (E.g. in a [Text area](/widgets/textarea))
- **LV_KEY_HOME** Go to the beginning/top (E.g. in a [Text area](/widgets/textarea))
- **LV_KEY_END** Go to the end (E.g. in a [Text area](/widgets/textarea)))
- **LV_KEY_ESC** Close or exit (E.g. close a [Drop down list](/widgets/core/dropdown))
- **LV_KEY_DEL** Delete (E.g. a character on the right in a [Text area](/widgets/core/textarea))
- **LV_KEY_BACKSPACE** Delete a character on the left (E.g. in a [Text area](/widgets/core/textarea))
- **LV_KEY_HOME** Go to the beginning/top (E.g. in a [Text area](/widgets/core/textarea))
- **LV_KEY_END** Go to the end (E.g. in a [Text area](/widgets/core/textarea)))
The most important special keys are `LV_KEY_NEXT/PREV`, `LV_KEY_ENTER` and `LV_KEY_UP/DOWN/LEFT/RIGHT`.
In your `read_cb` function, you should translate some of your keys to these special keys to navigate in the group and interact with the selected object.
@@ -80,7 +80,7 @@ Pressing `LV_KEY_ENTER` will change to *Edit* mode.
In *Edit* mode, `LV_KEY_NEXT/PREV` is usually used to edit the object.
Depending on the object's type, a short or long press of `LV_KEY_ENTER` changes back to *Navigate* mode.
Usually, an object which can not be pressed (like a [Slider](/widgets/slider)) leaves *Edit* mode on short click. But with objects where short click has meaning (e.g. [Button](/widgets/btn)), a long press is required.
Usually, an object which can not be pressed (like a [Slider](/widgets/core/slider)) leaves *Edit* mode on short click. But with objects where short click has meaning (e.g. [Button](/widgets/core/btn)), a long press is required.
### Styling

7
docs/overview/new_widget.md
View File

@@ -0,0 +1,7 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/overview/new_widget.md
```
# New widget

4
docs/overview/object.md
View File

@@ -5,7 +5,7 @@
# Objects
In the LVGL the **basic building blocks** of a user interface are the objects, also called *Widgets*.
For example a [Button](/widgets/btn), [Label](/widgets/label), [Image](/widgets/img), [List](/widgets/list), [Chart](/widgets/chart) or [Text area](/widgets/textarea).
For example a [Button](/widgets/core/btn), [Label](/widgets/core/label), [Image](/widgets/core/img), [List](/widgets/core/list), [Chart](/widgets/extra/chart) or [Text area](/widgets/core/textarea).
Check all the [Object types](/widgets/index) here.
@@ -176,7 +176,7 @@ Visit [Multi-display support](/overview/display) to learn more.
## Parts
The widgets are built from multiple parts. For example a [Base object](/widgets/obj) uses the main and scroll bar parts but a [Slider](/widgets/slider) uses the main, the indicator and the knob parts.
The widgets are built from multiple parts. For example a [Base object](/widgets/obj) uses the main and scroll bar parts but a [Slider](/widgets/core/slider) uses the main, the indicator and the knob parts.
Parts are similar to *pseudo elements* in CSS.
The following predefined parts exist in LVGL:

2
docs/widgets/core/arc.md
View File

@@ -80,7 +80,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_arc/index.rst
.. include:: ../../../examples/widgets/arc/index.rst
```

2
docs/widgets/core/bar.md
View File

@@ -48,7 +48,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_bar/index.rst
.. include:: ../../../examples/widgets/bar/index.rst
```

2
docs/widgets/core/btn.md
View File

@@ -36,7 +36,7 @@ Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_btn/index.rst
.. include:: ../../../examples/widgets/btn/index.rst
```

4
docs/widgets/core/btnmatrix.md
View File

@@ -9,7 +9,7 @@
The Button Matrix objects can display multiple buttons in rows and columns.
The Button matrix object is very light weighted because the buttons are not created just virtually drawn on the fly.
This way, 1 button use only 8 extra bytes instead of the ~100-150 byte size of a normal [Button](/widgets/btn) object and other ~100 byte for the size of the [Label](/widgets/label) object.
This way, 1 button use only 8 extra bytes instead of the ~100-150 byte size of a normal [Button](/widgets/core/btn) object and other ~100 byte for the size of the [Label](/widgets/core/label) object.
The Button matrix is added to the deafult group (if it is set). Besides the Button matrix is an editable object to allow selecting and clicing the buttons with encoder navigation too.
@@ -82,7 +82,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_btnmatrix/index.rst
.. include:: ../../../examples/widgets/btnmatrix/index.rst
```

8
docs/widgets/core/canvas.md
View File

@@ -7,7 +7,7 @@
## Overview
A Canvas inherites from [Image](/widgets/img) where the user can draw anything.
A Canvas inherites from [Image](/widgets/core/img) where the user can draw anything.
Rectangles, texts, images, lines, arcs can be drawn here using lvgl's drawing engine.
Besides some "effects" can be applied as well like rotation, zoom and blur.
@@ -53,7 +53,7 @@ To draw something to the canvas use
`draw_dsc` is a `lv_draw_rect/label/img/line/arc_dsc_t` variable which should be first initialized with `lv_draw_rect/label/img/line/arc_dsc_init()` function and then it's filed should be modified with the desired colors and other values.
The draw function can draw to any color format. For example, it's possible to draw a text to an `LV_IMG_VF_ALPHA_8BIT` canvas and use the result image as a mask in [lv_objmask](/widgets/objmask) later.
The draw function can draw to any color format. For example, it's possible to draw a text to an `LV_IMG_VF_ALPHA_8BIT` canvas and use the result image as a [draw mask](/overview/drawing) later.
### Transformations
`lv_canvas_transform()` can be used to rotate and/or scale the image of an image and store the result on the canvas.
@@ -75,7 +75,7 @@ A given area of the canvas can be blurred horizontally with `lv_canvas_blur_hor(
`r` is the radius of the blur (greater value means more intensive burring). `area` is the area where the blur should be applied (interpreted relative to the canvas)
## Events
The same events are sent than for the [Images](/widgets/img).
The same events are sent than for the [Images](/widgets/core/img).
Learn more about [Events](/overview/event).
@@ -87,7 +87,7 @@ Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_canvas/index.rst
.. include:: ../../../examples/widgets/canvas/index.rst
```

61
docs/widgets/core/checkbox.md
View File

@@ -2,61 +2,54 @@
.. include:: /header.rst
:github_url: |github_link_base|/widgets/checkbox.md
```
# Checkbox (lv_cb)
# Checkbox (lv_checkbox)
## Overview
The Checkbox objects are built from a [Button](/widgets/btn) background which contains an also Button *bullet* and a [Label](/widgets/label) to realize a classical checkbox.
The Checkbox object is created from a "tick box" and a label.
When the Chackbox is clicked the tick box is toggled.
## Parts and Styles
The Check box's main part is called `LV_CHECKBOX_PART_BG`. It's a container for a "bullet" and a text next to it. The background uses all the typical background style properties.
The bullet is real [lv_obj](/widgets/obj) object and can be referred with `LV_CHECKBOX_PART_BULLET`.
The bullet automatically inherits the state of the background. So the background is pressed the bullet goes to pressed state as well.
The bullet also uses all the typical background style properties.
There is not dedicated part for the label. Its styles can be set in the background's styles because the *text* styles properties are always inherited.
- `LV_PART_MAIN` The is the background of the Checkbox and it uses the text and all the typical backround style properties.
`pad_column` adjusts the spacing between the tickbox and the label
- `LV_PART_INDICATOR` The "tick box" is a square the uses all the typical backround style properties.
By deafult its size is equal to the height of the main part's font. Padding properties makes the tick boy larger in the respectiev directions.
The Checkbox is added to the deafult group (if it is set).
## Usage
### Text
The text can be modified by the `lv_checkbox_set_text(cb, "New text")` function. It will dynamically allocate the text.
The text can be modified by the `lv_checkbox_set_text(cb, "New text")` function.
It will dynamically allocate the text.
To set a static text, use `lv_checkbox_set_static_text(cb, txt)`. This way, only a pointer of `txt` will be stored and it shouldn't be deallocated while the checkbox exists.
To set a static text,
use `lv_checkbox_set_static_text(cb, txt)`. This way, only a pointer of `txt` will be stored and it shouldn't be deallocated while the checkbox exists.
### Check/Uncheck
You can manually check / un-check the Checkbox via `lv_checkbox_set_checked(cb, true/false)`. Setting `true` will check the checkbox and `false` will un-check the checkbox.
### Disabled
To make the Checkbox disabled, use `lv_checkbox_set_disabled(cb, true)`.
### Get/Set Checkbox State
You can get the current state of the Checkbox with the `lv_checkbox_get_state(cb)` function which returns the current state.
You can set the current state of the Checkbox with the `lv_checkbox_set_state(cb, state)`.
The available states as defined by the enum `lv_btn_state_t` are:
- **LV_BTN_STATE_RELEASED**
- **LV_BTN_STATE_PRESSED**
- **LV_BTN_STATE_DISABLED**
- **LV_BTN_STATE_CHECKED_RELEASED**
- **LV_BTN_STATE_CHECKED_PRESSED**
- **LV_BTN_STATE_CHECKED_DISABLED**
### Check, uncheck, disable
You can manually check, un-check, and disable the Checkbox by using the common state state add/clear function:
```c
lv_obj_add_state(cb, LV_STATE_CHECKED); /*Make the chekbox checked*/
lv_obj_clear_state(cb, LV_STATE_CHECKED); /*MAke the checkbox unchecked*/
lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); /*Make the checkbox checked and disabled*/
```
## Events
Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Checkboxes:
- **LV_EVENT_VALUE_CHANGED** - sent when the checkbox is toggled.
Note that, the generic input device-related events (like `LV_EVENT_PRESSED`) are sent in the inactive state too. You need to check the state with `lv_cb_is_inactive(cb)` to ignore the events from inactive Checkboxes.
- `LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled.
- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for both main and indicator parts to allow hooking the drawing.
The for more detail on the main part see the [Base object](/widgets/obj#events)'s documentation.
For the indicator the following fields are used: `clip_area`, `draw_area`, `rect_dsc`, `part`.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the 'Buttons':
- **LV_KEY_RIGHT/UP** - Go to toggled state if toggling is enabled
- **LV_KEY_LEFT/DOWN** - Go to non-toggled state if toggling is enabled
- `LV_KEY_RIGHT/UP` Go to toggled state if toggling is enabled
- `LV_KEY_LEFT/DOWN` Go to non-toggled state if toggling is enabled
- `LV_KEY_ENTER` Clicks the checkbox and toggles it
Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
@@ -67,7 +60,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_checkbox/index.rst
.. include:: ../../../examples/widgets/checkbox/index.rst
```

64
docs/widgets/core/dropdown.md
View File

@@ -13,22 +13,31 @@ The drop-down list is closed by default and displays a single value or a predefi
When activated (by click on the drop-down list), a list is created from which the user may select one option.
When the user selects a new value, the list is deleted.
The Drop-down list is added to the deafult group (if it is set). Besides the Drop-down list is an editable object to allow selecting an option with encoder navigation too.
## Parts and Styles
The drop-down list's main part is called `LV_DROPDOWN_PART_MAIN` which is a simple [lv_obj](/widgets/obj) object.
It uses all the typical background properties. *Pressed*, *Focused*, *Edited* etc. stiles are also applied as usual.
The Dropdown widgets is built from the elements: a "button" and a "list" (they are not realted to the butto and list widgets)
The list, which is created when the main object is clicked, is an [Page](/widgets/page).
Its background part can be referenced with `LV_DROPDOWN_PART_LIST` and uses all the typical background properties for the rectangle itself and text properties for the options.
To adjust the space between the options use the *text_line_space* style property.
Padding values can be used to make some space on the edges.
### Button
- `LV_PART_MAIN` The background of the button. It uses the typicaly background proeprties and text proeprties for the text on it.
- `LV_PART_INDICATOR` Typically an arrow symbol that can be an image or a text (`LV_SYMBOL`).
The scrollable part of the page is hidden and its styles are always empty (so transparent with no padding).
The button goes to `LV_STATE_CHECKED` when its opened.
The scrollbar can be referenced with `LV_DROPDOWN_PART_SCRLBAR` and uses all the typical background properties.
### List
- `LV_PART_MAIN` The list itself and it uses the typical background proeprties. `max_height` can be used to limit the height of the list.
- `LV_PART_SCROLLBAR` The scrollbar the background, border, shadow properties and width (for its width) and right padding for the spacing on the right.
- `LV_PART_SELECTED` Refers to the currently pressed, checked or prssed+checked option.
It also uses the typical background properties.
The selected option can be referenced with `LV_DROPDOWN_PART_SELECTED` and uses all the typical background properties.
It will used in its default state to draw a rectangle on the selected option, and in pressed state to draw a rectangle on the being pressed option.
As the list not exists when the drop-down list is closed it's not possible to simply add styles to it.
Instead the following should be done:
1. Ad an event handler to the button for `LV_EVENT_VALUE_CHANGED` (triggered when the list is opened/closed)
2. Use `lv_obj_t * list = lv_dropdown_get_list(dropdown)`
3. `if(list != NULL) {/*Add the styles to the list*/}`
Alternatively the the theme can be extended with the new styles.
## Usage
## Overview
@@ -42,7 +51,7 @@ The `lv_dropdown_add_option(dropdown, "New option", pos)` function inserts a new
To save memory the options can set from a static(constant) string too with `lv_dropdown_set_static_options(dropdown, options)`.
In this case the options string should be alive while the drop-down list exists and `lv_dropdown_add_option` can't be used
You can select an option manually with `lv_dropdown_set_selected(dropdown, id)`, where _id_ is the index of an option.
You can select an option manually with `lv_dropdown_set_selected(dropdown, id)`, where `id` is the index of an option.
### Get selected option
The get the currently selected option, use `lv_dropdown_get_selected(dropdown)`. It will return the *index* of the selected option.
@@ -50,49 +59,40 @@ The get the currently selected option, use `lv_dropdown_get_selected(dropdown)`.
`lv_dropdown_get_selected_str(dropdown, buf, buf_size)` copies the name of the selected option to a `buf`.
### Direction
The list can be created on any side. The default `LV_DROPDOWN_DOWN` can be modified by `lv_dropdown_set_dir(dropdown, LV_DROPDOWN_DIR_LEFT/RIGHT/UP/DOWN)` function.
The list can be created on any side. The default `LV_DIR_BOTTOM` can be modified by `lv_dropdown_set_dir(dropdown, LV_DIR_LEFT/RIGHT/UP/BOTTOM)` function.
If the list would be vertically out of the screen, it will aligned to the edge.
### Symbol
A symbol (typically an arrow) can be added to the drop down list with `lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)`
If the direction of the drop-down list is `LV_DROPDOWN_DIR_LEFT` the symbol will be shown on the left, else on the right.
### Maximum height
The maximum height of drop-down list can be set via `lv_dropdown_set_max_height(dropdown, height)`. By default it's set to 3/4 vertical resolution.
If the direction of the drop-down list is `LV_DIR_LEFT` the symbol will be shown on the left, else on the right.
### Show selected
The main part can either show the selected option or a static text. It can controlled with `lv_dropdown_set_show_selected(sropdown, true/false)`.
The static text can be set with `lv_dropdown_set_text(dropdown, "Text")`. Only the pointer of the text is saved.
If you also don't want the selected option to be highlighted, a custom transparent style can be used for `LV_DROPDOWN_PART_SELECTED`.
### Animation time
The drop-down list's open/close animation time is adjusted by `lv_dropdown_set_anim_time(ddlist, anim_time)`. Zero animation time means no animation.
The main part can either show the selected option or a static text. If a static is set with `lv_dropdown_set_text(dropdown, "Some text")` it will be shown regardless to th selected option.
Id the text text is `NULL` the selected option is displayed on the button.
### Manually open/close
To manually open or close the drop-down list the `lv_dropdown_open/close(dropdown, LV_ANIM_ON/OFF)` function can be used.
To manually open or close the drop-down list the `lv_dropdown_open/close(dropdown)` function can be used.
## Events
Besides the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the drop-down list:
- **LV_EVENT_VALUE_CHANGED** - Sent when the new option is selected.
- `LV_EVENT_VALUE_CHANGED` Sent when the new option is selected or the list is opened/closed.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Buttons:
- **LV_KEY_RIGHT/DOWN** - Select the next option.
- **LV_KEY_LEFT/UP** - Select the previous option.
- **LY_KEY_ENTER** - Apply the selected option (Send `LV_EVENT_VALUE_CHANGED` event and close the drop-down list).
- `LV_KEY_RIGHT/DOWN` Select the next option.
- `LV_KEY_LEFT/UP` Select the previous option.
- `LY_KEY_ENTER` Apply the selected option (Send `LV_EVENT_VALUE_CHANGED` event and close the drop-down list).
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_dropdown/index.rst
.. include:: ../../../examples/widgets/dropdown/index.rst
```

49
docs/widgets/core/img.md
View File

@@ -7,13 +7,12 @@
## Overview
*Images* are the basic object to display from the flash (as arrays) or externally as files. Images can display symbols (`LV_SYMBOL_...`) too.
Images are the basic object to display images from the flash (as arrays) or externally as files. Images can display symbols (`LV_SYMBOL_...`) too.
Using the [Image decoder interface](/overview/image.html#image-decoder) custom image formats can be supported as well.
## Parts and Styles
The images has only a main part called `LV_IMG_PART_MAIN` which uses the typical background style propeties to draw a background rectangle and the *image* properties.
The padding values are used to make the background virtually larger. (It won't change the image's real size but the size modification is applied only during drawing)
- `LV_PART_MAIN` A background rectangle that uses the typical background style proeprties and the image itself using teh image style proeprties.
## Usage
@@ -26,49 +25,49 @@ To provide maximum flexibility, the source of the image can be:
To set the source of an image, use `lv_img_set_src(img, src)`.
To generate a **pixel array** from a PNG, JPG or BMP image, use the [Online image converter tool](https://lvgl.io/tools/imageconverter) and set the converted image with its pointer: `lv_img_set_src(img1, &converted_img_var);`
To generate a pixel array from a PNG, JPG or BMP image, use the [Online image converter tool](https://lvgl.io/tools/imageconverter) and set the converted image with its pointer: `lv_img_set_src(img1, &converted_img_var);`
To make the variable visible in the C file, you need to declare it with `LV_IMG_DECLARE(converted_img_var)`.
To use **external files**, you also need to convert the image files using the online converter tool but now you should select the binary Output format.
You also need to use LVGL's file system module and register a driver with some functions for the basic file operation. Got to the [File system](/overview/file-system) to learn more.
To use external files, you also need to convert the image files using the online converter tool but now you should select the binary output format.
You also need to use LVGL's file system module and register a driver with some functions for the basic file operation. Go to the [File system](/overview/file-system) to learn more.
To set an image sourced from a file, use `lv_img_set_src(img, "S:folder1/my_img.bin")`.
You can set a **symbol** similarly to [Labels](/widgets/label). In this case, the image will be rendered as text according to the *font* specified in the style. It enables to use of light-weighted mono-color
You can set a symbol similarly to [Labels](/widgets/core/label). In this case, the image will be rendered as text according to the *font* specified in the style. It enables to use of light-weighted mono-color
"letters" instead of real images. You can set symbol like `lv_img_set_src(img1, LV_SYMBOL_OK)`.
### Label as an image
Images and labels are sometimes used to convey the same thing. For example, to describe what a button does. Therefore, images and labels are somewhat interchangeable.
To handle these images can even display texts by using `LV_SYMBOL_DUMMY` as the prefix of the text. For example, `lv_img_set_src(img, LV_SYMBOL_DUMMY "Some text")`.
Images and labels are sometimes used to convey the same thing. For example, to describe what a button does.
Therefore, images and labels are somewhat interchangeable, that is the images can display texts by using `LV_SYMBOL_DUMMY` as the prefix of the text. For example, `lv_img_set_src(img, LV_SYMBOL_DUMMY "Some text")`.
### Transparency
The internal (variable) and external images support 2 transparency handling methods:
- **Chrome keying** - Pixels with `LV_COLOR_TRANSP` (*lv_conf.h*) color will be transparent.
- **Alpha byte** - An alpha byte is added to every pixel.
- **Chrome keying** - Pixels with `LV_COLOR_CHROMA_KEY` (*lv_conf.h*) color will be transparent.
- **Alpha byte** - An alpha byte is added to every pixel that contains the pixel's opacity
### Palette and Alpha index
Besides *True color* (RGB) color format, the following formats are also supported:
- **Indexed** - Image has a palette.
- **Alpha indexed** - Only alpha values are stored.
These options can be selected in the font converter. To learn more about the color formats, read the [Images](/overview/image) section.
These options can be selected in the image converter. To learn more about the color formats, read the [Images](/overview/image) section.
### Recolor
The images can be re-colored in run-time to any color according to the brightness of the pixels.
It is very useful to show different states (selected, inactive, pressed, etc.) of an image without storing more versions of the same image.
This feature can be enabled in the style by setting `img.intense` between `LV_OPA_TRANSP` (no recolor, value: 0) and `LV_OPA_COVER` (full recolor, value: 255).
A color can be mixed to every pixel of an image with a given intensity.
It is very useful to show different states (checked, inactive, pressed, etc.) of an image without storing more versions of the same image.
This feature can be enabled in the style by setting `img_recolor_opa` between `LV_OPA_TRANSP` (no recolor, value: 0) and `LV_OPA_COVER` (full recolor, value: 255).
The default value is `LV_OPA_TRANSP` so this feature is disabled.
The color to mix is set by `img_recolor`.
### Auto-size
It is possible to automatically set the size of the image object to the image source's width and height if enabled by the `lv_img_set_auto_size(image, true)` function.
If *auto-size* is enabled, then when a new file is set, the object size is automatically changed. Later, you can modify the size manually. The *auto-size* is enabled by default if the image is not a screen.
Is the width or height of the image object is set to `LV_SIZE_CONTENT` the obejct's size will be set according to the size of image source in the respective direction.
### Mosaic
If the object size is greater than the image size in any directions, then the image will be repeated like a mosaic.
If the object's size is greater than the image size in any directions, then the image will be repeated like a mosaic.
It's a very useful feature to create a large image from only a very narrow source.
For example, you can have a *300 x 1* image with a special gradient and set it as a wallpaper using the mosaic feature.
For example, you can have a *300 x 5* image with a special gradient and set it as a wallpaper using the mosaic feature.
### Offset
With `lv_img_set_offset_x(img, x_ofs)` and `lv_img_set_offset_y(img, y_ofs)`, you can add some offset to the displayed image.
@@ -83,6 +82,8 @@ Fractional scale works as well. E.g. `281` for 10% enlargement.
To rotate the image use `lv_img_set_angle(img, angle)`. Angle has 0.1 degree precision, so for 45.8° set 458.
The `transform_zoom` and `transform_angle` style proeprties are also used to determin the final zoom and angle.
By default, the pivot point of the rotation is the center of the image. It can be changed with `lv_img_set_pivot(img, pivot_x, pivot_y)`. `0;0` is the top left corner.
The quality of the transformation can be adjusted with `lv_img_set_antialias(img, true/false)`. With enabled anti-aliasing the transformations has a higher quality but they are slower.
@@ -92,12 +93,8 @@ In other words transformations work only on true color images stored as C array,
Note that, the real coordinates of image object won't change during transformation. That is `lv_obj_get_width/height/x/y()` will returned the original, non-zoomed coordinates.
## Rotate
The images can be rotated with
## Events
As by default, clicking of the image objects is disabled, only [generic](../overview/event.html#generic-events) non-input device-related events are sent.
If you want to catch all of the generic events of an image object, you should enable its clicking by using this: `lv_obj_set_click(img, true)`
No special events are sendt by the imge objects.
Learn more about [Events](/overview/event).
@@ -110,7 +107,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_img/index.rst
.. include:: ../../../examples/widgets/img/index.rst
```

1
docs/widgets/core/index.md
View File

@@ -23,6 +23,7 @@
slider
switch
table
textarea
```

11
docs/widgets/extra/textarea.md → docs/widgets/core/textarea.md
View File

@@ -6,13 +6,13 @@
## Overview
The Text Area is a [Page](/widgets/page) with a [Label](/widgets/label) and a cursor on it.
The Text Area is a Page with a [Label](/widgets/core/label) and a cursor on it.
Texts or characters can be added to it.
Long lines are wrapped and when the text becomes long enough the Text area can be scrolled.
## Parts and Styles
The Text area has the same parts as [Page](/widgets/page).
The Text area has the same parts as Page.
Expect `LV_PAGE_PART_SCRL` because it can't be referenced and it's always transparent.
Refer the Page's documentation of details.
@@ -100,17 +100,12 @@ Using `LV_LABEL_LONG_TXT_HINT` the scrolling and drawing will as fast as with "n
A part of text can be selected if enabled with `lv_textarea_set_text_sel(textarea, true)`.
It works like when you select a text on your PC with your mouse.
### Scrollbars
The scrollbars can shown according to different policies set by `lv_textarea_set_scrollbar_mode(textarea, LV_SCRLBAR_MODE_...)`.
Learn more at the [Page](/widgets/page) object.
### Scroll propagation
When the Text area is scrolled on an other scrollable object (like a Page) and the scrolling has reached the edge of the Text area, the scrolling can be propagated to the parent.
In other words, when the Text area can be scrolled further, the parent will be scrolled instead.
It can be enabled with `lv_ta_set_scroll_propagation(ta, true)`.
Learn more at the [Page](/widgets/page) object.
### Edge flash
When the Text area is scrolled to edge a circle like flash animation can be shown if it is enabled with `lv_ta_set_edge_flash(ta, true)`
@@ -133,7 +128,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_textarea/index.rst
.. include:: ../../../examples/widgets/textarea/index.rst
```

1
docs/widgets/extra/index.md
View File

@@ -21,7 +21,6 @@
spinbox
spinner
tabview
textarea
tileview
win
```