MightyPork/tangara-fw
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update LVGL to v9.1.0

Browse Source
This commit is contained in:
jacqueline
2024-06-12 17:54:40 +10:00
parent 611176ed66
commit 64bd9053a2
2244 changed files with 278442 additions and 118864 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/lvgl/docs/others/file_explorer.rst
+115
View File
@@ -0,0 +1,115 @@
.. _file_explorer:
=============
File Explorer
=============
``lv_file_explorer`` provides an API to browse the contents of the file
system. ``lv_file_explorer`` only provides the file browsing function,
but does not provide the actual file operation function. In other words,
you can't click a picture file to open and view the picture like a PC.
``lv_file_explorer`` will tell you the full path and name of the
currently clicked file. The file operation function needs to be
implemented by the user.
The file list in ``lv_file_explorer`` is based on
:ref:`lv_table`, and the quick access bar is based on
:ref:`lv_list`. Therefore, care should be taken to ensure
that :ref:`lv_table` and :ref:`lv_list` are
enabled.
.. _file_explorer_usage:
Usage
-----
Enable :c:macro:`LV_USE_FILE_EXPLORER` in ``lv_conf.h``.
First use :cpp:expr:`lv_file_explorer_create(lv_screen_active())` to create a file
explorer, The default size is the screen size. After that, you can
customize the style like widget.
Quick access
~~~~~~~~~~~~
The quick access bar is optional. You can turn off
:c:macro:`LV_FILE_EXPLORER_QUICK_ACCESS` in ``lv_conf.h`` so that the quick
access bar will not be created. This can save some memory, but not much.
After the quick access bar is created, it can be hidden by clicking the
button at the top left corner of the browsing area, which is very useful
for small screen devices.
You can use
:cpp:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")`
to set the path of the quick access bar. The items of the quick access
bar are fixed. Currently, there are the following items:
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_HOME`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_MUSIC`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_PICTURES`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_VIDEO`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_DOCS`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_MNT`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_FS`
.. _file_explorer_sort:
Sort
~~~~
You can use
:cpp:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` to set
sorting method.
There are the following sorting methods:
- :cpp:enumerator:`LV_EXPLORER_SORT_NONE`
- :cpp:enumerator:`LV_EXPLORER_SORT_KIND`
You can customize the sorting. Before custom sort, please set the
default sorting to :cpp:enumerator:`LV_EXPLORER_SORT_NONE`. The default is
:cpp:enumerator:`LV_EXPLORER_SORT_NONE`.
.. _file_explorer_events:
Events
------
- :cpp:enumerator:`LV_EVENT_READY` Sent when a directory is opened. You can customize
the sort.
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when an item (file) in the file list
is clicked.
You can use :cpp:func:`lv_file_explorer_get_cur_path` to get the current path
and :cpp:func:`lv_file_explorer_get_sel_fn` to get the name of the currently
selected file in the event processing function. For example:
.. code:: c
static void file_explorer_event_handler(lv_event_t * e)
{
lv_event_code_t code = lv_event_get_code(e);
lv_obj_t * obj = lv_event_get_target(e);
if(code == LV_EVENT_VALUE_CHANGED) {
char * cur_path = lv_file_explorer_get_cur_path(obj);
char * sel_fn = lv_file_explorer_get_sel_fn(obj);
LV_LOG_USER("%s%s", cur_path, sel_fn);
}
}
You can also save the obtained **path** and **file** name into an array
through functions such as :cpp:func:`strcpy` and :cpp:func:`strcat` for later use.
.. _file_explorer_example:
Example
-------
.. include:: ../examples/others/file_explorer/index.rst
.. _file_explorer_api:
API
---
lib/lvgl/docs/others/fragment.md
-77
View File
@@ -1,77 +0,0 @@
# Fragment
Fragment is a concept copied from [Android](https://developer.android.com/guide/fragments).
It represents a reusable portion of your app's UI. A fragment defines and manages its own layout, has its own lifecycle,
and can handle its own events. Like Android's Fragment that must be hosted by an activity or another fragment, Fragment
in LVGL needs to be hosted by an object, or another fragment. The fragment’s view hierarchy becomes part of, or attaches
to, the host’s view hierarchy.
Such concept also has some similarities
to [UiViewController on iOS](https://developer.apple.com/documentation/uikit/uiviewcontroller).
Fragment Manager is a manager holding references to fragments attached to it, and has an internal stack to achieve
navigation. You can use fragment manager to build navigation stack, or multi pane application easily.
## Usage
Enable `LV_USE_FRAGMENT` in `lv_conf.h`.
### Create Fragment Class
```c
struct sample_fragment_t {
/* IMPORTANT: don't miss this part */
lv_fragment_t base;
/* States, object references and data fields for this fragment */
const char *title;
};
const lv_fragment_class_t sample_cls = {
/* Initialize something needed */
.constructor_cb = sample_fragment_ctor,
/* Create view objects */
.create_obj_cb = sample_fragment_create_obj,
/* IMPORTANT: size of your fragment struct */
.instance_size = sizeof(struct sample_fragment_t)
};
```
### Use `lv_fragment_manager`
```c
/* Create fragment instance, and objects will be added to container */
lv_fragment_manager_t *manager = lv_fragment_manager_create(container, NULL);
/* Replace current fragment with instance of sample_cls, and init_argument is user defined pointer */
lv_fragment_manager_replace(manager, &sample_cls, init_argument);
```
### Fragment Based Navigation
```c
/* Add one instance into manager stack. View object of current fragment will be destroyed,
* but instances created in class constructor will be kept.
*/
lv_fragment_manager_push(manager, &sample_cls, NULL);
/* Remove the top most fragment from the stack, and bring back previous one. */
lv_fragment_manager_pop(manager);
```
## Example
```eval_rst
.. include:: ../../examples/others/fragment/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_fragment.h
:project: lvgl
```
lib/lvgl/docs/others/fragment.rst
+86
View File
@@ -0,0 +1,86 @@
.. _fragment:
========
Fragment
========
Fragment is a concept copied from
`Android <https://developer.android.com/guide/fragments>`__.
It represents a reusable portion of your app's UI. A fragment defines
and manages its own layout, has its own lifecycle, and can handle its
own events. Like Android's Fragment that must be hosted by an activity
or another fragment, Fragment in LVGL needs to be hosted by an object,
or another fragment. The fragment's view hierarchy becomes part of, or
attaches to, the host's view hierarchy.
Such concept also has some similarities to `UiViewController on
iOS <https://developer.apple.com/documentation/uikit/uiviewcontroller>`__.
Fragment Manager is a manager holding references to fragments attached
to it, and has an internal stack to achieve navigation. You can use
fragment manager to build navigation stack, or multi pane application
easily.
.. _fragment_usage:
Usage
-----
Enable :c:macro:`LV_USE_FRAGMENT` in ``lv_conf.h``.
Create Fragment Class
~~~~~~~~~~~~~~~~~~~~~
.. code:: c
struct sample_fragment_t {
/* IMPORTANT: don't miss this part */
lv_fragment_t base;
/* States, object references and data fields for this fragment */
const char *title;
};
const lv_fragment_class_t sample_cls = {
/* Initialize something needed */
.constructor_cb = sample_fragment_ctor,
/* Create view objects */
.create_obj_cb = sample_fragment_create_obj,
/* IMPORTANT: size of your fragment struct */
.instance_size = sizeof(struct sample_fragment_t),
};
Use ``lv_fragment_manager``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: c
/* Create fragment instance, and objects will be added to container */
lv_fragment_manager_t *manager = lv_fragment_manager_create(container, NULL);
/* Replace current fragment with instance of sample_cls, and init_argument is user defined pointer */
lv_fragment_manager_replace(manager, &sample_cls, init_argument);
Fragment Based Navigation
~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: c
/* Add one instance into manager stack. View object of current fragment will be destroyed,
* but instances created in class constructor will be kept.
*/
lv_fragment_manager_push(manager, &sample_cls, NULL);
/* Remove the top most fragment from the stack, and bring back previous one. */
lv_fragment_manager_pop(manager);
.. _fragment_example:
Example
-------
.. include:: ../examples/others/fragment/index.rst
.. _fragment_api:
API
---
lib/lvgl/docs/others/gridnav.md
-56
View File
@@ -1,56 +0,0 @@
# Grid navigation
Grid navigation (gridnav for short) is a feature that changes the currently focused child object as arrow keys are pressed.
If the children are arranged into a grid-like layout then the up, down, left and right arrows move focus to the nearest sibling
in the respective direction.
It doesn't matter how the children are positioned, as only the current x and y coordinates are considered.
This means that gridnav works with manually positioned children, as well as [Flex](/layouts/flex) and [Grid](/layouts/grid) layouts.
Gridnav also works if the children are arranged into a single row or column.
That makes it useful, for example, to simplify navigation on a [List widget](/widgets/extra/list).
Gridnav assumes that the object to which gridnav is added is part of a [group](/overview/indev.html#groups).
This way, if the object with gridnav is focused, the arrow key presses are automatically forwarded to the object
so that gridnav can process the arrow keys.
To move the focus to the next widget of the group use `LV_KEY_NEXT/PREV` or `lv_group_focus_next/prev()` or the `TAB` key on keyboard as usual.
If the container is scrollable and the focused child is out of the view, gridnav will automatically scroll the child into view.
## Usage
To add the gridnav feature to an object use `lv_gridnav_add(cont, flags)`.
`flags` control the behavior of gridnav:
- `LV_GRIDNAV_CTRL_NONE` Default settings
- `LV_GRIDNAV_CTRL_ROLLOVER` If there is no next/previous object in a direction,
the focus goes to the object in the next/previous row (on left/right keys) or first/last row (on up/down keys
- `LV_GRIDNAV_CTRL_SCROLL_FIRST` If an arrow is pressed and the focused object can be scrolled in that direction
then it will be scrolled instead of going to the next/previous object. If there is no more room for scrolling the next/previous object will be focused normally
`lv_gridnav_remove(cont)` Removes gridnav from an object.
## Focusable objects
An object needs to be clickable or click focusable (`LV_OBJ_FLAG_CLICKABLE` or `LV_OBJ_FLAG_CLICK_FOCUSABLE`)
and not hidden (`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav.
## Example
```eval_rst
.. include:: ../../examples/others/gridnav/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_gridnav.h
:project: lvgl
```
lib/lvgl/docs/others/gridnav.rst
+76
View File
@@ -0,0 +1,76 @@
.. _gridnav:
===============
Grid navigation
===============
Grid navigation (gridnav for short) is a feature that changes the
currently focused child object as arrow keys are pressed.
If the children are arranged into a grid-like layout then the up, down,
left and right arrows move focus to the nearest sibling in the
respective direction.
It doesn't matter how the children are positioned, as only the current x
and y coordinates are considered. This means that gridnav works with
manually positioned children, as well as :ref:`flex` and
:ref:`grid` layouts.
Gridnav also works if the children are arranged into a single row or
column. That makes it useful, for example, to simplify navigation on a
:ref:`List widget <lv_list>`.
Gridnav assumes that the object to which gridnav is added is part of a
:ref:`group <indev_groups>`. This way, if the object with
gridnav is focused, the arrow key presses are automatically forwarded to
the object so that gridnav can process the arrow keys.
To move the focus to the next widget of the group use
:cpp:enumerator:`LV_KEY_NEXT` or :cpp:enumerator:`LV_KEY_PREV`.
Optionally you can also use :cpp:func:`lv_group_focus_next`
or :cpp:func:`lv_group_focus_prev` or the ``TAB``
key on keyboard as usual.
If the container is scrollable and the focused child is out of the view,
gridnav will automatically scroll the child into view.
.. _gridnav_usage:
Usage
-----
To add the gridnav feature to an object use
:cpp:expr:`lv_gridnav_add(cont, flags)`.
``flags`` control the behavior of gridnav:
- :cpp:enumerator:`LV_GRIDNAV_CTRL_NONE`: Default settings
- :cpp:enumerator:`LV_GRIDNAV_CTRL_ROLLOVER`: If there is no next/previous object in a
direction, the focus goes to the object in the next/previous row (on
left/right keys) or first/last row (on up/down keys)
- :cpp:enumerator:`LV_GRIDNAV_CTRL_SCROLL_FIRST`: If an arrow is pressed and the focused
object can be scrolled in that direction then it will be scrolled instead of
going to the next/previous object. If there is no more room for scrolling the
next/previous object will be focused normally
:cpp:expr:`lv_gridnav_remove(cont)` Removes gridnav from an object.
Focusable objects
-----------------
An object needs to be clickable or click focusable
(:cpp:enumerator:`LV_OBJ_FLAG_CLICKABLE` or :cpp:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE`) and not
hidden (:cpp:enumerator:`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav.
.. _gridnav_example:
Example
-------
.. include:: ../examples/others/gridnav/index.rst
.. _gridnav_api:
API
---
lib/lvgl/docs/others/ime_pinyin.md
-150
View File
@@ -1,150 +0,0 @@
# Pinyin IME
Pinyin IME provides API to provide Chinese Pinyin input method (Chinese input) for keyboard object, which supports 26 key and 9 key input modes. You can think of `lv_ime_pinyin` as a Pinyin input method plug-in for keyboard objects.
Normally, an environment where [lv_keyboard](/widgets/extra/keyboard) can run can also run `lv_ime_pinyin`. There are two main influencing factors: the size of the font file and the size of the dictionary.
<details>
<summary>中文</summary>
<p>
`lv_ime_pinyin`为[键盘](/widgets/extra/keyboard)组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)，支持26键和9键输入模式。您可以将 `lv_ime_pinyin` 看成是键盘组件的汉语拼音输入法插件。
一般情况下，只要是[键盘](/widgets/extra/keyboard)组件能运行的环境 `lv_ime_pinyin` 也能运行。有两个影响因素：字库的大小和词库的大小。
</p>
</details>
## Usage
Enable `LV_USE_IME_PINYIN` in `lv_conf.h`.
First use `lv_ime_pinyin_create(lv_scr_act())` to create a Pinyin input method plug-in, then use `lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the `keyboard` you created to the Pinyin input method plug-in.
You can use `lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` to use a custom dictionary (if you don't want to use the built-in dictionary at first, you can disable `LV_IME_PINYIN_USE_DEFAULT_DICT` in `lv_conf.h`, which can save a lot of memory space).
The built-in thesaurus is customized based on the **LV_FONT_SIMSUN_16_CJK** font library, which currently only has more than `1,000` most common CJK radicals, so it is recommended to use custom fonts and thesaurus.
In the process of using the Pinyin input method plug-in, you can change the keyboard and dictionary at any time.
<details>
<summary>中文</summary>
<p>
在 `lv_conf.h` 中打开 `LV_USE_IME_PINYIN`。
首先，使用 `lv_ime_pinyin_create(lv_scr_act())` 函数创建一个拼音输入法插件，
然后使用 `lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` 函数将您创建的键盘组件添加到插件中。
内置的词库是基于 LVGL 的 **LV_FONT_SIMSUN_16_CJK** 字库定制，这个字库目前只有 `1000` 多个最常见的 CJK 部首，所以建议使用自定义字库和词库。
您可以使用 `lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` 函数来设置使用自定义的词库，如果您一开始就不打算使用内置的词库，建议您在 `lv_conf.h` 中将 `LV_IME_PINYIN_USE_DEFAULT_DICT` 关闭，这可以节省一些内存空间。
</p>
</details>
## Custom dictionary
If you don't want to use the built-in Pinyin dictionary, you can use the custom dictionary.
Or if you think that the built-in phonetic dictionary consumes a lot of memory, you can also use a custom dictionary.
Customizing the dictionary is very simple.
First, set `LV_IME_PINYIN_USE_DEFAULT_DICT` to `0` in `lv_conf.h`
Then, write a dictionary in the following format.
<details>
<summary>中文</summary>
<p>
如果您不想使用内置的词库，可以通过下面的方法自定义词库。
自定义词典非常简单。
首先，在 `lv_conf.h` 将 `LV_IME_PINYIN_USE_DEFAULT_DICT` 设置为 0。
然后按照下面的格式编写词库。
</p>
</details>
### Dictionary format
The arrangement order of each pinyin syllable is very important. You need to customize your own thesaurus according to the Hanyu Pinyin syllable table. You can read [here](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981) to learn about the Hanyu Pinyin syllables and the syllable table.
Then, write your own dictionary according to the following format:
<details>
<summary>中文</summary>
<p>
**注意**，各个拼音音节的排列顺序非常重要，您需要按照汉语拼音音节表定制自己的词库，可以阅读[这里](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981)了解[汉语拼音音节](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981)以及[音节表](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981#1)。
然后，根据下面的格式编写自己的词库：
</p>
</details>
```c
lv_100ask_pinyin_dict_t your_pinyin_dict[] = {
{ "a", "啊阿呵吖" },
{ "ai", "埃挨哎唉哀皑蔼矮碍爱隘癌艾" },
{ "an", "按安暗岸俺案鞍氨胺厂广庵揞犴铵桉谙鹌埯黯" },
{ "ang", "昂肮盎仰" },
{ "ao", "凹敖熬翱袄傲奥懊澳" },
{ "ba", "芭捌叭吧笆八疤巴拔跋靶把坝霸罢爸扒耙" },
{ "bai", "白摆佰败拜柏百稗伯" },
/* ...... */
{ "zuo", "昨左佐做作坐座撮琢柞"},
{NULL, NULL}
```
**The last item** must end with `{null, null}` , or it will not work properly.
### Apply new dictionary
After writing a dictionary according to the above dictionary format, you only need to call this function to set up and use your dictionary:
<details>
<summary>中文</summary>
<p>
按照上面的词库格式编写好自己的词库之后，参考下面的用法，调用 `lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict)` 函数即可设置和使用新词库：
</p>
</details>
```c
lv_obj_t * pinyin_ime = lv_100ask_pinyin_ime_create(lv_scr_act());
lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict);
```
## Input modes
`lv_ime_pinyin` supports 26 key and 9 key input modes. The mode switching is very simple, just call the function `lv_ime_pinyin_set_mode`. If the second parameter of function `lv_ime_pinyin_set_mode` is' 1 ', switch to 26 key input mode; if it is' 0', switch to 9 key input mode, and the default is' 1 '.
<details>
<summary>中文</summary>
<p>
`lv_ime_pinyin` 支持26键和9键输入模式。模式的切换非常简单，只需调用函数 `lv_ime_pinyin_set_mode` 即可。如果函数 `lv_ime_pinyin_set_mode` 的第2个参数为 `1` 则切换到 26 键输入模式，如果为 `0` 则切换到 9 键输入法模式，默认为 `1` 。
</p>
</details>
## Example
```eval_rst
.. include:: ../../examples/others/ime/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_ime_pinyin.h
:project: lvgl
```
lib/lvgl/docs/others/ime_pinyin.rst
+122
View File
@@ -0,0 +1,122 @@
.. _ime_pinyin:
==========
Pinyin IME
==========
Pinyin IME provides API to provide Chinese Pinyin input method (Chinese
input) for keyboard object, which supports 26 key and 9 key input modes.
You can think of ``lv_ime_pinyin`` as a Pinyin input method plug-in for
keyboard objects.
Normally, an environment where :ref:`lv_keyboard` can
run can also run ``lv_ime_pinyin``. There are two main influencing
factors: the size of the font file and the size of the dictionary.
.. _ime_pinyin_example:
Usage
-----
Enable :c:macro:`LV_USE_IME_PINYIN` in ``lv_conf.h``.
First use :cpp:expr:`lv_ime_pinyin_create(lv_screen_active())` to create a Pinyin
input method plug-in, then use
:cpp:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the ``keyboard``
you created to the Pinyin input method plug-in. You can use
:cpp:expr:`lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` to use a custom
dictionary (if you don't want to use the built-in dictionary at first,
you can disable :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` in ``lv_conf.h``,
which can save a lot of memory space).
The built-in thesaurus is customized based on the
**LV_FONT_SIMSUN_16_CJK** font library, which currently only has more
than ``1,000`` most common CJK radicals, so it is recommended to use
custom fonts and thesaurus.
In the process of using the Pinyin input method plug-in, you can change
the keyboard and dictionary at any time.
Custom dictionary
-----------------
If you don't want to use the built-in Pinyin dictionary, you can use the
custom dictionary. Or if you think that the built-in phonetic dictionary
consumes a lot of memory, you can also use a custom dictionary.
Customizing the dictionary is very simple.
First, set :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` to ``0`` in ``lv_conf.h``
Then, write a dictionary in the following format.
Dictionary format
~~~~~~~~~~~~~~~~~
The arrangement order of each pinyin syllable is very important. You
need to customize your own thesaurus according to the Hanyu Pinyin
syllable table. You can read
`here <https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981>`__
to learn about the Hanyu Pinyin syllables and the syllable table.
Then, write your own dictionary according to the following format:
.. code:: c
lv_100ask_pinyin_dict_t your_pinyin_dict[] = {
{ "a", "啊阿呵吖" },
{ "ai", "埃挨哎唉哀皑蔼矮碍爱隘癌艾" },
{ "an", "按安暗岸俺案鞍氨胺厂广庵揞犴铵桉谙鹌埯黯" },
{ "ang", "昂肮盎仰" },
{ "ao", "凹敖熬翱袄傲奥懊澳" },
{ "ba", "芭捌叭吧笆八疤巴拔跋靶把坝霸罢爸扒耙" },
{ "bai", "白摆佰败拜柏百稗伯" },
/* ...... */
{ "zuo", "昨左佐做作坐座撮琢柞"},
{NULL, NULL}
**The last item** must end with ``{null, null}``, or it will not work
properly.
.. _ime_pinyin_apply_new_dictionary:
Apply new dictionary
~~~~~~~~~~~~~~~~~~~~
After writing a dictionary according to the above dictionary format, you
only need to call this function to set up and use your dictionary:
.. code:: c
lv_obj_t * pinyin_ime = lv_100ask_pinyin_ime_create(lv_screen_active());
lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict);
.. _ime_pinyin_modes:
Modes
-----
The lv_ime_pinyin have the following modes:
- :cpp:enumerator:`LV_IME_PINYIN_MODE_K26`: Pinyin 26 key input mode
- :cpp:enumerator:`LV_IME_PINYIN_MODE_K9`: Pinyin 9 key input mode
- :cpp:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: Numeric keypad mode
The ``TEXT`` modes' layout contains buttons to change mode.
To set the mode manually, use :cpp:expr:`lv_ime_pinyin_set_mode(pinyin_ime, mode)`.
The default mode is :cpp:enumerator:`LV_IME_PINYIN_MODE_K26`.
.. _ime_pinyin_example:
Example
-------
.. include:: ../examples/others/ime/index.rst
.. _ime_pinyin_api:
API
---
lib/lvgl/docs/others/imgfont.md
-25
View File
@@ -1,25 +0,0 @@
# Image font (imgfont)
Draw image in label or span obj with imgfont.
This is often used to display Unicode emoji icons in text.
Supported image formats: determined by LVGL image decoder.
## Usage
Enable `LV_USE_IMGFONT` in `lv_conf.h`.
To create a new imgfont use `lv_imgfont_create(height, path_cb)`.
`height` used to indicate the size of a imgfont.
`path_cb` Used to get the image path of the specified unicode.
Use `lv_imgfont_destroy(imgfont)` to destroy a imgfont that is no longer used.
## Example
```eval_rst
.. include:: ../../examples/others/imgfont/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_imgfont.h
:project: lvgl
```
lib/lvgl/docs/others/imgfont.rst
+41
View File
@@ -0,0 +1,41 @@
.. _lv_imgfont:
==========
Image font
==========
Draw image in **label** or **span** obj with :cpp:type:`lv_imgfont`. This is often used to
display Unicode emoji icons in text.
Supported image formats: determined by enabled LVGL :ref:`image decoders <overview_image_decoder>`.
.. _lv_imgfont_usage:
Usage
-----
Enable :c:macro:`LV_USE_IMGFONT` in ``lv_conf.h``.
To create a new *imgfont* use :cpp:expr:`lv_imgfont_create(height, path_cb, user_data)`.
- ``height`` Font size.
- ``path_cb`` A function to get the image path of a character.
Return ``NULL`` if no image should be shown, but the character itself.
- ``user_data`` Pointer to user data.
To use the *imgfont* in a label, reference it:
:cpp:expr:`lv_obj_set_style_text_font(label, imgfont, LV_PART_MAIN)`
To destroy the *imgfont* that is no longer used, use :cpp:expr:`lv_imgfont_destroy(imgfont)`.
.. _lv_imgfont_example:
Example
-------
.. include:: ../examples/others/imgfont/index.rst
.. _lv_imgfont_api:
API
---
lib/lvgl/docs/others/index.md
-17
View File
@@ -1,17 +0,0 @@
# Others
```eval_rst
.. toctree::
:maxdepth: 1
snapshot
monkey
gridnav
fragment
msg
imgfont
ime_pinyin
```
lib/lvgl/docs/others/index.rst
+19
View File
@@ -0,0 +1,19 @@
.. _others:
======
Others
======
.. toctree::
:maxdepth: 1
snapshot
monkey
gridnav
file_explorer
fragment
observer
imgfont
ime_pinyin
obj_id
obj_property
lib/lvgl/docs/others/monkey.md
-35
View File
@@ -1,35 +0,0 @@
# Monkey
A simple monkey test. Use random input to stress test the application.
## Usage
Enable `LV_USE_MONKEY` in `lv_conf.h`.
First configure monkey, use `lv_monkey_config_t` to define the configuration structure, set the `type` (check [input devices](/overview/indev) for the supported types), and then set the range of `period_range` and `input_range`, the monkey will output random operations at random times within this range. Call `lv_monkey_create` to create monkey. Finally call `lv_monkey_set_enable(monkey, true)` to enable monkey.
If you want to pause the monkey, call `lv_monkey_set_enable(monkey, false)`. To delete the monkey, call `lv_monkey_del(monkey)`.
Note that `input_range` has different meanings in different `type`:
- `LV_INDEV_TYPE_POINTER` No effect, click randomly within the pixels of the screen resolution.
- `LV_INDEV_TYPE_ENCODER` The minimum and maximum values ​​of `enc_diff`.
- `LV_INDEV_TYPE_BUTTON` The minimum and maximum values ​​of `btn_id`. Use `lv_monkey_get_indev()` to get the input device, and use `lv_indev_set_button_points()` to map the key ID to the coordinates.
- `LV_INDEV_TYPE_KEYPAD` No effect, Send random [Keys](/overview/indev).
## Example
```eval_rst
.. include:: ../../examples/others/monkey/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_monkey.h
:project: lvgl
```
lib/lvgl/docs/others/monkey.rst
+47
View File
@@ -0,0 +1,47 @@
.. _monkey:
======
Monkey
======
A simple monkey test. Use random input to stress test the application.
.. _monkey_usage:
Usage
-----
Enable :c:macro:`LV_USE_MONKEY` in ``lv_conf.h``.
First configure monkey, use :c:struct:`lv_monkey_config_t` to define the
configuration structure, set the ``type`` (check `input devices </overview/indev>`__ for the supported types), and then set the
range of ``period_range`` and ``input_range``, the monkey will output
random operations at random times within this range. Call
:cpp:func:`lv_monkey_create` to create monkey. Finally call
:cpp:expr:`lv_monkey_set_enable(monkey, true)` to enable monkey.
If you want to pause the monkey, call
:cpp:expr:`lv_monkey_set_enable(monkey, false)`. To delete the monkey, call
:cpp:expr:`lv_monkey_delete(monkey)`.
Note that ``input_range`` has different meanings in different ``type``:
- :cpp:enumerator:`LV_INDEV_TYPE_POINTER`: No effect, click randomly within the pixels of the screen resolution.
- :cpp:enumerator:`LV_INDEV_TYPE_ENCODER`: The minimum and maximum values of ``enc_diff``.
- :cpp:enumerator:`LV_INDEV_TYPE_BUTTON`: The minimum and maximum values of ``btn_id``.
Use :cpp:func:`lv_monkey_get_indev` to get the input device, and use
:cpp:func:`lv_indev_set_button_points` to map the key ID to the coordinates.
- :cpp:enumerator:`LV_INDEV_TYPE_KEYPAD`: No effect, Send random :ref:`indev_keys`.
.. _monkey_example:
Example
-------
.. include:: ../examples/others/monkey/index.rst
.. _monkey_api:
API
---
lib/lvgl/docs/others/msg.md
-97
View File
@@ -1,97 +0,0 @@
# Messaging
Messaging (`lv_msg`) is a classic []publisher subscriber](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) implementation for LVGL.
## IDs
Both the publishers and the subscribers needs to know the message identifiers.
In `lv_msg` these are simple `uint32_t` integers. For example:
```c
#define MSG_DOOR_OPENED 1
#define MSG_DOOR_CLOSED 2
#define MSG_USER_NAME_CHANGED 100
#define MSG_USER_AVATAR_CHANGED 101
```
You can orgnaize the message IDs as you wish.
Both parties also need to know about the format of teh payload. E.g. in the above example
`MSG_DOOR_OPENED` and `MSG_DOOR_CLOSED` has no payload but `MSG_USER_NAME_CHANGED` can have a `const char *` payload containing the user name, and `MSG_USER_AVATAR_CHANGED` a `const void *` image source with the new avatar image.
## Send message
Messages can be sent with `lv_msg_send(msg_id, payload)`. E.g.
```c
lv_msg_send(MSG_USER_DOOR_OPENED, NULL);
lv_msg_send(MSG_USER_NAME_CHANGED, "John Smith");
```
## Subscribe to a message
`lv_msg_subscribe(msg_id, callback, user_data)` can be used to subscribe to message.
The callback should look like this:
```c
static void user_name_subscriber_cb(void * s, lv_msg_t * m)
{
/*s: a subscriber obeject, can be used to unscubscribe*/
/*m: a message object with the msg_id, payload, and user_data (set durung subscription)*/
...do something...
}
```
From `lv_msg_t` the followings can be used to get some data:
- `lv_msg_get_id(m)`
- `lv_msg_get_payload(m)`
- `lv_msg_get_user_data(m)`
## Subscribe with an lv_obj
It's quite typical that an LVGL widget is interested in some messages.
To make it simpler `lv_msg_subsribe_obj(msg_id, obj, user_data)` can be used.
If a new message is published with `msg_id` an `LV_EVENT_MSG_RECEIVED` event will be sent to the object.
For example:
```c
lv_obj_add_event_cb(user_name_label, user_name_label_event_cb, LV_EVENT_MSG_RECEIVED, NULL);
lv_msg_subsribe_obj(MSG_USER_NAME_CHANGED, user_name_label, NULL);
...
void user_name_label_event_cb(lv_event_t * e)
{
lv_obj_t * label = lv_event_get_target(e);
lv_msg_t * m = lv_event_get_msg(e);
lv_label_set_text(label, lv_msg_get_payload(m));
}
```
### Unsubscribe
`lv_msg_subscribe` returns a pointer which can be used to unsubscribe:
```c
void * s1;
s1 = lv_msg_subscribe(MSG_USER_DOOR_OPENED, some_callback, NULL);
...
lv_msg_unsubscribe(s1);
```
## Example
```eval_rst
.. include:: ../../examples/others/msg/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_msg.h
:project: lvgl
```
lib/lvgl/docs/others/obj_id.rst
+57
View File
@@ -0,0 +1,57 @@
.. _obj_id:
======
OBJ ID
======
LVGL provides an optional field in :cpp:type:`lv_obj_t` to store the object ID.
Object ID can be used in many cases, for example, to identify the object.
Or we can store a program backtrace to where the object is created.
.. _obj_id_usage:
Usage
-----
Enable this feature by setting :c:macro:`LV_USE_OBJ_ID` to `1` in ``lv_conf.h``.
Use the builtin obj ID generator by setting :c:macro:`LV_USE_OBJ_ID_BUILTIN` to `1`.
Otherwise provide your own custom implementation.
The ID is automatically generated and assigned to :cpp:expr:`obj->id` during obj's
construction by calling API :cpp:expr:`lv_obj_assign_id(obj)` from :cpp:func:`lv_obj_constructor`.
You can directly access the ID by :cpp:expr:`obj->id` or use API :cpp:expr:`lv_obj_stringify_id(obj, buf, len)`
to get a string representation of the ID.
Use custom ID generator
~~~~~~~~~~~~~~~~~~~~~~~
Set :c:macro:`LV_USE_OBJ_ID_BUILTIN` to `0` in ``lv_conf.h``.
Below APIs needed to be implemented and linked to lvgl.
.. code:: c
void lv_obj_assign_id(const lv_obj_class_t * class_p, lv_obj_t * obj);
void lv_obj_free_id(lv_obj_t * obj);
const char * lv_obj_stringify_id(lv_obj_t * obj, char * buf, uint32_t len);
:cpp:func:`lv_obj_assign_id` is called when an object is created. The object final class is passed from
parameter ``class_p``. Note it may be different than :cpp:expr:`obj->class_p` which is the class
currently being constructed.
:cpp:func:`lv_obj_free_id` is called when object is deconstructed. Free any resource allocated in :cpp:func:`lv_obj_assign_id`.
:cpp:func:`lv_obj_stringify_id` converts id to a string representation. The string is stored in ``buf``.
Dump obj tree
~~~~~~~~~~~~~
Use API :cpp:expr:`lv_obj_dump_tree(lv_obj_t * obj, int depth)` to dump the object tree.
It will walk through all children and print the object ID together with object address.
This is useful to debug UI crash. From log we can rebuilt UI the moment before crash.
For example, if the obj is stored to a :cpp:expr:`timer->user_data`, but obj is deleted when timer expired.
Timer callback will crash because of accessing wild pointer.
From the dump log we can clearly see that the obj does not exist.
lib/lvgl/docs/others/obj_property.rst
+81
View File
@@ -0,0 +1,81 @@
.. _obj_property:
===============
Widget Property
===============
Widgets have many properties that can decide what they look like and how they behave.
For example, the size, position, color, font, etc. are properties of a widget.
Specially, widget local style is also a property of a widget.
.. _obj_property_usage:
Usage
-----
Two APIs are provided to get/set widget properties. It can be enabled by setting
:c:macro:`LV_USE_OBJ_PROPERTY` to `1` in ``lv_conf.h``.
.. code:: c
typedef struct {
lv_prop_id_t id;
union {
int32_t num; /**< Number integer number (opacity, enums, booleans or "normal" numbers)*/
const void * ptr; /**< Constant pointers (font, cone text, etc)*/
lv_color_t color; /**< Colors*/
lv_style_value_t _style; /**< A place holder for style value which is same as property value.*/
};
} lv_property_t;
lv_result_t lv_obj_set_property(lv_obj_t * obj, const lv_property_t * value);
lv_property_t lv_obj_get_property(lv_obj_t * obj, lv_prop_id_t id);
.. _obj_property_id:
Property ID
~~~~~~~~~~~
:cpp:type:`lv_prop_id_t` identifies which property to get/set. :cpp:type:`lv_property_t` is an enum value
defined in ``lv_obj_property.h`` that are grouped by widget class. You can add your own
widget property ID following same rule and using helper macro :c:macro:`LV_PROPERTY_ID`.
Do make sure the ID is unique across all widgets.
Property ID is a 32-bit value. The higher 4bits indicates the property value type.
The lower 28bits is the property ID.
Note that :cpp:type:`lv_style_prop_t` is also valid property ID.
.. _obj_property_value:
Property Value
~~~~~~~~~~~~~~
Property value is a union of all possible property types including integer, pointer and color.
``_style`` is kept their just to indicate it's compatible with ``style`` value type.
A Step Further
--------------
The unified widget property set/get API is useful when developing wrapper layer for other
modules like micropython, lua, or for an external animation engine.
For pointer type of property value, which typically points to a specific struct, it still needs
additional code to convert values from dict, table etc to a C struct before setting to widget.
Another possible use case is to ease of creating UI from lots of code. For example, you can gather
all properties to an array now and set properties with a for loop.
.. code:: c
lv_property_t props[] = {
{ .id = LV_PROPERTY_IMAGE_SRC, .ptr = &img_demo_widgets_avatar, },
{ .id = LV_PROPERTY_IMAGE_PIVOT, .ptr = &pivot_50, },
{ .id = LV_PROPERTY_IMAGE_SCALE, .num = 128, },
{ .id = LV_PROPERTY_OBJ_FLAG_CLICKABLE, .num = 1, },
{ .id = LV_STYLE_IMAGE_OPA, .num = 128, },
{ .id = LV_STYLE_BG_COLOR, .color = (lv_color_t){.red = 0x11, .green = 0x22, .blue = 0x33}, },
}
LV_OBJ_SET_PROPERTY_ARRAY(obj, props);
lib/lvgl/docs/others/observer.rst
+342
View File
@@ -0,0 +1,342 @@
.. _observer:
========
Observer
========
.. _observer_overview:
Overview
********
The ``lv_observer`` module implements a standard `Observer pattern <https://en.wikipedia.org/wiki/Observer_pattern>`__.
It consists of:
- **subjects**: each containing a value
- **observers**: attached to subjects to be notified on value change
A typical use case looks like this:
.. code:: c
//It's a global variable
lv_subject_t my_subject;
/*-------
* main.c
*-------*/
extern lv_subject_t my_subject;
void main(void)
{
//Initialize the subject as integer with the default value of 10
lv_subject_init_int(&my_subject, 10);
some_module_init();
}
/*--------------
* some_module.c
*--------------*/
extern lv_subject_t some_subject;
//Will be called when the related subject's value changes
static void some_observer_cb(lv_observer_t * observer, lv_subject_t * subject)
{
int32_t v = lv_subject_get_int(subject);
do_something(v);
}
void some_module_init(void)
{
//Subscribe to a subject
lv_subject_add_observer(&some_subject, some_observer_cb, NULL);
}
/*--------------
* some_system.c
*--------------*/
extern lv_subject_t some_subject;
void some_event(void)
{
//Set the subject's value to 30. It will notify `some_observer_cb`
lv_subject_set_int(&some_subject, 30);
}
.. _observer_subject:
Subject
*******
Subject initialization
----------------------
Subjects have to be static or global :cpp:type:`lv_subject_t` type variables.
To initialize a subject use :cpp:expr:`lv_subject_init_<type>(&subject, params, init_value)`.
The following initializations exist for types:
- **Integer** :cpp:expr:`void lv_subject_init_int(lv_subject_t * subject, int32_t value)`
- **String** :cpp:expr:`void lv_subject_init_string(lv_subject_t * subject, char * buf, char * prev_buf, size_t size, const char * value)`
- **Pointer** :cpp:expr:`void lv_subject_init_pointer(lv_subject_t * subject, void * value)`
- **Color** :cpp:expr:`void lv_subject_init_color(lv_subject_t * subject, lv_color_t color)`
- **Group** :cpp:expr:`void lv_subject_init_group(lv_subject_t * subject, lv_subject_t * list[], uint32_t list_len)`
Set subject value
-----------------
The following functions can be used to set a subject's value:
- **Integer** :cpp:expr:`void lv_subject_set_int(lv_subject_t * subject, int32_t value)`
- **String** :cpp:expr:`void lv_subject_copy_string(lv_subject_t * subject, char * buf)`
- **Pointer** :cpp:expr:`void lv_subject_set_pointer(lv_subject_t * subject, void * ptr)`
- **Color** :cpp:expr:`void lv_subject_set_color(lv_subject_t * subject, lv_color_t color)`
Get subject's value
-------------------
The following functions can be used to get a subject's value:
- **Integer** :cpp:expr:`int32_t lv_subject_get_int(lv_subject_t * subject)`
- **String** :cpp:expr:`const char * lv_subject_get_string(lv_subject_t * subject)`
- **Pointer** :cpp:expr:`const void * lv_subject_get_pointer(lv_subject_t * subject)`
- **Color** :cpp:expr:`lv_color_t lv_subject_get_color(lv_subject_t * subject)`
Get subject's previous value
----------------------------
The following functions can be used to get a subject's previous value:
- **Integer** :cpp:expr:`int32_t lv_subject_get_previous_int(lv_subject_t * subject)`
- **String** :cpp:expr:`const char * lv_subject_get_previous_string(lv_subject_t * subject)`
- **Pointer** :cpp:expr:`const void * lv_subject_get_previous_pointer(lv_subject_t * subject)`
- **Color** :cpp:expr:`lv_color_t lv_subject_get_previous_color(lv_subject_t * subject)`
.. _observer_observer:
Observer
********
Subscribe to a subject
----------------------
To subscribe to a subject the following function can be used:
.. code:: c
lv_observer_t * observer = lv_subject_add_observer(&some_subject, some_observer_cb, user_data);
Where the observer callback should look like this:
.. code:: c
static void some_observer_cb(lv_observer_t * observer, lv_subject_t * subject)
{
...
}
It's also possible to save a target widget when subscribing to a subject.
In this case when widget is deleted, it will automatically unsubscribe from the subject.
In the observer callback :cpp:expr:`lv_observer_get_target(observer)` can be used to get the saved widget.
.. code:: c
lv_observer_t * observer = lv_subject_add_observer_obj(&some_subject, some_observer_cb, obj, user_data);
In more generic case any pointer can be saved a target:
.. code:: c
lv_observer_t * observer = lv_subject_add_observer_with_target(&some_subject, some_observer_cb, some_pointer, user_data);
Unsubscribe from a subject
--------------------------
.. code:: c
lv_observer_remove(observer)
To unsubscribe from a subject with all widgets you can use:
.. code:: c
lv_subject_remove_obj(subject, obj)
.. _observer_subject_groups:
Subject groups
**************
There are cases when a subject changes and the value of some other subjects are also required by the observer.
As a practical example imagine an instrument which measures either voltage or current.
To display the measured value on a label 3 things are required:
1. What do we measure (current or voltage)?
2. What is the measured value?
3. What is the range or unit (mV, V, mA, A)?
When any of these 3 parameters changes the label needs to be updated,
and it needs to know all 3 parameters to compose its text.
To handle this you can create an array from some existing subjects and pass
this array as a parameter when you initialize a subject with group type.
.. code:: c
static lv_subject_t * subject_list[3] = {&subject_1, &subject_2, &subject_3};
lv_subject_init_group(&subject_all, subject_list, 3); /*The last parameter is the number of elements*/
You can add observers to subject groups in the regular way.
The trick is that when any element of the group is notified the subject group will be notified too.
The above Voltage/Current measurement example looks like this in the practice:
.. code:: c
lv_obj_t * label = lv_label_create(lv_screen_active());
lv_subject_t subject_mode; //Voltage or Current
lv_subject_t subject_value; //Measured value
lv_subject_t subject_unit; //The unit
lv_subject_t subject_all; //It will be the subject group
lv_subject_t * subject_list[3] = {&subject_mode, &subject_value, &subject_unit}; //The elements of the group
lv_subject_init_int(&subject_mode, 0); //Let's say 0 is Voltage, 1 is Current
lv_subject_init_int(&subject_value, 0);
lv_subject_init_pointer(&subject_unit, "V");
lv_subject_init_group(&subject_all, subject_list, 3);
lv_subject_add_observer_obj(&subject_all, all_observer_cb, label, NULL);
...
static void all_observer_cb(lv_observer_t * observer, lv_subject_t * subject)
{
lv_obj_t * label = lv_observer_get_target(observer);
lv_subject_t * subject_mode = lv_subject_get_group_element(subject, 0);
lv_subject_t * subject_value = lv_subject_get_group_element(subject, 1);
lv_subject_t * subject_unit = lv_subject_get_group_element(subject, 2);
int32_t mode = lv_subject_get_int(subject_mode);
int32_t value = lv_subject_get_int(subject_value);
const char * unit = lv_subject_get_pointer(subject_unit);
lv_label_set_text_fmt(label, "%s: %d %s", mode ? "Current" : "Voltage", value, unit);
}
.. _observer_widget_binding:
Widget binding
**************
Base object
-----------
Set an object flag if an integer subject's value is equal to a reference value, clear the flag otherwise
.. code:: c
observer = lv_obj_bind_flag_if_eq(obj, &subject, LV_OBJ_FLAG_*, ref_value);
Set an object flag if an integer subject's value is not equal to a reference value, clear the flag otherwise
.. code:: c
observer = lv_obj_bind_flag_if_not_eq(obj, &subject, LV_OBJ_FLAG_*, ref_value);
Set an object state if an integer subject's value is equal to a reference value, clear the flag otherwise
.. code:: c
observer = lv_obj_bind_state_if_eq(obj, &subject, LV_STATE_*, ref_value);
Set an object state if an integer subject's value is not equal to a reference value, clear the flag otherwise
.. code:: c
observer = lv_obj_bind_state_if_not_eq(obj, &subject, LV_STATE_*, ref_value);
Button
------
Set an integer subject to 1 when a button is checked and set it 0 when unchecked.
.. code:: c
observer = lv_button_bind_checked(obj, &subject);
Label
-----
Bind an integer, string, or pointer (pointing to a string) subject to a label.
An optional format string can be added with 1 format specifier (e.g. ``"%d °C"``)
If the format string is ``NULL`` the value will be used directly. In this case on string and pointer type subjects can be used.
.. code:: c
observer = lv_label_bind_text(obj, &subject, format_string);
Arc
---
Bind an integer subject to an arc's value.
.. code:: c
observer = lv_arc_bind_value(obj, &subject);
Slider
------
Bind an integer subject to a slider's value
.. code:: c
observer = lv_slider_bind_value(obj, &subject);
Roller
------
Bind an integer subject to a roller's value
.. code:: c
observer = lv_roller_bind_value(obj, &subject);
Drop-down
---------
Bind an integer subject to a drop-down's value
.. code:: c
observer = lv_dropdown_bind_value(obj, &subject);
.. _observer_example:
Example
*******
.. include:: ../examples/others/observer/index.rst
.. _observer_api:
API
***
lib/lvgl/docs/others/snapshot.md
-63
View File
@@ -1,63 +0,0 @@
# Snapshot
Snapshot provides APIs to take snapshot image for LVGL object together with its children. The image will look exactly like the object.
## Usage
Simply call API `lv_snapshot_take` to generate the image descriptor which can be set as image object src using `lv_img_set_src`.
Note, only below color formats are supported for now:
- LV_IMG_CF_TRUE_COLOR_ALPHA
- LV_IMG_CF_ALPHA_1BIT
- LV_IMG_CF_ALPHA_2BIT
- LV_IMG_CF_ALPHA_4BIT
- LV_IMG_CF_ALPHA_8BIT
### Free the Image
The memory `lv_snapshot_take` uses are dynamically allocated using `lv_mem_alloc`. Use API `lv_snapshot_free` to free the memory it takes. This will firstly free memory the image data takes, then the image descriptor.
Take caution to free the snapshot but not delete the image object. Before free the memory, be sure to firstly unlink it from image object, using `lv_img_set_src(NULL)` and `lv_img_cache_invalidate_src(src)`.
Below code snippet explains usage of this API.
```c
void update_snapshot(lv_obj_t * obj, lv_obj_t * img_snapshot)
{
lv_img_dsc_t* snapshot = (void*)lv_img_get_src(img_snapshot);
if(snapshot) {
lv_snapshot_free(snapshot);
}
snapshot = lv_snapshot_take(obj, LV_IMG_CF_TRUE_COLOR_ALPHA);
lv_img_set_src(img_snapshot, snapshot);
}
```
### Use Existing Buffer
If the snapshot needs update now and then, or simply caller provides memory, use API `lv_res_t lv_snapshot_take_to_buf(lv_obj_t * obj, lv_img_cf_t cf, lv_img_dsc_t * dsc, void * buf, uint32_t buff_size);` for this case. It's caller's responsibility to alloc/free the memory.
If snapshot is generated successfully, the image descriptor is updated and image data will be stored to provided `buf`.
Note that snapshot may fail if provided buffer is not enough, which may happen when object size changes. It's recommended to use API `lv_snapshot_buf_size_needed` to check the needed buffer size in byte firstly and resize the buffer accordingly.
## Example
```eval_rst
.. include:: ../../examples/others/snapshot/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_snapshot.h
:project: lvgl
```
lib/lvgl/docs/others/snapshot.rst
+77
View File
@@ -0,0 +1,77 @@
.. _snapshot:
========
Snapshot
========
Snapshot provides API to take snapshot image for LVGL object together
with its children. The image will look exactly like the object on display.
.. _snapshot_usage:
Usage
-----
Simply call API :cpp:func:`lv_snapshot_take` to generate the image descriptor
which can be set as image object src using :cpp:func:`lv_image_set_src`.
Note, only following color formats are supported for now:
- :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`
- :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`
- :cpp:enumerator:`LV_COLOR_FORMAT_XRGB8888`
- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`
Free the Image
~~~~~~~~~~~~~~
The memory :cpp:func:`lv_snapshot_take` uses are dynamically allocated using
:cpp:func:`lv_draw_buf_create`. Use API :cpp:func:`lv_draw_buf_destroy` to free the memory it
takes. This will firstly free memory the image data takes, then the
image descriptor.
The snapshot image which is the draw buffer returned by :cpp:func:`lv_snapshot_take`
normally won't be added to cache because it can be drawn directly. So you don't need
to invalidate cache by :cpp:func:`lv_image_cache_drop` before destroy the draw buffer.
Below code snippet explains usage of this API.
.. code:: c
void update_snapshot(lv_obj_t * obj, lv_obj_t * img_snapshot)
{
lv_draw_buf_t* snapshot = (void*)lv_image_get_src(img_snapshot);
if(snapshot) {
lv_draw_buf_destroy(snapshot);
}
snapshot = lv_snapshot_take(obj, LV_COLOR_FORMAT_ARGB8888);
lv_image_set_src(img_snapshot, snapshot);
}
Use Existing Buffer
~~~~~~~~~~~~~~~~~~~
If the snapshot needs update now and then, or simply caller provides memory, use API
``lv_result_t lv_snapshot_take_to_draw_buf(lv_obj_t * obj, lv_color_format_t cf, lv_draw_buf_t * draw_buf);``
for this case. It's caller's responsibility to create and destroy the draw buffer.
If snapshot is generated successfully, the image descriptor is updated
and image data will be stored to provided ``buf``.
Note that snapshot may fail if provided buffer is not enough, which may
happen when object size changes. It's recommended to use API
:cpp:func:`lv_snapshot_reshape_draw_buf` to prepare the buffer firstly and if it
fails, destroy the existing draw buffer and call `lv_snapshot_take` directly.
.. _snapshot_example:
Example
-------
.. include:: ../examples/others/snapshot/index.rst
.. _snapshot_api:
API
---