mirrors/lvgl
0
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2024-11-23 01:33:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): reorganize docs (#7136)

Browse Source
This commit is contained in:
Victor Wheeler 2024-10-23 12:53:33 -06:00 committed by GitHub
parent c61ca42a2a
commit 9b6f6d23f1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
212 changed files with 6314 additions and 5806 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/CHANGELOG.rst
View File

@ -1,24 +1,24 @@
.. _changelog:
Changelog
=========
Change Log
==========
`v9.2 <https://github.com/lvgl/lvgl/compare/v9.1.0...v9.2.0>`__ 26 August 2024
------------------------------------------------------------------------------
It's huge release with many interesting updates:
- Built-in `Wayland driver <https://docs.lvgl.io/master/integration/driver/wayland.html>`__
- `OpenGL ES and GLFW driver <https://docs.lvgl.io/master/integration/driver/opengles.html>`__ with support for external textures
- `Renesas GLCDC <https://docs.lvgl.io/master/integration/driver/display/renesas_glcdc.html>`__ driver
- Built-in :ref:`Wayland driver <wayland_driver>`
- :ref:`OpenGL ES and GLFW driver <opengl_es_driver>` with support for external textures
- :ref:`renesas_glcdc` driver
- L8 and I1 rendering support
- Matrix transformations during rendering
- New `file system interfaces <https://docs.lvgl.io/master/libs/fs.html>`__: LittleFS, ESP LittleFS, Arduino FS
- New :ref:`file system interfaces <libs_filesystem>`: LittleFS, ESP LittleFS, Arduino FS
- SDL renderer improvements (supporting all draw task types and improving speed)
- Radial, Conic, and Skew `gradients supported <https://docs.lvgl.io/master/overview/style.html#metallic-knob-with-conic-gradient>`__ by software rendering and VG-Lite
- `QNX <https://docs.lvgl.io/master/integration/os/qnx.html>`__ and `MQX <https://docs.lvgl.io/master/integration/os/mqx.html>`__ support
- `Mouse hover handling <https://docs.lvgl.io/master/get-started/quick-overview.html>`__
- `Lottie <https://docs.lvgl.io/master/widgets/lottie.html>`__ support
- Radial, Conic, and Skew `gradients supported <https://docs.lvgl.io/master/details/base-widget/styles/style.html#metallic-knob-with-conic-gradient>`__ by software rendering and VG-Lite
- :ref:`qnx` and :ref:`mqx` support
- :ref:`Mouse hover handling <styles_states>`
- :ref:`lv_lottie` support
- CI tests for UEFI builds
And many smaller fixes and features

12
docs/CODING_STYLE.rst
View File

@ -148,7 +148,7 @@ illustrating most of the Doxygen commands used in LVGL.
.. code-block:: c
/**
* Set alignment of objects placed in containers with LV_STYLE_FLEX_FLOW style.
* Set alignment of Widgets placed in containers with LV_STYLE_FLEX_FLOW style.
*
* The values for the `..._place` arguments come from the `lv_flex_align_t`
* enumeration and have the same meanings as they do for flex containers in CSS.
@ -170,7 +170,7 @@ illustrating most of the Doxygen commands used in LVGL.
* - https://css-tricks.com/snippets/css/a-guide-to-flexbox/
* - see `lv_obj_set_flex_grow()` for additional information.
*/
void lv_obj_set_flex_align(lv_obj_t * obj, lv_flex_align_t main_place, lv_flex_align_t cross_place,
void lv_obj_set_flex_align(lv_obj_t * widget, lv_flex_align_t main_place, lv_flex_align_t cross_place,
lv_flex_align_t track_cross_place);
@ -264,12 +264,12 @@ follow some coding conventions:
- Use typed pointers instead of :cpp:expr:`void *` pointers
- Widget constructor must follow the ``lv_<widget_name>_create(lv_obj_t * parent)`` pattern.
- Widget members function must start with ``lv_<widget_name>`` and should receive :cpp:expr:`lv_obj_t *` as first
argument which is a pointer to widget object itself.
argument which is a pointer to Widget object itself.
- ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the
first argument, and the prefix of the ``struct`` name should be used as the prefix of the
function name too (e.g. :cpp:expr:`lv_display_set_default(lv_display_t * disp)`)
function name as well (e.g. :cpp:expr:`lv_display_set_default(lv_display_t * disp)`)
- Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as "private".
- Argument must be named in H files too.
- Argument must be named in H files as well.
- Do not ``malloc`` into a static or global variables. Instead declare the variable in ``lv_global_t``
structure in ``lv_global.h`` and mark the variable with :cpp:expr:`(LV_GLOBAL_DEFAULT()->variable)` when it's used.
- To register and use callbacks one of the following needs to be followed.
@ -293,7 +293,7 @@ Here is example to show bracket placing and using of white space:
/**
* Set new text for a label. Memory will be allocated by label to store text.
*
* @param label pointer to label object
* @param label pointer to label Widget
* @param text '\0' terminated character string.
* NULL to refresh with current text.
*/

54
docs/README.md
View File

@ -52,7 +52,18 @@ The most important thing that has to be done when contributing to LVGL is ***EVE
The below are some rules to follow when updating any of the `.rst` files located in the `./docs/` directory and any of it's subdirectories.
### index.rst files
### What to Name Your `.rst` File
The documentation-generation logic uses the stem of the file name (i.e. "event" from file name "event.rst") and compares this with code-element names found by Doxygen. If a match is found, then it appends hyperlinks to the API pages that contain those code elements (names of macros, enum/struct/union types, variables, namespaces, typedefs and functions).
If this is appropriate for the .RST file you are creating, ensure the stem of the file name matches the beginning part of the code-element name you want it to be associated with.
If this is *not* appropriate for the .RST file you are creating, ensure the stem of the file name DOES NOT match any code-element names found in the LVGL header files under the ./src/ directory.
In alignment with the above, use a file name stem that is appropriate to the topic being covered.
### index.rst Files
If you create a new directory you MUST have an `index.rst` file in that directory and that index file needs to be pointed to in the `index.rst` file that is located in the parent directory.
@ -124,6 +135,8 @@ This in-line markup (interpreted text using the Sphinx-defined custom `:ref:` ro
This latter syntax enables you to put a **link target** anywhere in an .RST file (not just above a heading) and link to it using this syntax.
Note: This latter syntax was either added or fixed in Sphinx recently. It did not work in Sphinx 7.3.7.
@ -144,19 +157,19 @@ If you are creating a new .RST file, use this convention:
=====
Title
=====
Chapter
*******
Section
-------
Sub Section
~~~~~~~~~~~
Sub Sub Section
^^^^^^^^^^^^^^^
Sub Sub Sub Section
'''''''''''''''''''
@ -201,7 +214,7 @@ To create a bulleted list, do the following:
lines to align with item text like this.
- If you want to include a code block under a list item,
it must be intended to align with the list item like this:
.. code-block: python
<=== blank line here is important
# this is some code
@ -232,22 +245,23 @@ If you want to reference portions of the LVGL code from the documentation (in .R
There is a special directive when wanting to use a more complex expression. For example when showing the arguments passed to a function.
:cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`
:cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX)`
:cpp:expr:`lv_slider_set_mode(slider, LV_SLIDER_MODE_...)`
Arguments that are expressions (more than one word), or contain non-alphanumeric characters will cause the `:cpp:expr:` interpreted-text to fail. Examples:
:cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX/GRID)` <== arg with > 1 word
:cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_*)` <== asterisk
:cpp:expr:`lv_obj_set_layout(*obj, LV_LAYOUT_FLEX)` <== asterisk
:cpp:expr:`lv_obj_set_layout((lv_obj_t *)obj, LV_LAYOUT_FLEX)` <== cast
:cpp:expr:`lv_obj_set_layout(&obj, LV_LAYOUT_FLEX);` <== ampersand
:cpp:expr:`lv_obj_set_layout(obj, ...)` <== elipsis
:cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)` <== arg with > 1 word
:cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_*)` <== asterisk
:cpp:expr:`lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)` <== asterisk
:cpp:expr:`lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)` <== cast
:cpp:expr:`lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);` <== ampersand & semicolon
:cpp:expr:`lv_obj_set_layout(widget, ...)` <== lone elipsis
For such examples, simply use reStructuredText literal markup like this:
``lv_obj_set_layout(obj, LV_LAYOUT_FLEX/GRID)``
``lv_obj_set_layout(obj, LV_LAYOUT_*)``
``lv_obj_set_layout(*obj, LV_LAYOUT_FLEX)``
``lv_obj_set_layout((lv_obj_t *)obj, LV_LAYOUT_FLEX)``
``lv_obj_set_layout(&obj, LV_LAYOUT_FLEX);``
``lv_obj_set_layout(obj, ...)``
``lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)``
``lv_obj_set_layout(widget, LV_LAYOUT_*)``
``lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)``
``lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)``
``lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);``
``lv_obj_set_layout(widget, ...)``

36
docs/README_jp.rst
View File

@ -75,16 +75,16 @@ Cライブラリ。(C++互換) -
任意の(RT)OS、任意のMCU・MPU用にコンパイル可能。 -
電子ペーパー、OLEDディスプレイ、TFTディスプレイ、白黒ディスプレイ、モニターに対応。
`Porting
Guide <https://docs-lvgl-io.translate.goog/master/porting/project.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
Guide <https://docs-lvgl-io.translate.goog/master/intro/add-lvgl-to-your-project/project.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
- MITライセンスにより商用利用可能。 - システム要件：RAM 32KB、Flash
128KB、フレームバッファ、レンダリング用に1/10以上のスクリーンサイズのバッファ。
- OS、外部メモリ、GPUもサポート。
**ウィジェット、スタイル、レイアウトなど** - 30以上の組み込み
`ウィジェット <https://docs-lvgl-io.translate.goog/master/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__: ボタン、ラベル、スライダー、グラフ、キーボード、メーター、円弧、表など。
`ウィジェット <https://docs-lvgl-io.translate.goog/master/details/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__: ボタン、ラベル、スライダー、グラフ、キーボード、メーター、円弧、表など。
-
ウィジェットの任意の部分を任意の状態にカスタマイズ可能な豊富なスタイルプロパティを備えた柔軟な
`スタイルシステム <https://docs-lvgl-io.translate.goog/master/overview/style.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__\ 。
`スタイルシステム <https://docs-lvgl-io.translate.goog/master/details/base-widget/styles/style.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__\ 。
-
`Flexbox <https://docs-lvgl-io.translate.goog/master/layouts/flex.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
および
@ -98,9 +98,9 @@ Guide <https://docs-lvgl-io.translate.goog/master/porting/project.html?_x_tr_sl=
アニメーション、アンチエイリアシング、不透明度、スムーズスクロール、シャドウ、画像変換などをサポートするレンダリングエンジン。
-
マウス、タッチパッド、キーパッド、キーボード、外部ボタン、エンコーダ等の
`入力デバイス <https://docs-lvgl-io.translate.goog/master/porting/indev.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
`入力デバイス <https://docs-lvgl-io.translate.goog/master/details/modules/indev.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
をサポート。 -
`マルチディスプレイ <https://docs-lvgl-io.translate.goog/master/overview/display.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
`マルチディスプレイ <https://docs-lvgl-io.translate.goog/master/details/modules/display.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
対応。
**Binding と Build をサポート** - `MicroPython
@ -108,9 +108,9 @@ Binding <https://blog-lvgl-io.translate.goog/2019-02-20/micropython-bindings?_x_
が LVGL API を公開。 -
カスタムビルドシステムは使用せず、プロジェクトの他のファイルをビルドするときに、LVGLをビルド可能。
- Make と
`CMake <https://docs-lvgl-io.translate.goog/master/get-started/platforms/cmake.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
`CMake <https://docs-lvgl-io.translate.goog/master/details/integration/building/cmake.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
が含まれており、すぐ使えるようにサポート。 -
`PCのシミュレータで開発したUIコード <https://docs-lvgl-io.translate.goog/master/get-started/platforms/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
`PCのシミュレータで開発したUIコード <https://docs-lvgl-io.translate.goog/master/details/integration/ide/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
は、そのまま組込み用ハードウェアでも使用可能。 - `Emscripten
port <https://github.com/lvgl/lv_web_emscripten>`__ :gb:
によりC言語のUIコードをHTMLファイルに変換。
@ -128,19 +128,19 @@ UI開発をよりシンプルかつ迅速にするための、ユーザーイン
--------------------
LVGL は以下で利用可能です。 - `Arduino
library <https://docs-lvgl-io.translate.goog/master/get-started/platforms/arduino.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
library <https://docs-lvgl-io.translate.goog/master/details/entegration/framework/arduino.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
- `PlatformIO
package <https://registry.platformio.org/libraries/lvgl/lvgl>`__ :gb: -
`Zephyr
library <https://docs-zephyrproject-org.translate.goog/latest/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
- `ESP32
component <https://docs-lvgl-io.translate.goog/master/get-started/platforms/espressif.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
component <https://docs-lvgl-io.translate.goog/master/details/integration/chip/espressif.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
- `NXP MCUXpresso
component <https://www-nxp-com.translate.goog/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
- `NuttX
library <https://docs-lvgl-io.translate.goog/master/get-started/os/nuttx.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
library <https://docs-lvgl-io.translate.goog/master/details/integration/os/nuttx.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
- `RT-Thread
RTOS <https://docs-lvgl-io.translate.goog/master/get-started/os/rt-thread.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
RTOS <https://docs-lvgl-io.translate.goog/master/details/integration/os/rt-thread.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
- NXP MCUXpresso library - CMSIS-Pack
:robot:
@ -386,7 +386,7 @@ C code
/*Add the style sheet to the slider's INDICATOR part*/
lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR);
/*Add the same style to the KNOB part too and locally overwrite some properties*/
/*Add the same style to the KNOB part as well and locally overwrite some properties*/
lv_obj_add_style(slider, &style_indicator, LV_PART_KNOB);
lv_obj_set_style_outline_color(slider, lv_color_hex(0x0096FF), LV_PART_KNOB);
@ -441,7 +441,7 @@ MicroPython code \| Online Simulator :gb:
slider.add_style(style_indicator, lv.PART.INDICATOR)
slider.add_style(style_indicator, lv.PART.KNOB)
# Add the same style to the KNOB part too and locally overwrite some properties
# Add the same style to the KNOB part as well and locally overwrite some properties
slider.set_style_outline_color(lv.color_hex(0x0096FF), lv.PART.KNOB)
slider.set_style_outline_width(3, lv.PART.KNOB)
slider.set_style_outline_pad(-5, lv.PART.KNOB)
@ -556,16 +556,16 @@ LVGLを使い始める時は、以下の順に進める事をおすすめしま
`Introduction <https://docs-lvgl-io.translate.goog/master/intro/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
を読みましょう。 (5分間)
3. LVGLの基本に慣れるため `Quick
overview <https://docs-lvgl-io.translate.goog/master/get-started/quick-overview.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
overview <https://docs-lvgl-io.translate.goog/master/intro/overview.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
を読みましょう。 (15分間)
**LVGLを使ってみましょう**
4. `シミュレータ <https://docs-lvgl-io.translate.goog/master/get-started/platforms/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
4. `シミュレータ <https://docs-lvgl-io.translate.goog/master/details/integration/ide/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
をセットアップしましょう。 (10 minutes)
5. `サンプルプログラム <https://github.com/lvgl/lvgl/tree/master/examples>`__
:gb: を動かしてみましょう。
6. `移植ガイド <https://docs-lvgl-io.translate.goog/master/porting/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
6. `移植ガイド <https://docs-lvgl-io.translate.goog/master/intro/add-lvgl-to-your-project/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
を参考に、LVGLを開発ボードに移植してみましょう。すぐ使える形の
`プロジェクト <https://github.com/lvgl?q=lv_port_>`__ :gb:
も用意してあります。
@ -573,10 +573,10 @@ LVGLを使い始める時は、以下の順に進める事をおすすめしま
**より詳しく体験してみましょう**
7. ライブラリの理解を深めるため
`Overview <https://docs-lvgl-io.translate.goog/master/overview/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
`Overview <https://docs-lvgl-io.translate.goog/master/details/modules/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
を読みましょう。 (2～3時間)
8. ウィジェットの機能や使い方の詳細は
`Widgets <https://docs-lvgl-io.translate.goog/master/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
`Widgets <https://docs-lvgl-io.translate.goog/master/details/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
でご確認ください。
**助け合いましょう**

26
docs/README_pt_BR.rst
View File

@ -88,8 +88,8 @@ algum suporte durante o desenvolvimento de seu próximo projeto de GUI.
dependências externas.
- Pode ser compilado para qualquer display MCU ou MPU, e qualquer
sistema operacional de tempo real (RT-OS).
- Suporta monitores monocromáticos, ePaper, OLED ou TFT. `Guia de
portabilidade <https://docs.lvgl.io/master/porting/project.html>`__
- Suporta monitores monocromáticos, ePaper, OLED ou TFT. :ref:`Guia de
portabilidade <initializing_lvgl>`
- Distribuído sob a licença do MIT, para que você também possa usá-lo
facilmente em projetos comerciais.
- Precisa de apenas 32 kB de RAM e 128 kB de Flash, um frame buffer e
@ -126,10 +126,10 @@ algum suporte durante o desenvolvimento de seu próximo projeto de GUI.
- Nenhum sistema de compilação personalizado é usado. Você pode
construir o LVGL enquanto constrói os outros arquivos do seu projeto.
- O suporte para Make e
`CMake <https://docs.lvgl.io/master/get-started/platforms/cmake.html>`__
:ref:`CMake <build_cmake>`
já vem incluído.
- `Desenvolva no
PC <https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html>`__
PC <https://docs.lvgl.io/master/details/integration/ide/pc-simulator.html>`__
e use o mesmo código de interface do usuário em hardwares
incorporados (embedded hardware).
- Converta o código C para um arquivo HTML com o `Emscripten
@ -187,19 +187,19 @@ receberá o pagamento em alguns dias.
LVGL está disponível para:
- `Arduino
library <https://docs.lvgl.io/master/get-started/platforms/arduino.html>`__
library <https://docs.lvgl.io/master/details/entegration/framework/arduino.html>`__
- `PlatformIO
package <https://registry.platformio.org/libraries/lvgl/lvgl>`__
- `Zephyr
library <https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_LVGL>`__
- `ESP32
component <https://docs.lvgl.io/master/get-started/platforms/espressif.html>`__
component <https://docs.lvgl.io/master/details/integration/chip/espressif.html>`__
- `NXP MCUXpresso
component <https://www.nxp.com/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY>`__
- `NuttX
library <https://docs.lvgl.io/master/get-started/os/nuttx.html>`__
library <https://docs.lvgl.io/master/details/integration/os/nuttx.html>`__
- `RT-Thread
RTOS <https://docs.lvgl.io/master/get-started/os/rt-thread.html>`__
RTOS <https://docs.lvgl.io/master/details/integration/os/rt-thread.html>`__
- NXP MCUXpresso library
- CMSIS-Pack
@ -614,28 +614,28 @@ Esta lista irá guiá-lo para começar com o LVGL passo a passo.
`introdução <https://docs.lvgl.io/master/intro/index.html>`__ da
documentação (~5 minutos)
3. Familiarize-se com o básico na página de `visão geral
rápida <https://docs.lvgl.io/master/get-started/quick-overview.html>`__
rápida <https://docs.lvgl.io/master/intro/overview.html>`__
(~15 minutos)
**Começando a usar o LVGL**
4. Configure um
`simulador <https://docs.lvgl.io/master/get-started/platforms/pc-simulator.html>`__
`simulador <https://docs.lvgl.io/master/details/integration/ide/pc-simulator.html>`__
(~10 minutos)
5. Experimente alguns
`exemplos <https://github.com/lvgl/lvgl/tree/master/examples>`__
6. Porte o LVGL para uma placa. Veja o guia `portando o
LVGL <https://docs.lvgl.io/master/porting/index.html>`__ ou veja um
LVGL <https://docs.lvgl.io/master/intro/add-lvgl-to-your-project/index.html>`__ ou veja um
projeto pronto para usar em
`projetos <https://github.com/lvgl?q=lv_port_>`__
**Torne-se um profissional**
7. Leia a página `visão
geral <https://docs.lvgl.io/master/overview/index.html>`__ para
geral <https://docs.lvgl.io/master/details/modules/index.html>`__ para
entender melhor a biblioteca (~2-3 horas)
8. Verifique a documentação dos
`widgets <https://docs.lvgl.io/master/widgets/index.html>`__ para ver
`widgets <https://docs.lvgl.io/master/details/widgets/index.html>`__ para ver
seus recursos e usabilidade
**Obtenha ajuda e ajude outras pessoas**

32
docs/README_zh.rst
View File

@ -72,25 +72,25 @@ RAM 和 128 KB Flash、C 编译器、帧缓冲区和至少 1/10 屏幕大小的
- 一个完全可移植的 C（C++ 兼容）库，没有外部依赖关系。
- 可以编译到任何 MCU 或 MPU，使用任何 RTOS 或者操作系统。
- 支持单色、ePaper、OLED、TFT 显示器或者模拟器。
`移植指南 <https://docs.lvgl.io/master/porting/project.html>`__
`移植指南 <https://docs.lvgl.io/master/intro/add-lvgl-to-your-project/project.html>`__
- 该项目使用 MIT 许可证，因此您可以在商业项目中轻松使用它。
- 仅需 32 KB RAM 和 128 KB Flash，一个帧缓冲区，以及至少 1/10 屏幕大小的渲染缓冲区。
- 支持使用可选的操作系统、外部存储器和 GPU。
**控件、样式、布局等**
- 30+ 内置\ `控件 <https://docs.lvgl.io/master/widgets/index.html>`__:
- 30+ 内置\ `控件 <https://docs.lvgl.io/master/details/widgets/index.html>`__:
 按钮、标签、滑块、图表、键盘、仪表、弧形、表格等等。
- 灵活的\ `样式系统 <https://docs.lvgl.io/master/overview/style.html>`__
- 灵活的\ `样式系统 <https://docs.lvgl.io/master/details/base-widget/styles/style.html>`__
支持约 100 个样式属性，可在任何状态下自定义控件的任何部分。
- `Flex 布局 <https://docs.lvgl.io/master/layouts/flex.html>`__ 和
`Grid 布局 <https://docs.lvgl.io/master/layouts/grid.html>`__
- `Flex 布局 <https://docs.lvgl.io/master/details/base-widget/layouts/flex.html>`__ 和
`Grid 布局 <https://docs.lvgl.io/master/details/base-widget/layouts/grid.html>`__
可以响应式自动调整控件的大小和位置。
- 文本支持 UTF-8 编码，支持 CJK、泰语、印地语、阿拉伯语和波斯语书写系统。
- 支持自动换行、字距调整、文本滚动、亚像素渲染、拼音输入法、文本表情符号。
- 渲染引擎支持动画、抗锯齿、不透明度、平滑滚动、阴影、图形变换等。
- 支持鼠标、触摸板、小键盘、键盘、外部按钮、编码器\ `输入设备 <https://docs.lvgl.io/master/porting/indev.html>`__\ 。
- 支持\ `多显示器 <https://docs.lvgl.io/master/overview/display.html#multiple-display-support>`__\ 。
- 支持鼠标、触摸板、小键盘、键盘、外部按钮、编码器\ `输入设备 <https://docs.lvgl.io/master/details/modules/indev.html>`__\ 。
- 支持\ `多显示器 <https://docs.lvgl.io/master/details/modules/display.html#multiple-display-support>`__\ 。
**绑定和构建支持**
@ -99,7 +99,7 @@ RAM 和 128 KB Flash、C 编译器、帧缓冲区和至少 1/10 屏幕大小的
- `PikaScript 绑定 <https://blog.lvgl.io/2022-08-24/pikascript-and-lvgl>`__
在 MCU 上的更轻更简单的 Python 版本
- 未使用自定义生成系统。您可以在构建项目的其他文件时构建 LVGL。
- 支持开箱即用的 Make 和 \ `CMake <https://docs.lvgl.io/master/integration/building/cmake.html>`__\ 编译系统。
- 支持开箱即用的 Make 和 \ `CMake <https://docs.lvgl.io/master/details/integration/building/cmake.html>`__\ 编译系统。
- 支持在 \ `PC 上开发 <https://docs.lvgl.io/master/integration/ide/pc-simulator.html>`__\ ，并可以在嵌入式硬件上使用相同的 UI 代码。
- 支持使用我们的 \ `Emscripten 移植 <https://github.com/lvgl/lv_web_emscripten>`__\ 从而将 C 写的 UI 代码转换为 HTML 文件。
@ -183,7 +183,7 @@ Hello world 标签
.. code-block:: c
/*Change the active screen's background color*/
/* Change Active Screen's background color */
lv_obj_set_style_bg_color(lv_screen_active(), lv_color_hex(0x003a57), LV_PART_MAIN);
/*Create a white label, set its text and align it to the center*/
@ -203,7 +203,7 @@ Hello world 标签
.. code-block:: python
# Change the active screen's background color
# Change Active Screen's background color
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x003a57), lv.PART.MAIN)
@ -400,7 +400,7 @@ Hello world 标签
/*Add the style sheet to the slider's INDICATOR part*/
lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR);
/*Add the same style to the KNOB part too and locally overwrite some properties*/
/*Add the same style to the KNOB part as well and locally overwrite some properties*/
lv_obj_add_style(slider, &style_indicator, LV_PART_KNOB);
lv_obj_set_style_outline_color(slider, lv_color_hex(0x0096FF), LV_PART_KNOB);
@ -448,7 +448,7 @@ Hello world 标签
slider.add_style(style_indicator, lv.PART.INDICATOR)
slider.add_style(style_indicator, lv.PART.KNOB)
# Add the same style to the KNOB part too and locally overwrite some properties
# Add the same style to the KNOB part as well and locally overwrite some properties
slider.set_style_outline_color(lv.color_hex(0x0096FF), lv.PART.KNOB)
slider.set_style_outline_width(3, lv.PART.KNOB)
slider.set_style_outline_pad(-5, lv.PART.KNOB)
@ -540,19 +540,19 @@ Hello world 标签
1. 查看\ `在线演示 <https://lvgl.io/demos>`__\ ，了解 LVGL 的实际操作（3 分钟）
2. 阅读\ `文档 <https://docs.lvgl.io/master/intro/index.html>`__\ 的简介页（5 分钟）
3. 熟悉\ `快速概览 <https://docs.lvgl.io/master/get-started/quick-overview.html>`__
3. 熟悉\ `快速概览 <https://docs.lvgl.io/master/intro/overview.html>`__
页面上的基本知识（15 分钟）
**开始使用 LVGL**
4. 设置\ `模拟器 <https://docs.lvgl.io/master/integration/ide/pc-simulator.html#simulator>`__ （10 分钟）
5. 尝试一些\ `示例 <https://github.com/lvgl/lvgl/tree/master/examples>`__
6. 将LVGL端口连接到线路板。请参阅\ `移植 <https://docs.lvgl.io/master/porting/index.html>`__\ 指南，或查看现成的\ `项目 <https://github.com/lvgl?q=lv_port_>`__
6. 将LVGL端口连接到线路板。请参阅\ `移植 <https://docs.lvgl.io/master/intro/add-lvgl-to-your-project/index.html>`__\ 指南，或查看现成的\ `项目 <https://github.com/lvgl?q=lv_port_>`__
**成为专业人士**
7. 阅读\ `概述 <https://docs.lvgl.io/master/overview/index.html>`__\ 页面以更好地了解图书馆（2-3 小时）
8. 查看\ `控件 <https://docs.lvgl.io/master/widgets/index.html>`__\ 的文档以查看其功能和用法
7. 阅读\ `概述 <https://docs.lvgl.io/master/details/modules/index.html>`__\ 页面以更好地了解图书馆（2-3 小时）
8. 查看\ `控件 <https://docs.lvgl.io/master/details/widgets/index.html>`__\ 的文档以查看其功能和用法
**获得帮助并帮助他人**

8
docs/ROADMAP.rst
View File

@ -50,12 +50,12 @@ Architecture
(see `here <https://github.com/lvgl/lvgl/pull/3390#pullrequestreview-990710921>`__)
- |check| Make LVGL render independent areas in parallel.
`#4016 <https://github.com/lvgl/lvgl/issues/4016>`__
- |check| Drop `lv_mem_buf_get` as tlsf should be fast enough for normal allocations too.
- |check| Drop `lv_mem_buf_get` as tlsf should be fast enough for normal allocations as well.
Fragmentation is also lower if processes can completely clean up after themselves.
- |check| More color formats: 24 bit, ARGB1555, ARGB4444 etc
(see `here <https://forum.lvgl.io/t/keypad-input-device-why-lv-event-long-pressed-only-on-enter/10263>`__)
- |check| Unified caching #3116 #3415
- |check| Variable binding. I.e create properties which can be bound to objects and those objects are notified on value change. Maybe based on `lv_msg`?
- |check| Variable binding. I.e create properties which can be bound to Widgets and those Widgets are notified on value change. Maybe based on `lv_msg`?
- |uncheck| Add GPU abstraction for display rotation
- |check| Replace the `read_line_cb` of the image decoders with `get_area_cb`
- |check| Limit the image caching size in bytes instead of image count
@ -144,7 +144,7 @@ Widgets
- |uncheck| `lv_bar`, `lv_arc`: handle max < min for fill direction swapping #4039
- |uncheck| `lv_bar`, `lv_slider`, `lv_arc`: make possible to move the knob only inside the background (see `here <https://forum.lvgl.io/t/slider-knob-out-of-the-track/11956>`__)
- |uncheck| Improve `lv_label_align_t` #1656
- |uncheck| `lv_label` reconsider label long modes. (support min/max-width/height too) #3420
- |uncheck| `lv_label` reconsider label long modes. (support min/max-width/height as well) #3420
- |uncheck| `lv_roller` make it more flexible #4009
Others
@ -164,7 +164,7 @@ Ideas
- Reconsider how themes should work.
- Better way to reset global variables in `lv_deinit()` #3385
- `lv_array`: replace linked lists with array where possible (arrays are faster and uses less memory)
- Reconsider how to handle UTF-8 characters (allow different encoding too) and Bidi. Maybe create an abstraction for textshaping.
- Reconsider how to handle UTF-8 characters (allow different encoding as well) and Bidi. Maybe create an abstraction for textshaping.
- Consider direct binary font format support
- Improve groups. `Discussion <https://forum.lvgl.io/t/lv-group-tabindex/2927/3>`__.
Reconsider focusing logic. Allow having no widget selected (on web it's possible). Keep editing state in `lv_obj_t`

8
docs/_ext/link_roles.py
View File

@ -37,10 +37,12 @@ class TranslationLinkNodeTransform(SphinxPostTransform):
(language, link_text) = text.split(':')
env = self.document.settings.env
docname = env.docname
#doc_path = env.doc2path(docname, False)
urlpath = os.environ['LVGL_URLPATH']+'/'
# doc_path = env.doc2path(docname, False)
if "LVGL_URLPATH" not in os.environ:
os.environ['LVGL_URLPATH'] = 'master'
urlpath = os.getenv('LVGL_URLPATH')+'/'
return_path = URL_BASE.get(language, "") + urlpath
url = '{}.html'.format(os.path.join(return_path, docname))
node.replace_self(nodes.reference(rawtext, link_text, refuri=url, **options))

20
docs/_ext/lv_example.py
View File

@ -106,7 +106,25 @@ class LvExample(Directive):
def setup(app):
app.add_directive("lv_example", LvExample)
app.add_config_value("repo_commit_hash", "", "env")
# Direct [View on GitHub] links in examples to use current
# branch (stored in LVGL_GITCOMMIT environment variable) instead
# of the current commit hash as was being done previously.
# Default to 'master' if Sphinx is being run outside of `build.py`.
# Resulting example link:
# [https://github.com/lvgl/lvgl/blob/master/examples/anim/lv_example_anim_1.c].
# [https://github.com/lvgl/lvgl/blob/v8.4.0/examples/anim/lv_example_anim_1.c].
# [https://github.com/lvgl/lvgl/blob/v9.2.0/examples/anim/lv_example_anim_1.c].
if 'LVGL_GITCOMMIT' in os.environ:
git_commit = os.environ['LVGL_GITCOMMIT']
else:
git_commit = 'master'
app.add_config_value("repo_commit_hash", git_commit, "env")
# if 'repo_commit_hash' in app.config._options:
# print(f"repo_commit_hash from lv_example.py: [{app.config._options['repo_commit_hash']}]")
# else:
# print("repo_commit_hash not found in [app.config._options] at this time.")
return {
'version': '0.1',

BIN
docs/_static/img/gh-header.webp vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 127 KiB

BIN
docs/_static/img/home_1.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 9.6 KiB

BIN
docs/_static/img/home_2.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 9.4 KiB

BIN
docs/_static/img/home_3.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/_static/img/home_4.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/_static/img/home_5.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 11 KiB

305
docs/build.py
View File

@ -17,25 +17,113 @@ import tempfile
import config_builder
import add_translation
# due to the modifications that take place to the documentation files
# -------------------------------------------------------------------------
# Process args.
#
# Normal usage:
# $ python build.py skip_latex
#
# Other optional arguments are meant for doc development to speed up
# turn-around time between doc modification and seeing the final results:
#
# - skip_api
# Skips generating API pages (this saves about 70% of build time).
# This is intended to be used only during doc development to speed up
# turn-around time between doc modifications and seeing final results.
# - no_fresh_env
# excludes -E command-line argument to `sphinx-build`, which forces
# generating a whole new environment (memory of what was built
# previously, forcing a full rebuild). "no_fresh_env" enables a
# rebuild of only docs that got updated -- Sphinx's default behavior.
# - develop
# Leaves temporary directory intact for docs development purposes.
# - fixed_tmp_dir
# If (fixed_tmp_dir and 'LVGL_FIXED_TEMP_DIR' in os.environ),
# then the temporary directory in the value of that environment
# variable will be used instead of the normal (randomly-named)
# temporary directory. This is important when getting `sphinx-build`
# to ONLY rebuild updated documents, since changing the directory
# from which they are generated (normally the randomly-named temp
# dir) will force Sphinx to do a full-rebuild because it remembers
# the doc paths from which the build was last generated.
# - docs_dev
# Forces "fresh_env" to False, and "fixed_tmp_dir" to True. This is
# merely a shortcut to having both "no_fresh_env" and "fixed_tmp_dir"
# on the command line.
# - skip_trans
# Skips adding translation links. This allows direct copying of
# of .RST files to `temp_directory` when they are updated to save
# time during re-build. Final build must not include this option
# so that the translation links are added at the top of each page.
#
# With arguments [skip_latex, develop, docs_dev], Sphinx will generate
# docs from a fixed temporary directory that can be then used later from
# the LVGL ./docs/ directory like this:
#
# $ sphinx-build -b html "fixed_temp_dir" "..\out_html" -D version="9.3" -j cpu_count
#
# to only rebuild docs that have been updated.
# -------------------------------------------------------------------------
clean = 0
skip_latex = False
skip_api = False
fresh_env = True
develop = False
fixed_tmp_dir = False
docs_dev = False
skip_trans = False
args = sys.argv[1:]
if len(args) >= 1:
if "clean" in args:
clean = 1
if "skip_latex" in args:
skip_latex = True
if 'skip_api' in args:
skip_api = True
if 'no_fresh_env' in args:
fresh_env = False
if 'develop' in args:
develop = True
if 'fixed_tmp_dir' in args:
fixed_tmp_dir = True
if 'docs_dev' in args:
docs_dev = True
if 'skip_trans' in args:
skip_trans = True
# Arg ramifications...
# docs_dev implies no fresh_env
if docs_dev:
fresh_env = False
fixed_tmp_dir = True
# -------------------------------------------------------------------------
# Due to the modifications that take place to the documentation files
# when the documentation builds it is better to copy the source files to a
# temporary folder and modify the copies. Not setting it up this way makes it
# a real headache when making alterations that need to be committed as the
# alterations trigger the files as changed.
# If there is debugging that needs to be done you can provide a command line
# switch of "develop" and it will leave the temporary directory in tact and
# that directory will be output at the end of the build.
# the html and PDF output locations are going to remain the same as they were.
# alterations trigger the files as changed. Also, this keeps maintenance
# effort to a minimum as adding a new language translation only needs to be
# done in 2 places (add_translation.py and ./docs/_ext/link_roles.py) rather
# than once for each .rst file.
#
# The html and PDF output locations are going to remain the same as they were.
# it's just the source documentation files that are going to be copied.
# -------------------------------------------------------------------------
if fixed_tmp_dir and 'LVGL_FIXED_TEMP_DIR' in os.environ:
temp_directory = os.environ['LVGL_FIXED_TEMP_DIR']
else:
temp_directory = tempfile.mkdtemp(suffix='.lvgl_docs')
temp_directory = tempfile.mkdtemp(suffix='.lvgl_docs')
print(f'Using temp directory: [{temp_directory}]')
langs = ['en']
# Change to script directory for consistency
# -------------------------------------------------------------------------
# Set up paths.
# -------------------------------------------------------------------------
base_path = os.path.abspath(os.path.dirname(__file__))
project_path = os.path.abspath(os.path.join(base_path, '..'))
examples_path = os.path.join(project_path, 'examples')
@ -48,24 +136,14 @@ pdf_dst_file = os.path.join(temp_directory, 'LVGL.pdf')
html_src_path = temp_directory
html_dst_path = os.path.join(project_path, 'out_html')
# -------------------------------------------------------------------------
# Change to script directory for consistency.
# -------------------------------------------------------------------------
os.chdir(base_path)
clean = 0
trans = 0
skip_latex = False
develop = False
args = sys.argv[1:]
if len(args) >= 1:
if "clean" in args:
clean = 1
if "skip_latex" in args:
skip_latex = True
if 'develop' in args:
develop = True
# -------------------------------------------------------------------------
# Provide a way to run an external command and abort build on error.
# -------------------------------------------------------------------------
def cmd(s, start_dir=None):
if start_dir is None:
start_dir = os.getcwd()
@ -79,18 +157,32 @@ def cmd(s, start_dir=None):
os.chdir(saved_dir)
if result != 0:
print("Exit build due to previous error")
print("Exiting build due to previous error.")
sys.exit(result)
# Get the current branch name
# -------------------------------------------------------------------------
# Get current branch name
# -------------------------------------------------------------------------
# 03-Oct-2024: Gabor requested this be changed to a branch name
# since that will always be current, and it will fix a large number
# of broken links on the docs website. This gets used in the
# 'Edit on GitHub' links in the upper-right corner of pages.
# Original code:
# status, br = subprocess.getstatusoutput("git branch --show-current")
# _, gitcommit = subprocess.getstatusoutput("git rev-parse HEAD")
# br = re.sub(r'\* ', '', br)
status, br = subprocess.getstatusoutput("git branch --show-current")
_, gitcommit = subprocess.getstatusoutput("git rev-parse HEAD")
br = re.sub(r'\* ', '', br)
# If in an unusual branch that is not 'master' or 'release/...'
# then default to 'master'.
if '/' in br and 'release' not in br:
br = 'master'
gitcommit = br
urlpath = re.sub('release/', '', br)
# These environment variables are used in other scripts.
os.environ['LVGL_URLPATH'] = urlpath
os.environ['LVGL_GITCOMMIT'] = gitcommit
@ -101,8 +193,9 @@ print("****************")
print("Building")
print("****************")
# Remove all previous output files if 'clean' on command line.
if clean:
print('cleaning...')
print('Removing previous output files...')
# api_path = os.path.join(dname, 'API')
# xml_path = os.path.join(dname, 'xml')
# doxy_path = os.path.join(dname, 'doxygen_html')
@ -125,11 +218,21 @@ if clean:
# os.mkdir(api_path)
# os.mkdir(lang)
# -------------------------------------------------------------------------
# Build local lv_conf.h from lv_conf_template.h for this build only.
# -------------------------------------------------------------------------
config_builder.run()
# -------------------------------------------------------------------------
# Copy files to 'temp_directory' where they will be edited
# (translation link and API links) before being used to generate new docs.
# -------------------------------------------------------------------------
shutil.copytree('.', temp_directory, dirs_exist_ok=True)
shutil.copytree(examples_path, os.path.join(temp_directory, 'examples'))
shutil.copytree(examples_path, os.path.join(temp_directory, 'examples'), dirs_exist_ok=True)
# -------------------------------------------------------------------------
# Replace tokens in Doxyfile in 'temp_directory' with data from this run.
# -------------------------------------------------------------------------
with open(os.path.join(temp_directory, 'Doxyfile'), 'rb') as f:
data = f.read().decode('utf-8')
@ -139,35 +242,69 @@ data = data.replace('*#*#SRC#*#*', '"{0}"'.format(lvgl_src_path))
with open(os.path.join(temp_directory, 'Doxyfile'), 'wb') as f:
f.write(data.encode('utf-8'))
print("Generate the list of examples")
# -------------------------------------------------------------------------
# Generate examples pages.
# -------------------------------------------------------------------------
print("Generating examples...")
ex.exec(temp_directory)
print("Add translation")
add_translation.exec(temp_directory)
if skip_trans:
print("Skipping translation links as requested.")
else:
# ---------------------------------------------------------------------
# Add translation links at top of all .rst files.
# ---------------------------------------------------------------------
print("Adding translation links...")
add_translation.exec(temp_directory)
print("Running doxygen")
cmd('doxygen Doxyfile', temp_directory)
if skip_api:
print("Skipping API generation as requested.")
else:
# ---------------------------------------------------------------------
# Generate API pages and links thereto.
# ---------------------------------------------------------------------
print("Running Doxygen...")
cmd('doxygen Doxyfile', temp_directory)
print("Generating API documentation .RST files...")
print('Reading Doxygen output')
doc_builder.EMIT_WARNINGS = False
doc_builder.EMIT_WARNINGS = False
# Create .RST files for API pages.
doc_builder.run(
project_path,
temp_directory,
os.path.join(temp_directory, 'intro'),
os.path.join(temp_directory, 'intro', 'add-lvgl-to-your-project'),
os.path.join(temp_directory, 'details'),
os.path.join(temp_directory, 'details', 'base-widget'),
os.path.join(temp_directory, 'details', 'base-widget', 'layouts'),
os.path.join(temp_directory, 'details', 'base-widget', 'styles'),
os.path.join(temp_directory, 'details', 'debugging'),
os.path.join(temp_directory, 'details', 'integration'),
os.path.join(temp_directory, 'details', 'integration', 'bindings'),
os.path.join(temp_directory, 'details', 'integration', 'building'),
os.path.join(temp_directory, 'details', 'integration', 'chip'),
os.path.join(temp_directory, 'details', 'integration', 'driver'),
os.path.join(temp_directory, 'details', 'integration', 'driver', 'display'),
os.path.join(temp_directory, 'details', 'integration', 'driver', 'touchpad'),
os.path.join(temp_directory, 'details', 'integration', 'framework'),
os.path.join(temp_directory, 'details', 'integration', 'ide'),
os.path.join(temp_directory, 'details', 'integration', 'os'),
os.path.join(temp_directory, 'details', 'integration', 'os', 'yocto'),
os.path.join(temp_directory, 'details', 'integration', 'renderers'),
os.path.join(temp_directory, 'details', 'libs'),
os.path.join(temp_directory, 'details', 'main-components'),
os.path.join(temp_directory, 'details', 'other-components'),
os.path.join(temp_directory, 'details', 'widgets')
)
doc_builder.run(
project_path,
temp_directory,
os.path.join(temp_directory, 'layouts'),
os.path.join(temp_directory, 'libs'),
os.path.join(temp_directory, 'others'),
os.path.join(temp_directory, 'overview'),
os.path.join(temp_directory, 'overview', 'renderers'),
os.path.join(temp_directory, 'porting'),
os.path.join(temp_directory, 'widgets')
)
print('Reading Doxygen output...')
# we make sure to remove the link to the PDF before the PDF get generated
# -------------------------------------------------------------------------
# We make sure to remove the link to the PDF before the PDF get generated
# doesn't make any sense to have a link to the PDF in the PDF. The link gets
# added if there is a PDF build so the HTML build will have the link.
# -------------------------------------------------------------------------
index_path = os.path.join(temp_directory, 'index.rst')
with open(index_path, 'rb') as f:
@ -181,11 +318,12 @@ if 'PDF version: :download:`LVGL.pdf <LVGL.pdf>`' in index_data:
with open(index_path, 'wb') as f:
f.write(index_data.encode('utf-8'))
# -------------------------------------------------------------------------
# BUILD PDF
# -------------------------------------------------------------------------
if skip_latex:
print("skipping latex build as requested")
print("Skipping latex build as requested.")
else:
# Silly workaround to include the more or less correct
# PDF download link in the PDF
# cmd("cp -f " + lang +"/latex/LVGL.pdf LVGL.pdf | true")
@ -212,9 +350,10 @@ else:
with open(index_path, 'wb') as f:
f.write(index_data.encode('utf-8'))
# -------------------------------------------------------------------------
# BUILD HTML
# This version of get_version() works correctly under Windows and Linux.
# Credit: @kdschlosser
# -------------------------------------------------------------------------
# This version of get_version() also works correctly under Windows.
def get_version():
path = os.path.join(project_path, 'lv_version.h')
with open(path, 'rb') as fle:
@ -230,17 +369,39 @@ def get_version():
return f'{major.strip()}.{minor.strip()}'
cmd('sphinx-build -b html "{src}" "{dst}" -D version="{version}" -E -j {cpu}'.format(
src=html_src_path,
dst=html_dst_path,
version=get_version(),
cpu=os.cpu_count()
))
if develop:
print('temp directory:', temp_directory)
# -------------------------------------------------------------------------
# Run Sphinx after determining whether to use -E (fresh environment)
# command-line argument.
# -------------------------------------------------------------------------
if fresh_env:
# Uses -E option (same as --fresh-env). Forces sphinx-build to rebuild sphinx
# environment so that all docs are fully regenerated, even if they have not changed.
print("Regenerating all files...")
cmd('sphinx-build -b html "{src}" "{dst}" -D version="{version}" -E -j {cpu}'.format(
src=html_src_path,
dst=html_dst_path,
version=get_version(),
cpu=os.cpu_count()
))
else:
# Does not use -E option (same as --fresh-env).
print("Regenerating only updated files...")
cmd('sphinx-build -b html "{src}" "{dst}" -D version="{version}" -j {cpu}'.format(
src=html_src_path,
dst=html_dst_path,
version=get_version(),
cpu=os.cpu_count()
))
# -------------------------------------------------------------------------
# If 'develop' was specified on command line, announce location of temp dir.
# Otherwise, remove temporary files created for the doc build.
# -------------------------------------------------------------------------
if develop:
print('Temp directory: ', temp_directory)
else:
print('Removing temporary files...', temp_directory)
# Recursively remove generated files in `temp_directory`.
def iter_temp(p):
folders = []
remove_folder = True
@ -268,7 +429,13 @@ else:
iter_temp(temp_directory)
# -------------------------------------------------------------------------
# Remove temporary `lv_conf.h` created for this build.
# -------------------------------------------------------------------------
config_builder.cleanup()
print('output path:', html_dst_path)
print('\nFINISHED!!')
# -------------------------------------------------------------------------
# Indicate results.
# -------------------------------------------------------------------------
print('Output path: ', html_dst_path)
print('Finished.')

53
docs/conf.py
View File

@ -44,7 +44,8 @@ extensions = [
'sphinx_design',
'sphinx_rtd_dark_mode',
'link_roles',
'sphinxcontrib.mermaid'
'sphinxcontrib.mermaid',
'sphinx_reredirects'
]
default_dark_mode = False
@ -61,7 +62,7 @@ highlight_language = 'c'
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst']
source_suffix = {'.rst': 'restructuredtext'}
# The master toctree document.
@ -78,7 +79,8 @@ author = 'LVGL community'
# built documents.
#
# The short X.Y version.
# embeddedt: extract using scripts/find_version.sh
# `version` is extracted from lv_version.h using a cross-platform compatible
# Python function in build.py, and passed in on `sphinx-build` command line.
version = ''
@ -114,9 +116,12 @@ html_theme = 'sphinx_rtd_theme'
# documentation.
#
# Note: 'display_version' option is now obsolete in the current (08-Oct-2024)
# version of sphinx-rtd-theme (upgraded for Sphinx v8.x). The removed line is
# preserved by commenting it out in case it is ever needed again.
html_theme_options = {
'display_version': True,
# 'display_version': True,
'prev_next_buttons_location': 'both',
'style_external_links': False,
# 'vcs_pageview_mode': '',
@ -133,7 +138,12 @@ html_theme_options = {
# For site map generation
html_baseurl = f"https://docs.lvgl.io/{os.environ['LVGL_URLPATH']}/"
if "LVGL_URLPATH" not in os.environ:
os.environ['LVGL_URLPATH'] = 'master'
_branch = os.getenv('LVGL_URLPATH')
html_baseurl = f"https://docs.lvgl.io/{_branch}/"
sitemap_url_scheme = "{link}"
@ -141,8 +151,13 @@ sitemap_url_scheme = "{link}"
#extlinks = {'github_link_base': (github_url + '%s', github_url)}
if "LVGL_GITCOMMIT" not in os.environ:
os.environ['LVGL_GITCOMMIT'] = 'master'
_git_commit_ref = os.getenv('LVGL_GITCOMMIT')
html_context = {
'github_version': os.environ['LVGL_GITCOMMIT'],
'github_version': _git_commit_ref,
'github_user': 'lvgl',
'github_repo': 'lvgl',
'display_github': True,
@ -260,10 +275,30 @@ StandaloneHTMLBuilder.supported_image_types = [
'image/jpeg'
]
smartquotes = False
repo_commit_hash = os.environ['LVGL_GITCOMMIT']
# Enabling smart quotes action to convert -- to en dashes and --- to em dashes.
# Converting quotation marks and ellipses is NOT done because the default
# `smartquotes_action` 'qDe' is changed to just 'D' below, which accomplishes
# the dash conversions as desired.
smartquotes = True
smartquotes_action = 'D'
repo_commit_hash = _git_commit_ref
# -- Options for sphinx_reredirects ---------------------------------------
# The below generates .HTML page redirects for pages that have been moved.
# Browsers are redirected via `<meta http-equiv="refresh" content="0; url=new_url">`.
redirects = {
"get-started/index": "../intro/basics.html#going-deeper" ,
"integration/index": "../details/integration/index.html" ,
"porting/index": "../intro/add-lvgl-to-your-project/index.html",
"overview/index": "../details/main-components/index.html" ,
"layouts/index": "../details/base-widget/layouts/index.html" ,
"libs/index": "../details/libs/index.html" ,
"others/index": "../details/other-components/index.html"
}
# Example configuration for intersphinx: refer to the Python standard library.
@ -275,3 +310,5 @@ def setup(app):
# app.add_transform(AutoStructify)
app.add_css_file('css/custom.css')
app.add_css_file('css/fontawesome.min.css')

10
docs/config_builder.py
View File

@ -1,4 +1,12 @@
"""
Create lv_conf.h in same directory as this file
from ../lv_conf_template.h that has:
1. all its #define LV_USE... 0-or-1 options set to 1
(except for LV_USER_PROFILER),
2. all its #define LV_FONT... 0-or-1 options set to 1,
3. its #if 0 directive set to #if 1.
"""
import os
base_path = os.path.dirname(__file__)
@ -25,7 +33,7 @@ def run(c_path=None):
if 'LV_USE_PROFILER' in line:
continue
if 'LV_USE' in line or 'LV_FONT' in line and '#define' in line:
if 'LV_USE' in line or ('LV_FONT' in line and '#define' in line):
line = [item for item in line.split(' ') if item]
for j, item in enumerate(line):

284
docs/overview/coord.rst → docs/details/base-widget/coord.rst
View File

@ -1,66 +1,69 @@
.. _coord:
=============================
Positions, sizes, and layouts
=============================
============================
Positions, Sizes and Layouts
============================
Overview
********
Similarly to many other parts of LVGL, the concept of setting the
Similar to many other parts of LVGL, the concept of setting the
coordinates was inspired by CSS. LVGL has by no means a complete
implementation of CSS but a comparable subset is implemented (sometimes
with minor adjustments).
In short this means:
In short this means:
- Explicitly set coordinates are stored in styles (size, position, layouts, etc.)
- Explicitly set coordinates are stored in styles (position, size, layouts, etc.)
- support min-width, max-width, min-height, max-height
- have pixel, percentage, and "content" units
- x=0; y=0 coordinate means the top-left corner of the parent plus the left/top padding plus border width
- width/height means the full size, the "content area" is smaller with padding and border width
- a subset of flexbox and grid layouts are supported
.. _coord_unites:
.. _coord_units:
Units
-----
*****
- pixel: Simply a position in pixels. An integer always means pixels.
E.g. :cpp:expr:`lv_obj_set_x(btn, 10)`
- percentage: The percentage of the size of the object or its parent
- percentage: The percentage of the size of the Widget or its parent
(depending on the property). :cpp:expr:`lv_pct(value)` converts a value to
percentage. E.g. :cpp:expr:`lv_obj_set_width(btn, lv_pct(50))`
- :c:macro:`LV_SIZE_CONTENT`: Special value to set the width/height of an
object to involve all the children. It's similar to ``auto`` in CSS.
Widget to involve all the children. It's similar to ``auto`` in CSS.
E.g. :cpp:expr:`lv_obj_set_width(btn, LV_SIZE_CONTENT)`.
.. _coord_boxing_model:
Boxing model
------------
************
LVGL follows CSS's `border-box <https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing>`__
model. An object's "box" is built from the following parts:
model. A Widget's "box" is built from the following parts:
- bounding box: the width/height of the elements.
- border width: the width of the border.
- padding: space between the sides of the object and its children.
- margin: space outside of the object (considered only by some layouts)
- padding: space between the sides of the Widget and its children.
- margin: space outside of the Widget (considered only by some layouts)
- content: the content area which is the size of the bounding box reduced by the border width and padding.
.. image:: /misc/boxmodel.png
:alt: The box models of LVGL: The content area is smaller than the bounding box with the padding and border width
The border is drawn inside the bounding box. Inside the border LVGL
keeps a "padding margin" when placing an object's children.
keeps a "padding margin" when placing a Widget's children.
The outline is drawn outside the bounding box.
.. _coord_notes:
Important notes
---------------
Important Notes
***************
This section describes special cases in which LVGL's behavior might be
unexpected.
@ -68,45 +71,45 @@ unexpected.
.. _coord_postponed_coordinate_calculation:
Postponed coordinate calculation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
--------------------------------
LVGL doesn't recalculate all the coordinate changes immediately. This is
done to improve performance. Instead, the objects are marked as "dirty"
done to improve performance. Instead, the Widgets are marked as "dirty"
and before redrawing the screen LVGL checks if there are any "dirty"
objects. If so it refreshes their position, size and layout.
Widgets. If so it refreshes their position, size and layout.
In other words, if you need to get the coordinate of an object and the
In other words, if you need to get the coordinate of a Widget and the
coordinates were just changed, LVGL needs to be forced to recalculate
the coordinates. To do this call :cpp:func:`lv_obj_update_layout`.
The size and position might depend on the parent or layout. Therefore
:cpp:func:`lv_obj_update_layout` recalculates the coordinates of all objects on
:cpp:func:`lv_obj_update_layout` recalculates the coordinates of all Widgets on
the screen of ``obj``.
.. _coord_removing styles:
Removing styles
^^^^^^^^^^^^^^^
---------------
As it's described in the :ref:`coord_using_styles` section,
coordinates can also be set via style properties. To be more precise,
under the hood every style coordinate related property is stored as a
style property. If you use :cpp:expr:`lv_obj_set_x(obj, 20)` LVGL saves ``x=20``
in the local style of the object.
style property. If you use :cpp:expr:`lv_obj_set_x(widget, 20)` LVGL saves ``x=20``
in the local style of the Widget.
This is an internal mechanism and doesn't matter much as you use LVGL.
However, there is one case in which you need to be aware of the
implementation. If the style(s) of an object are removed by
implementation. If the style(s) of a Widget are removed by
.. code-block:: c
lv_obj_remove_style_all(obj)
lv_obj_remove_style_all(widget)
or
.. code-block:: c
lv_obj_remove_style(obj, NULL, LV_PART_MAIN);
lv_obj_remove_style(widget, NULL, LV_PART_MAIN);
the earlier set coordinates will be removed as well.
@ -114,30 +117,33 @@ For example:
.. code-block:: c
/*The size of obj1 will be set back to the default in the end*/
lv_obj_set_size(obj1, 200, 100); /*Now obj1 has 200;100 size*/
lv_obj_remove_style_all(obj1); /*It removes the set sizes*/
/* The size of obj1 will be set back to the default in the end */
lv_obj_set_size(widget1, 200, 100); /* Now obj1 has 200;100 size */
lv_obj_remove_style_all(widget1); /* It removes the set sizes */
/*obj2 will have 200;100 size in the end */
lv_obj_remove_style_all(obj2);
lv_obj_set_size(obj2, 200, 100);
/* widget2 will have 200;100 size in the end */
lv_obj_remove_style_all(widget2);
lv_obj_set_size(widget2, 200, 100);
.. _coord_position:
Position
********
Simple way
----------
.. _positioning_widgets:
To simply set the x and y coordinates of an object use:
Positioning Widgets
*******************
Direct
------
To simply set the x and y coordinates of a Widget use:
.. code-block:: c
lv_obj_set_x(obj, 10); //Separate...
lv_obj_set_y(obj, 20);
lv_obj_set_pos(obj, 10, 20); //Or in one function
lv_obj_set_x(widget, 10); /* Separate... */
lv_obj_set_y(widget, 20);
lv_obj_set_pos(widget, 10, 20); /* Or in one function */
By default, the x and y coordinates are measured from the top left
corner of the parent's content area. For example if the parent has five
@ -150,25 +156,31 @@ Percentage values are calculated from the parent's content area size.
lv_obj_set_x(btn, lv_pct(10)); //x = 10 % of parent content area width
Align
-----
In some cases it's convenient to change the origin of the positioning
from the default top left. If the origin is changed e.g. to
bottom-right, the (0,0) position means: align to the bottom-right
corner. To change the origin use:
Alignment
---------
Inside parent widget
~~~~~~~~~~~~~~~~~~~~
In many cases it is more convenient to tell LVGL to align your object relative to
an "anchor point" in its parent *other* than its upper left corner. To establish
that "anchor point", call :cpp:expr:`lv_obj_set_align(widget, LV_ALIGN_...)`. After
that call, that "anchor point" will be remembered until another one is established.
In other words, every futire x and y setting for that Widget will be relative to the
that "anchor point".
Example: Position Widget (10,20) px relative to the center of its parent:
.. code-block:: c
lv_obj_set_align(obj, align);
lv_obj_set_align(widget, LV_ALIGN_CENTER);
lv_obj_set_pos(widget, 10, 20);
To change the alignment and set new coordinates:
/* Or combine the above in one function... */
lv_obj_align(widget, LV_ALIGN_CENTER, 10, 20);
.. code-block:: c
lv_obj_align(obj, align, x, y);
The following alignment options can be used:
9 convenient "anchor points" can be used with these functions:
- :cpp:enumerator:`LV_ALIGN_TOP_LEFT`
- :cpp:enumerator:`LV_ALIGN_TOP_MID`
@ -180,28 +192,31 @@ The following alignment options can be used:
- :cpp:enumerator:`LV_ALIGN_RIGHT_MID`
- :cpp:enumerator:`LV_ALIGN_CENTER`
See illustration below to visualize what these mean.
It's quite common to align a child to the center of its parent,
therefore a dedicated function exists:
.. code-block:: c
lv_obj_center(obj);
lv_obj_center(widget);
//Has the same effect
lv_obj_align(obj, LV_ALIGN_CENTER, 0, 0);
lv_obj_align(widget, LV_ALIGN_CENTER, 0, 0);
If the parent's size changes, the set alignment and position of the
children is updated automatically.
The functions introduced above align the object to its parent. However,
it's also possible to align an object to an arbitrary reference object.
Relative to another Widget
~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternately, you can choose an "anchor point" on another Widget.
.. code-block:: c
lv_obj_align_to(obj_to_align, reference_obj, align, x, y);
lv_obj_align_to(widget, reference_widget, align, x, y);
Besides the alignments options above, the following can be used to align
an object outside the reference object:
where ``align`` can be done of the following:
- :cpp:enumerator:`LV_ALIGN_OUT_TOP_LEFT`
- :cpp:enumerator:`LV_ALIGN_OUT_TOP_MID`
@ -216,67 +231,84 @@ an object outside the reference object:
- :cpp:enumerator:`LV_ALIGN_OUT_RIGHT_MID`
- :cpp:enumerator:`LV_ALIGN_OUT_RIGHT_BOTTOM`
For example to align a label above a button and center the label
horizontally:
Example: to horizontally center a label 10 pixels above a button:
.. code-block:: c
lv_obj_align_to(label, btn, LV_ALIGN_OUT_TOP_MID, 0, -10);
Note that, unlike with :cpp:func:`lv_obj_align`, :cpp:func:`lv_obj_align_to` cannot
realign the object if its coordinates or the reference object's
coordinates change.
Note that, unlike with :cpp:func:`lv_obj_align`, :cpp:func:`lv_obj_align_to`
does not remember the "anchor point" used, and so will not automatically reposition
the aligned widget if the reference widget later moves.
The following illustration shows the meaning of each "anchor point" mentioned above.
.. image:: /misc/align.png
.. _coord_size:
Size
****
Sizing the Simple way
Sizing the simple way
---------------------
The width and the height of an object can be set easily as well:
The width and the height of a Widget can be set easily as well:
.. code-block:: c
lv_obj_set_width(obj, 200); //Separate...
lv_obj_set_height(obj, 100);
lv_obj_set_size(obj, 200, 100); //Or in one function
lv_obj_set_width(widget, 200); /* Separate... */
lv_obj_set_height(widget, 100);
lv_obj_set_size(widget, 200, 100); /* Or in one function */
Percentage values are calculated based on the parent's content area
size. For example to set the object's height to the screen height:
size. For example to set the Widget's height to the screen height:
.. code-block:: c
lv_obj_set_height(obj, lv_pct(100));
lv_obj_set_height(widget, lv_pct(100));
The size settings support a special value: :c:macro:`LV_SIZE_CONTENT`. It means
the object's size in the respective direction will be set to the size of
the Widget's size in the respective direction will be set to the size of
its children. Note that only children on the right and bottom sides will
be considered and children on the top and left remain cropped. This
limitation makes the behavior more predictable.
Objects with :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` or :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` will be
Widgets with :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` or :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` will be
ignored by the :c:macro:`LV_SIZE_CONTENT` calculation.
The above functions set the size of an object's bounding box but the
size of the content area can be set as well. This means an object's
The above functions set the size of a Widget's bounding box but the
size of the content area can be set as well. This means a Widget's
bounding box will be enlarged with the addition of padding.
.. code-block:: c
lv_obj_set_content_width(obj, 50); //The actual width: padding left + 50 + padding right
lv_obj_set_content_height(obj, 30); //The actual width: padding top + 30 + padding bottom
lv_obj_set_content_width(widget, 50); /* The actual width: padding left + 50 + padding right */
lv_obj_set_content_height(widget, 30); /* The actual width: padding top + 30 + padding bottom */
The size of the bounding box and the content area can be retrieved with
the following functions:
.. code-block:: c
int32_t w = lv_obj_get_width(obj);
int32_t h = lv_obj_get_height(obj);
int32_t content_w = lv_obj_get_content_width(obj);
int32_t content_h = lv_obj_get_content_height(obj);
int32_t w = lv_obj_get_width(widget);
int32_t h = lv_obj_get_height(widget);
int32_t content_w = lv_obj_get_content_width(widget);
int32_t content_h = lv_obj_get_content_height(widget);
.. _extending_click_area:
Extending the click area
------------------------
By default, Widgets can be clicked only within their bounding area. However,
especially with small Widgets, it can be helpful to make a Widget's "clickable" area
larger. You can do this with :cpp:expr:`lv_obj_set_ext_click_area(widget, size)`.
.. _coord_using_styles:
@ -286,22 +318,22 @@ Using styles
Under the hood the position, size and alignment properties are style
properties. The above described "simple functions" hide the style
related code for the sake of simplicity and set the position, size, and
alignment properties in the local styles of the object.
alignment properties in the local styles of the Widget.
However, using styles to set the coordinates has some great advantages:
- It makes it easy to set the width/height/etc. for several objects
- It makes it easy to set the width/height/etc. for several Widgets
together. E.g. make all the sliders 100x10 pixels sized.
- It also makes possible to modify the values in one place.
- The values can be partially overwritten by other styles. For example
``style_btn`` makes the object ``100x50`` by default but adding
``style_full_width`` overwrites only the width of the object.
- The object can have different position or size depending on state.
``style_btn`` makes the Widget ``100x50`` by default but adding
``style_full_width`` overwrites only the width of the Widget.
- The Widget can have different position or size depending on state.
E.g. 100 px wide in :cpp:enumerator:`LV_STATE_DEFAULT` but 120 px
in :cpp:enumerator:`LV_STATE_PRESSED`.
- Style transitions can be used to make the coordinate changes smooth.
Here are some examples to set an object's size using a style:
Here are some examples to set a Widget's size using a style:
.. code-block:: c
@ -371,18 +403,18 @@ work as expected. Translations can be used to solve this:
lv_obj_add_style(btn3, &style_normal, LV_STATE_DEFAULT);
lv_obj_add_style(btn3, &style_pressed, LV_STATE_PRESSED);
Translation is applied from the current position of the object.
Translation is applied from the current position of the Widget.
Percentage values can be used in translations as well. The percentage is
relative to the size of the object (and not to the size of the parent).
For example :cpp:expr:`lv_pct(50)` will move the object with half of its
relative to the size of the Widget (and not to the size of the parent).
For example :cpp:expr:`lv_pct(50)` will move the Widget with half of its
width/height.
The translation is applied after the layouts are calculated. Therefore,
even laid out objects' position can be translated.
even laid out Widgets' position can be translated.
The translation actually moves the object. That means it makes the
scrollbars and :c:macro:`LV_SIZE_CONTENT` sized objects react to the position
The translation actually moves the Widget. That means it makes the
scrollbars and :c:macro:`LV_SIZE_CONTENT` sized Widgets react to the position
change.
.. _coord_transformation:
@ -390,13 +422,13 @@ change.
Transformation
**************
Similarly to position, an object's size can be changed relative to the
Similarly to position, a Widget's size can be changed relative to the
current size as well. The transformed width and height are added on both
sides of the object. This means a 10 px transformed width makes the
object 2x10 pixels wider.
sides of the Widget. This means a 10 px transformed width makes the
Widget 2x10 pixels wider.
Unlike position translation, the size transformation doesn't make the
object "really" larger. In other words scrollbars, layouts, and
Widget "really" larger. In other words scrollbars, layouts, and
:c:macro:`LV_SIZE_CONTENT` will not react to the transformed size. Hence, size
transformation is "only" a visual effect.
@ -417,8 +449,8 @@ Min and Max size
----------------
Similarly to CSS, LVGL also supports ``min-width``, ``max-width``,
``min-height`` and ``max-height``. These are limits preventing an
object's size from becoming smaller/larger than these values. They are
``min-height`` and ``max-height``. These are limits preventing a
Widget's size from becoming smaller/larger than these values. They are
especially useful if the size is set by percentage or
:c:macro:`LV_SIZE_CONTENT`.
@ -428,8 +460,8 @@ especially useful if the size is set by percentage or
lv_style_init(&style_max_height);
lv_style_set_y(&style_max_height, 200);
lv_obj_set_height(obj, lv_pct(100));
lv_obj_add_style(obj, &style_max_height, LV_STATE_DEFAULT); //Limit the height to 200 px
lv_obj_set_height(widget, lv_pct(100));
lv_obj_add_style(widget, &style_max_height, LV_STATE_DEFAULT); //Limit the height to 200 px
Percentage values can be used as well which are relative to the size of
the parent's content area.
@ -440,18 +472,21 @@ the parent's content area.
lv_style_init(&style_max_height);
lv_style_set_y(&style_max_height, lv_pct(50));
lv_obj_set_height(obj, lv_pct(100));
lv_obj_add_style(obj, &style_max_height, LV_STATE_DEFAULT); //Limit the height to half parent height
lv_obj_set_height(widget, lv_pct(100));
lv_obj_add_style(widget, &style_max_height, LV_STATE_DEFAULT); //Limit the height to half parent height
.. _coord_layout:
Layout
******
Layout Overview
Layout overview
---------------
Layouts can update the position and size of an object's children. They
Layouts can update the position and size of a Widget's children. They
can be used to automatically arrange the children into a line or column,
or in much more complicated forms.
@ -459,32 +494,35 @@ The position and size set by the layout overwrites the "normal" x, y,
width, and height settings.
There is only one function that is the same for every layout:
:cpp:func:`lv_obj_set_layout` ``(obj, <LAYOUT_NAME>)`` sets the layout on an object.
:cpp:func:`lv_obj_set_layout` ``(widget, <LAYOUT_NAME>)`` sets the layout on a Widget.
For further settings of the parent and children see the documentation of
the given layout.
Built-in layout
---------------
Built-in layouts
----------------
LVGL comes with two very powerful layouts:
* Flexbox: arrange objects into rows or columns, with support for wrapping and expanding items.
* Grid: arrange objects into fixed positions in 2D table.
* Flexbox: arrange Widgets into rows or columns, with support for wrapping and expanding items.
* Grid: arrange Widgets into fixed positions in 2D table.
Both are heavily inspired by the CSS layouts with the same name.
Layouts are described in detail in their own section of documentation.
Flags
-----
There are some flags that can be used on objects to affect how they
There are some flags that can be used on Widgets to affect how they
behave with layouts:
- :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` Hidden objects are ignored in layout calculations.
- :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` The object is simply ignored by the layouts. Its coordinates can be set as usual.
- :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` Same as :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` but the object with :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` will be ignored in :c:macro:`LV_SIZE_CONTENT` calculations.
- :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` Hidden Widgets are ignored in layout calculations.
- :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` The Widget is simply ignored by the layouts. Its coordinates can be set as usual.
- :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` Same as :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` but the Widget with :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` will be ignored in :c:macro:`LV_SIZE_CONTENT` calculations.
These flags can be added/removed with :cpp:expr:`lv_obj_add_flag(widget, FLAG)` and :cpp:expr:`lv_obj_remove_flag(widget, FLAG)`
These flags can be added/removed with :cpp:expr:`lv_obj_add_flag(obj, FLAG)` and :cpp:expr:`lv_obj_remove_flag(obj, FLAG)`
Adding new layouts
------------------
@ -501,9 +539,9 @@ LVGL can be freely extended by a custom layout like this:
...
void my_layout_update(lv_obj_t * obj, void * user_data)
void my_layout_update(lv_obj_t * widget, void * user_data)
{
/*Will be called automatically if it's required to reposition/resize the children of "obj" */
/* Will be called automatically if it's required to reposition/resize the children of "obj" */
}
Custom style properties can be added which can be retrieved and used in
@ -525,11 +563,15 @@ the update callback. For example:
lv_style_set_prop(style, LV_STYLE_MY_PROP, v);
}
.. _coord_example:
Examples
********
.. _coord_api:
API

186
docs/overview/event.rst → docs/details/base-widget/event.rst
View File

@ -5,27 +5,30 @@ Events
======
Events are triggered in LVGL when something happens which might be
interesting to the user, e.g. when an object:
interesting to the user, e.g. when a Widget:
- is clicked
- is scrolled
- has its value changed
- is redrawn, etc.
Besides widgets, events can registered from displays and input devices too.
It's not detailed below, however the same applies to displays and indevs as well
by changing the prefix of the functions from ``lv_obj_`` to ``lv_display_`` or ``lv_indev_``.
Besides Widgets, events can registered from displays and input devices as well.
It is not detailed below, but you can do this by changing the prefix of the functions
from ``lv_obj_`` to ``lv_display_`` or ``lv_indev_``.
Add events to a widget
**********************
The user can assign callback functions to an object to see its events.
.. _adding_events_to_a_widget:
Adding Events to a Widget
*************************
The user can assign callback functions to a widget to process events.
In practice, it looks like this:
.. code-block:: c
lv_obj_t * btn = lv_button_create(lv_screen_active());
lv_obj_add_event_cb(btn, my_event_cb, LV_EVENT_CLICKED, NULL); /*Assign an event callback*/
lv_obj_add_event_cb(btn, my_event_cb, LV_EVENT_CLICKED, user_data); /* Assign an event callback */
...
@ -39,30 +42,37 @@ call ``my_event_cb``. See the :ref:`list of event codes <events_codes>` for
all the options. :cpp:enumerator:`LV_EVENT_ALL` can be used to receive all events.
The last parameter of :cpp:func:`lv_obj_add_event` is a pointer to any custom
data that will be available in the event. It will be described later in
more detail.
More events can be added to an object, like this:
data that will be available in the event. NULL may be passed for this argument if
there is no need to use that data when the event is processed. You can retrieve the
pointer passed when setting the callback function like this:
.. code-block:: c
lv_obj_add_event_cb(obj, my_event_cb_1, LV_EVENT_CLICKED, NULL);
lv_obj_add_event_cb(obj, my_event_cb_2, LV_EVENT_PRESSED, NULL);
lv_obj_add_event_cb(obj, my_event_cb_3, LV_EVENT_ALL, NULL); /*No filtering, receive all events*/
my_user_data_t * user_data;
...
user_data = lv_event_get_user_data(e);
Even the same event callback can be used on an object with different
More events can be added to a Widget, like this:
.. code-block:: c
lv_obj_add_event_cb(widget, my_event_cb_1, LV_EVENT_CLICKED, NULL);
lv_obj_add_event_cb(widget, my_event_cb_2, LV_EVENT_PRESSED, NULL);
lv_obj_add_event_cb(widget, my_event_cb_3, LV_EVENT_ALL, NULL); /* No filtering, receive all events */
Even the same event callback can be used on a Widget with different
``user_data``. For example:
.. code-block:: c
lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num1);
lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num2);
lv_obj_add_event_cb(widget, increment_on_click, LV_EVENT_CLICKED, &num1);
lv_obj_add_event_cb(widget, increment_on_click, LV_EVENT_CLICKED, &num2);
The events will be called in the order as they were added.
Other objects can use the same *event callback*.
Other Widgets can use the same *event callback*.
In the very same way events can attached to the input devices and displays like this
In the very same way, events can be attached to input devices and displays like this:
.. code-block:: c
@ -70,30 +80,31 @@ In the very same way events can attached to the input devices and displays like
lv_indev_add_event_cb(indev, event_cb, LV_EVENT_CLICKED, NULL);
Remove event(s) from widgets
****************************
Removing Event(s) from Widgets
******************************
.. code-block:: c
uint32_t i;
uint32_t event_cnt = lv_obj_get_event_count(obj);
uint32_t event_cnt = lv_obj_get_event_count(widget);
for(i = 0; i < event_cnt; i++) {
lv_event_dsc_t * event_dsc = lv_obj_get_event_dsc(obj, i);
lv_event_dsc_t * event_dsc = lv_obj_get_event_dsc(widget, i);
if(lv_event_dsc_get_cb(event_dsc) == some_event_cb) {
lv_obj_remove_event(obj, i);
lv_obj_remove_event(widget, i);
break;
}
}
.. _events_codes:
Event codes
Event Codes
***********
The event codes can be grouped into these categories: - Input device
events - Drawing events - Other events - Special events - Custom events
All objects (such as Buttons/Labels/Sliders etc.) regardless their type
All Widgets (such as Buttons/Labels/Sliders etc.) regardless their type
receive the *Input device*, *Drawing* and *Other* events.
However, the *Special events* are specific to a particular widget type.
@ -104,40 +115,39 @@ are sent,
The following event codes exist:
Input device events
Input Device Events
-------------------
- :cpp:enumerator:`LV_EVENT_PRESSED`: The object has been pressed
- :cpp:enumerator:`LV_EVENT_PRESSING`: The object is being pressed (called continuously while pressing)
- :cpp:enumerator:`LV_EVENT_PRESS_LOST`: The object is still being pressed but slid cursor/finger off of the object
- :cpp:enumerator:`LV_EVENT_SHORT_CLICKED`: The object was pressed for a short period of time, and then released without scrolling.
- :cpp:enumerator:`LV_EVENT_SINGLE_CLICKED`: The object was pressed for a short period of time, and then released without scrolling, for the first time in a click streak. A click streak refers to multiple short clicks within a short period of time and a small distance.
- :cpp:enumerator:`LV_EVENT_DOUBLE_CLICKED`: The object was pressed for a short period of time, and then released without scrolling, for the second time in a click streak.
- :cpp:enumerator:`LV_EVENT_TRIPLE_CLICKED`: The object was pressed for a short period of time, and then released without scrolling, for the third time in a click streak.
- :cpp:enumerator:`LV_EVENT_LONG_PRESSED`: Object has been pressed for at least `long_press_time`. Not called if scrolled.
- :cpp:enumerator:`LV_EVENT_PRESSED`: Widget has been pressed
- :cpp:enumerator:`LV_EVENT_PRESSING`: Widget is being pressed (called continuously while pressing)
- :cpp:enumerator:`LV_EVENT_PRESS_LOST`: Widget is still being pressed but slid cursor/finger off Widget
- :cpp:enumerator:`LV_EVENT_SHORT_CLICKED`: Widget was pressed for a short period of time, and then released without scrolling.
- :cpp:enumerator:`LV_EVENT_SINGLE_CLICKED`: Widget was pressed for a short period of time, and then released without scrolling, for the first time in a click streak. A click streak refers to multiple short clicks within a short period of time and a small distance.
- :cpp:enumerator:`LV_EVENT_DOUBLE_CLICKED`: Widget was pressed for a short period of time, and then released without scrolling, for the second time in a click streak.
- :cpp:enumerator:`LV_EVENT_TRIPLE_CLICKED`: Widget was pressed for a short period of time, and then released without scrolling, for the third time in a click streak.
- :cpp:enumerator:`LV_EVENT_LONG_PRESSED`: Widget has been pressed for at least `long_press_time`. Not called if scrolled.
- :cpp:enumerator:`LV_EVENT_LONG_PRESSED_REPEAT`: Called after `long_press_time` in every `long_press_repeat_time` ms. Not called if scrolled.
- :cpp:enumerator:`LV_EVENT_CLICKED`: Called on release if not scrolled (regardless of long press)
- :cpp:enumerator:`LV_EVENT_RELEASED`: Called in every cases when the object has been released
- :cpp:enumerator:`LV_EVENT_RELEASED`: Called in every cases when Widget has been released
- :cpp:enumerator:`LV_EVENT_SCROLL_BEGIN`: Scrolling begins. The event parameter is a pointer to the animation of the scroll. Can be modified
- :cpp:enumerator:`LV_EVENT_SCROLL_THROW_BEGIN`:
- :cpp:enumerator:`LV_EVENT_SCROLL_END`: Scrolling ends
- :cpp:enumerator:`LV_EVENT_SCROLL`: Scrolling
- :cpp:enumerator:`LV_EVENT_GESTURE`: A gesture is detected. Get the gesture with :cpp:expr:`lv_indev_get_gesture_dir(lv_indev_active())`
- :cpp:enumerator:`LV_EVENT_KEY`: A key is sent to the object. Get the key with :cpp:expr:`lv_indev_get_key(lv_indev_active())`
- :cpp:enumerator:`LV_EVENT_FOCUSED`: The object is focused
- :cpp:enumerator:`LV_EVENT_DEFOCUSED`: The object is defocused
- :cpp:enumerator:`LV_EVENT_LEAVE`: The object is defocused but still selected
- :cpp:enumerator:`LV_EVENT_KEY`: A key is sent to Widget. Get the key with :cpp:expr:`lv_indev_get_key(lv_indev_active())`
- :cpp:enumerator:`LV_EVENT_FOCUSED`: Widget received focus
- :cpp:enumerator:`LV_EVENT_DEFOCUSED`: Widget is defocused
- :cpp:enumerator:`LV_EVENT_LEAVE`: Widget is defocused but still selected
- :cpp:enumerator:`LV_EVENT_HIT_TEST`: Perform advanced hit-testing
- :cpp:enumerator:`LV_EVENT_INDEV_RESET`: Indev has been reset
- :cpp:enumerator:`LV_EVENT_HOVER_OVER`: Indev hover over object
- :cpp:enumerator:`LV_EVENT_HOVER_LEAVE`: Indev hover leave object
- :cpp:enumerator:`LV_EVENT_HOVER_OVER`: Indev hover over Widget
- :cpp:enumerator:`LV_EVENT_HOVER_LEAVE`: Indev hover leave Widget
Drawing Events
--------------
- :cpp:enumerator:`LV_EVENT_COVER_CHECK`: Check if the object fully covers an area. The event parameter is :cpp:type:`lv_cover_check_info_t` ``*``.
- :cpp:enumerator:`LV_EVENT_REFR_EXT_DRAW_SIZE`: Get the required extra draw area around the object (e.g. for shadow). The event parameter is :cpp:type:`int32_t` ``*`` to store the size.
- :cpp:enumerator:`LV_EVENT_COVER_CHECK`: Check if Widget fully covers an area. The event parameter is :cpp:type:`lv_cover_check_info_t` ``*``.
- :cpp:enumerator:`LV_EVENT_REFR_EXT_DRAW_SIZE`: Get the required extra draw area around Widget (e.g. for shadow). The event parameter is :cpp:type:`int32_t` ``*`` to store the size.
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_BEGIN`: Starting the main drawing phase
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN`: Perform the main drawing
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_END`: Finishing the main drawing phase
@ -146,20 +156,20 @@ Drawing Events
- :cpp:enumerator:`LV_EVENT_DRAW_POST_END`: Finishing the post draw phase (when all children are drawn)
- :cpp:enumerator:`LV_EVENT_DRAW_TASK_ADDED`: Adding a draw task
Special events
Special Events
--------------
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED`: The object's value has changed (i.e. slider moved)
- :cpp:enumerator:`LV_EVENT_INSERT`: A text is inserted to the object. The event data is :cpp:type:`char` ``*`` being inserted.
- :cpp:enumerator:`LV_EVENT_REFRESH`: Notify the object to refresh something on it (for the user)
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED`: Widget's value has changed (i.e. slider moved)
- :cpp:enumerator:`LV_EVENT_INSERT`: A text is inserted to Widget. The event data is ``char `*`` being inserted.
- :cpp:enumerator:`LV_EVENT_REFRESH`: Notify Widget to refresh something on it (for the user)
- :cpp:enumerator:`LV_EVENT_READY`: A process has finished
- :cpp:enumerator:`LV_EVENT_CANCEL`: A process has been cancelled
Other events
Other Events
------------
- :cpp:enumerator:`LV_EVENT_CREATE`: Object is being created
- :cpp:enumerator:`LV_EVENT_DELETE`: Object is being deleted
- :cpp:enumerator:`LV_EVENT_CREATE`: Widget is being created
- :cpp:enumerator:`LV_EVENT_DELETE`: Widget is being deleted
- :cpp:enumerator:`LV_EVENT_CHILD_CHANGED`: Child was removed, added, or its size, position were changed
- :cpp:enumerator:`LV_EVENT_CHILD_CREATED`: Child was created, always bubbles up to all parents
- :cpp:enumerator:`LV_EVENT_CHILD_DELETED`: Child was deleted, always bubbles up to all parents
@ -167,12 +177,12 @@ Other events
- :cpp:enumerator:`LV_EVENT_SCREEN_LOAD_START`: A screen load started, fired when the screen change delay is expired
- :cpp:enumerator:`LV_EVENT_SCREEN_LOADED`: A screen was loaded
- :cpp:enumerator:`LV_EVENT_SCREEN_UNLOADED`: A screen was unloaded
- :cpp:enumerator:`LV_EVENT_SIZE_CHANGED`: Object coordinates/size have changed
- :cpp:enumerator:`LV_EVENT_STYLE_CHANGED`: Object's style has changed
- :cpp:enumerator:`LV_EVENT_SIZE_CHANGED`: Widget coordinates/size have changed
- :cpp:enumerator:`LV_EVENT_STYLE_CHANGED`: Widget's style has changed
- :cpp:enumerator:`LV_EVENT_LAYOUT_CHANGED`: The children position has changed due to a layout recalculation
- :cpp:enumerator:`LV_EVENT_GET_SELF_SIZE`: Get the internal size of a widget
Display events
Display Events
--------------
- :cpp:enumerator:`LV_EVENT_INVALIDATE_AREA`
@ -187,44 +197,47 @@ Display events
- :cpp:enumerator:`LV_EVENT_FLUSH_FINISH`
Custom events
Custom Events
-------------
Any number of custom event codes can be registered by
``uint32_t MY_EVENT_1 =`` :cpp:func:`lv_event_register_id`
They can be sent to any objects with
:cpp:expr:`lv_obj_send_event(obj, MY_EVENT_1, &some_data)`
They can be sent to any Widget with
:cpp:expr:`lv_obj_send_event(widget, MY_EVENT_1, &some_data)`
Sending events
**************
To manually send events to an object, use
``lv_obj_send_event(obj, <EVENT_CODE>, &some_data)``.
Refresh Event
-------------
:cpp:enumerator:`LV_EVENT_REFRESH` is a special event because it's designed to let the
user notify a Widget to refresh itself. Some examples:
- notify a label to refresh its text according to one or more variables (e.g. current time)
- refresh a label when the language changes
- enable a button if some conditions are met (e.g. the correct PIN is entered)
- add/remove styles to/from a Widget if a limit is exceeded, etc
Sending Events Manually
***********************
To manually send events to a Widget, use
``lv_obj_send_event(widget, <EVENT_CODE>, &some_data)``.
For example, this can be used to manually close a message box by
simulating a button press (although there are simpler ways to do this):
.. code-block:: c
/*Simulate the press of the first button (indexes start from zero)*/
/* Simulate the press of the first button (indexes start from zero) */
uint32_t btn_id = 0;
lv_obj_send_event(mbox, LV_EVENT_VALUE_CHANGED, &btn_id);
The same works for display and input devices with
``lv_display_send_event(obj, <EVENT_CODE>, &some_data)`` and
``lv_indev_send_event(obj, <EVENT_CODE>, &some_data)``.
``lv_display_send_event(widget, <EVENT_CODE>, &some_data)`` and
``lv_indev_send_event(widget, <EVENT_CODE>, &some_data)``.
Refresh event
-------------
:cpp:enumerator:`LV_EVENT_REFRESH` is a special event because it's designed to let the
user notify an object to refresh itself. Some examples:
- notify a label to refresh its text according to one or more variables (e.g. current time)
- refresh a label when the language changes
- enable a button if some conditions are met (e.g. the correct PIN is entered)
- add/remove styles to/from an object if a limit is exceeded, etc
Fields of lv_event_t
********************
@ -233,31 +246,34 @@ Fields of lv_event_t
contains all data about the event. The following values can be gotten from it:
- :cpp:expr:`lv_event_get_code(e)`: get the event code
- :cpp:expr:`lv_event_get_current_target(e)`: get the object to which an event was sent. I.e. the object whose event handler is being called.
- :cpp:expr:`lv_event_get_target(e)`: get the object that originally triggered the event (different from :cpp:func:`lv_event_get_target` if :ref:`event bubbling <event_bubbling>` is enabled)
- :cpp:expr:`lv_event_get_current_target(e)`: get Widget to which an event was sent. I.e. the Widget whose event handler is being called.
- :cpp:expr:`lv_event_get_target(e)`: get Widget that originally triggered the event (different from :cpp:func:`lv_event_get_target` if :ref:`event bubbling <event_bubbling>` is enabled)
- :cpp:expr:`lv_event_get_user_data(e)`: get the pointer passed as the last parameter of :cpp:func:`lv_obj_add_event`.
- :cpp:expr:`lv_event_get_param(e)`: get the parameter passed as the last parameter of :cpp:func:`lv_obj_send_event`
.. _event_bubbling:
Event bubbling
Event Bubbling
**************
If :cpp:expr:`lv_obj_add_flag(obj, LV_OBJ_FLAG_EVENT_BUBBLE)` is enabled all
events will be sent to an object's parent too. If the parent also has
If :cpp:expr:`lv_obj_add_flag(widget, LV_OBJ_FLAG_EVENT_BUBBLE)` is enabled all
events will be sent to a Widget's parent as well. If the parent also has
:cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` enabled the event will be sent to its
parent and so on.
parent, and so on.
The *target* parameter of the event is always the current target object,
not the original object. To get the original target call
The *target* parameter of the event is always the current target Widget,
not the original Widget. To get the original target call
:cpp:expr:`lv_event_get_target_obj(e)` in the event handler.
.. _events_examples:
Examples
********
.. include:: ../examples/event/index.rst
.. include:: ../../examples/event/index.rst
.. _events_api:

18
docs/details/base-widget/index.rst Normal file
View File

@ -0,0 +1,18 @@
.. _base_widget_overview:
===========
Base Widget
===========
The following details apply to all types of Widgets.
.. toctree::
:maxdepth: 3
obj
coord
layer
styles/index
event
layouts/index
scroll

126
docs/details/base-widget/layer.rst Normal file
View File

@ -0,0 +1,126 @@
.. _layers:
======
Layers
======
When the term "layer" is used in LVGL documentation, it may refer to one of several
things:
1. for Widgets, the :ref:`layers_creation` creates a natural layering of Widgets;
2. in the context of pixel rendering (drawing), there are :ref:`draw_layers`;
3. permanent :ref:`screen_layers` are part of each :ref:`display` object, and
are covered :ref:`here <screen_layers>`
#1 and #2 are covered below.
.. _layers_creation:
Order of Creation
*****************
By default, LVGL draws new Widgets on top of old Widgets.
For example, assume we add a button to a parent Widget named button1 and
then another button named button2. Then button1 (along with its child
Widget(s)) will be in the background and can be covered by button2 and
its children.
.. image:: /misc/layers.png
.. code-block:: c
/* Create a screen */
lv_obj_t * scr = lv_obj_create(NULL, NULL);
lv_screen_load(scr); /* Load the screen */
/* Create 2 buttons */
lv_obj_t * btn1 = lv_button_create(scr, NULL); /* Create a button on the screen */
lv_button_set_fit(btn1, true, true); /* Enable automatically setting the size according to content */
lv_obj_set_pos(btn1, 60, 40); /* Set the position of the button */
lv_obj_t * btn2 = lv_button_create(scr, btn1); /* Copy the first button */
lv_obj_set_pos(btn2, 180, 80); /* Set the position of the button */
/* Add labels to the buttons */
lv_obj_t * label1 = lv_label_create(btn1, NULL); /* Create a label on the first button */
lv_label_set_text(label1, "Button 1"); /* Set the text of the label */
lv_obj_t * label2 = lv_label_create(btn2, NULL); /* Create a label on the second button */
lv_label_set_text(label2, "Button 2"); /* Set the text of the label */
/* Delete the second label */
lv_obj_delete(label2);
.. _layers_order:
Changing Order
--------------
There are four explicit ways to bring a Widget to the foreground:
- Use :cpp:expr:`lv_obj_move_foreground(widget)` to bring a Widget to the foreground.
Similarly, use :cpp:expr:`lv_obj_move_background(widget)` to move it to the background.
- Use :cpp:expr:`lv_obj_move_to_index(widget, idx)` to move a Widget to a given index in the order of children.
- ``0``: background
- ``child_num - 1``: foreground
- ``< 0``: count from the top, to move forward (up): :cpp:expr:`lv_obj_move_to_index(widget, lv_obj_get_index(widget) - 1)`
- Use :cpp:expr:`lv_obj_swap(widget1, widget2)` to swap the relative layer position of two Widgets.
- When :cpp:expr:`lv_obj_set_parent(widget, new_parent)` is used, ``widget`` will be on the foreground of ``new_parent``.
.. _draw_layers:
Draw Layers
***********
Some style properties cause LVGL to allocate a buffer and render a Widget and its
children there first. Later that layer will be merged to the screen or its parent
layer after applying some transformations or other modifications.
Simple Layer
------------
The following style properties trigger the creation of a "Simple Layer":
- ``opa_layered``
- ``bitmap_mask_src``
- ``blend_mode``
In this case the Widget will be sliced into ``LV_DRAW_SW_LAYER_SIMPLE_BUF_SIZE``
sized chunks.
If there is no memory for a new chunk, LVGL will try allocating the layer after
another chunk is rendered and freed.
Transformed Layer
-----------------
When the widget is transformed a larger part of the Widget needs to rendered to
provide enough data for transformation. LVGL tries to render as small area of the
widget as possible, but due to the nature of transformations no slicing is possible
in this case.
The following style properties trigger the creation of a "Transform Layer":
- ``transform_scale_x``
- ``transform_scale_y``
- ``transform_skew_x``
- ``transform_skew_y``
- ``transform_rotate``
Clip corner
-----------
The ``clip_corner`` style property also causes LVGL to create a 2 layers with radius
height for the top and bottom parts of the Widget.
.. _layers_api:
API
***

16
docs/layouts/flex.rst → docs/details/base-widget/layouts/flex.rst
View File

@ -14,8 +14,8 @@ adjust the spacing between the items and tracks, handle *grow* to make
the item(s) fill the remaining space with respect to min/max width and
height.
To make an object flex container call
:cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`.
To make a Widget flex container call
:cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX)`.
Note that the flex layout feature of LVGL needs to be globally enabled
with :c:macro:`LV_USE_FLEX` in ``lv_conf.h``.
@ -43,7 +43,7 @@ With the following functions you can set a Flex layout on any parent.
Flex flow
---------
:cpp:expr:`lv_obj_set_flex_flow(obj, flex_flow)`
:cpp:expr:`lv_obj_set_flex_flow(widget, flex_flow)`
The possible values for ``flex_flow`` are:
@ -62,7 +62,7 @@ Flex align
----------
To manage the placement of the children use
:cpp:expr:`lv_obj_set_flex_align(obj, main_place, cross_place, track_cross_place)`
:cpp:expr:`lv_obj_set_flex_align(widget, main_place, cross_place, track_cross_place)`
- ``main_place`` determines how to distribute the items in their track
on the main axis. E.g. flush the items to the right on :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP`. (It's called
@ -99,7 +99,7 @@ Flex grow
Flex grow can be used to make one or more children fill the available
space on the track. When more children have grow parameters, the
available space will be distributed proportionally to the grow values.
For example, there is 400 px remaining space and 4 objects with grow:
For example, there is 400 px remaining space and 4 Widgets with grow:
- ``A`` with grow = 1
- ``B`` with grow = 1
@ -132,7 +132,7 @@ The following flex related style properties exist:
Internal padding
----------------
To modify the minimum space flexbox inserts between objects, the
To modify the minimum space flexbox inserts between Widgets, the
following properties can be set on the flex container style:
- ``pad_row`` Sets the padding between the rows.
@ -140,7 +140,7 @@ following properties can be set on the flex container style:
- ``pad_column`` Sets the padding between the columns.
These can for example be used if you don't want any padding between your
objects: :cpp:expr:`lv_style_set_pad_column(&row_container_style,0)`
Widgets: :cpp:expr:`lv_style_set_pad_column(&row_container_style,0)`
.. _flex_other:
@ -170,7 +170,7 @@ You can force Flex to put an item into a new line with
Example
*******
.. include:: ../examples/layouts/flex/index.rst
.. include:: ../../../examples/layouts/flex/index.rst
.. _flex_api:

14
docs/layouts/grid.rst → docs/details/base-widget/layouts/grid.rst
View File

@ -15,7 +15,7 @@ track's size can be set in pixel, to the largest item
(:c:macro:`LV_GRID_CONTENT`) or in "Free unit" (FR) to distribute the free
space proportionally.
To make an object a grid container call :cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_GRID)`.
To make a Widget a grid container call :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_GRID)`.
Note that the grid layout feature of LVGL needs to be globally enabled
with :c:macro:`LV_USE_GRID` in ``lv_conf.h``.
@ -47,11 +47,11 @@ For example:
.. code-block:: c
static int32_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST}; /*2 columns with 100 and 400 ps width*/
static int32_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; /*3 100 px tall rows*/
static int32_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST}; /* 2 columns with 100 and 400 ps width */
static int32_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; /* 3 100 px tall rows */
To set the descriptors on a parent use
:cpp:expr:`lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`.
:cpp:expr:`lv_obj_set_grid_dsc_array(widget, col_dsc, row_dsc)`.
Besides simple settings the size in pixel you can use two special
values:
@ -105,7 +105,7 @@ If there are some empty space the track can be aligned several ways:
item on the end line. Not applies to ``track_cross_place``.
To set the track's alignment use
:cpp:expr:`lv_obj_set_grid_align(obj, column_align, row_align)`.
:cpp:expr:`lv_obj_set_grid_align(widget, column_align, row_align)`.
.. _grid_subgrid:
@ -151,7 +151,7 @@ The following Grid related style properties exist:
Internal padding
----------------
To modify the minimum space Grid inserts between objects, the following
To modify the minimum space Grid inserts between Widgets, the following
properties can be set on the Grid container style:
- ``pad_row`` Sets the padding between the rows.
@ -176,7 +176,7 @@ The columns will be placed from right to left.
Example
*******
.. include:: ../examples/layouts/grid/index.rst
.. include:: ../../../examples/layouts/grid/index.rst
.. _grid_api:

0
docs/layouts/index.rst → docs/details/base-widget/layouts/index.rst
View File

633
docs/details/base-widget/obj.rst Normal file
View File

@ -0,0 +1,633 @@
.. _widget_basics:
=============
Widget Basics
=============
What is a Widget?
*****************
A Widget is the **basic building block** of the LVGL user interface.
Examples of Widgets: :ref:`Base Widget (and Screen) <base_widget>`,
:ref:`Button <lv_button>`, :ref:`Label <lv_label>`,
:ref:`Image <lv_image>`, :ref:`List <lv_list>`,
:ref:`Chart <lv_chart>` and :ref:`Text Area <lv_textarea>`.
See :ref:`widgets` to see all Widget types.
All Widgets are referenced using an :cpp:type:`lv_obj_t` pointer as a handle.
This pointer can later be used to read or change the Widget's attributes.
.. _base_widget:
Base Widget
***********
The most fundamental of all Widgets is the Base Widget, on which all other widgets
are based. From an Object-Oriented perspective, think of the Base Widget as the
Widget class from which all other Widgets inherit.
The functions and functionalities of the Base Widget can be used with
other widgets as well. For example :cpp:expr:`lv_obj_set_width(slider, 100)`.
The Base Widget can be used directly as a simple widget. While it is a simple
rectangle, it has a large number of features shared with all Widgets, detailed
below and in subsequent pages. In HTML terms, think of it as a ``<div>``.
.. _widget_attributes:
Attributes
**********
Basic attributes
----------------
All Widget types share some basic attributes:
- Position
- Size
- Parent
- Styles
- Events it emits
- Flags like *Clickable*, *Scollable*, etc.
- Etc.
You can set/get these attributes with ``lv_obj_set_...`` and
``lv_obj_get_...`` functions. For example:
.. code-block:: c
/* Set basic Widget attributes */
lv_obj_set_size(btn1, 100, 50); /* Set a button's size */
lv_obj_set_pos(btn1, 20,30); /* Set a button's position */
For complete details on position, size, coordinates and layouts, see :ref:`coord`.
Widget-specific attributes
--------------------------
The Widget types have special attributes as well. For example, a slider has
- Minimum and maximum values
- Current value
For these special attributes, every Widget type may have unique API
functions. For example for a slider:
.. code-block:: c
/* Set slider specific attributes */
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 widgets is described in their
:ref:`Documentation <widgets>` but you can also check the respective
header files (e.g. *widgets/lv_slider.h*)
.. _lv_obj_parents_and_children:
Parents and children
--------------------
A Widget's parent is set when the widget is created --- the parent is passed to the
creation function.
To get a Widget's current parent, use :cpp:expr:`lv_obj_get_parent(widget)`.
You can move the Widget to a new parent with :cpp:expr:`lv_obj_set_parent(widget, new_parent)`.
To get a specific child of a parent use :cpp:expr:`lv_obj_get_child(parent, idx)`.
Some examples for ``idx``:
- ``0`` get the child created first
- ``1`` get the child created second
- ``-1`` get the child created last
You can iterate through a parent Widget's children like this:
.. code-block:: c
uint32_t i;
for(i = 0; i < lv_obj_get_child_count(parent); i++) {
lv_obj_t * child = lv_obj_get_child(parent, i);
/* Do something with child. */
}
:cpp:expr:`lv_obj_get_index(widget)` returns the index of the Widget in its parent.
It is equivalent to the number of older children in the parent.
You can bring a Widget to the foreground or send it to the background with
:cpp:expr:`lv_obj_move_foreground(widget)` and :cpp:expr:`lv_obj_move_background(widget)`.
You can change the index of a Widget in its parent using :cpp:expr:`lv_obj_move_to_index(widget, index)`.
You can swap the position of two Widgets with :cpp:expr:`lv_obj_swap(widget1, widget2)`.
To get a Widget's Screen (highest-level parent) use :cpp:expr:`lv_obj_get_screen(widget)`.
.. _widget_working_mechanisms:
Working Mechanisms
******************
Parent-child structure
----------------------
A parent Widget can be considered as the container of its children. Every Widget has
exactly one parent Widget (except Screens), but a parent Widget can have any number
of children. There is no limitation for the type of the parent but there are Widgets
which are typically a parent (e.g. button) or a child (e.g. label).
Moving together
---------------
If the position of a parent changes, the children will move along with
it. Therefore, all positions are relative to the parent.
.. image:: /misc/par_child1.png
.. code-block:: c
lv_obj_t * parent = lv_obj_create(lv_screen_active()); /* Create a parent Widget on current screen */
lv_obj_set_size(parent, 100, 80); /* Set size of parent */
lv_obj_t * obj1 = lv_obj_create(parent); /* Create a Widget on previously created parent Widget */
lv_obj_set_pos(widget1, 10, 10); /* Set position of new Widget */
Modify the position of the parent:
.. image:: /misc/par_child2.png
.. code-block:: c
lv_obj_set_pos(parent, 50, 50); /* Move the parent. The child will move with it. */
(For simplicity the adjusting of colors of the Widgets is not shown in
the example.)
Visibility only on the parent
-----------------------------
If a child is partially or fully outside its parent then the parts
outside will not be visible.
.. image:: /misc/par_child3.png
.. code-block:: c
lv_obj_set_x(widget1, -30); /* Move the child a little bit off the parent */
This behavior can be overwritten with
:cpp:expr:`lv_obj_add_flag(widget, LV_OBJ_FLAG_OVERFLOW_VISIBLE)` which allow the
children to be drawn out of the parent.
Create and delete Widgets
-------------------------
In LVGL, Widgets can be created and deleted dynamically at run time. It
means only the currently created (existing) Widgets consume RAM.
This allows for the creation of a screen just when a button is clicked
to open it, and for deletion of screens when a new screen is loaded.
UIs can be created based on the current environment of the device. For
example one can create meters, charts, bars and sliders based on the
currently attached sensors.
Every widget has its own **create** function with a prototype like this:
.. code-block:: c
lv_obj_t * lv_<widget>_create(lv_obj_t * parent, <other parameters if any>);
Typically, the create functions only have a ``parent`` parameter telling
them on which Widget to create the new Widget.
The return value is a pointer to the created Widget with :cpp:type:`lv_obj_t` ``*``
type.
There is a common **delete** function for all Widget types. It deletes
the Widget and all of its children.
.. code-block:: c
void lv_obj_delete(lv_obj_t * widget);
:cpp:func:`lv_obj_delete` will delete the Widget immediately. If for any reason you
can't delete the Widget immediately you can use
:cpp:expr:`lv_obj_delete_async(widget)` which will perform the deletion on the next
call of :cpp:func:`lv_timer_handler`. This is useful e.g. if you want to
delete the parent of a Widget in the child's :cpp:enumerator:`LV_EVENT_DELETE`
handler.
You can remove all the children of a Widget (but not the Widget itself)
using :cpp:expr:`lv_obj_clean(widget)`.
You can use :cpp:expr:`lv_obj_delete_delayed(widget, 1000)` to delete a Widget after
some time. The delay is expressed in milliseconds.
Sometimes you're not sure whether a Widget was deleted and you need some way to
check if it's still "alive". Anytime before the Widget is deleted, you can use
cpp:expr:`lv_obj_null_on_delete(&widget)` to cause your Widget pointer to be set to ``NULL``
when the Widget is deleted.
Make sure the pointer variable itself stays valid until the Widget is deleted. Here
is an example:
.. code:: c
void some_timer_callback(lv_timer_t * t)
{
static lv_obj_t * my_label;
if(my_label == NULL) {
my_label = lv_label_create(lv_screen_active());
lv_obj_delete_delayed(my_label, 1000);
lv_obj_null_on_delete(&my_label);
}
else {
lv_obj_set_x(my_label, lv_obj_get_x(my_label) + 1);
}
}
.. _screens:
Screens
*******
What are Screens?
-----------------
Not to be confused with a :ref:`display`, Screens are simply any Widget created
without a parent (i.e. passing NULL for the ``parent`` argument during creation). As
such, they form the "root" of a Widget Tree.
Normally the Base Widget is used for this purpose since it has all the features most
Screens need. But an :ref:`lv_image` Widget can also be used to create a wallpaper
background for the Widget Tree.
All Screens:
- are automatically attached to the :ref:`default_display` current when the Screen
was created;
- automatically occupy the full area of the associated display;
- cannot be moved, i.e. functions such as :cpp:func:`lv_obj_set_pos` and
:cpp:func:`lv_obj_set_size` cannot be used on screens.
Each :ref:`display` object can have multiple screens associated with it, but not vice
versa. Thus the relationship::
Display
|
--- (one or more)
/|\
Screen Widgets (root of a Widget Tree)
|
O (zero or more)
/|\
Child Widgets
Creating Screens
----------------
Screens are created like this:
.. code-block:: c
lv_obj_t * scr1 = lv_obj_create(NULL);
Screens can be deleted with :cpp:expr:`lv_obj_delete(scr)`, but be sure you do not
delete the :ref:`active_screen`.
.. _active_screen:
Active Screen
-------------
While each :ref:`display` object can have any number of Screens Widgets associated
with it, only one of those Screens is considered "Active" at any given time. That
Screen is referred to as the Display's "Active Screen". For this reason, only one
Screen and its child Widgets will ever be shown on a display at one time.
When each :ref:`display` object was created, a default screen was created with it and
set as its "Active Screen".
To get a pointer to the "Active Screen", call :cpp:func:`lv_screen_active`.
To set a Screen to be the "Active Screen", call :cpp:func:`lv_screen_load` or
:cpp:func:`lv_screen_load_anim`.
.. _loading_screens:
Loading Screens
---------------
To load a new screen, use :cpp:expr:`lv_screen_load(scr1)`. This sets ``scr1`` as
the Active Screen.
Load Screen with Animation
^^^^^^^^^^^^^^^^^^^^^^^^^^
A new screen can be loaded with animation by using
:cpp:expr:`lv_screen_load_anim(scr, transition_type, time, delay, auto_del)`. The
following transition types exist:
- :cpp:enumerator:`LV_SCR_LOAD_ANIM_NONE`: Switch immediately after ``delay`` milliseconds
- :cpp:enumerator:`LV_SCR_LOAD_ANIM_OVER_LEFT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_OVER_RIGHT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_OVER_TOP` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_OVER_BOTTOM`: Move the new screen over the current towards the given direction
- :cpp:enumerator:`LV_SCR_LOAD_ANIM_OUT_LEFT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_OUT_RIGHT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_OUT_TOP` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_OUT_BOTTOM`: Move out the old screen over the current towards the given direction
- :cpp:enumerator:`LV_SCR_LOAD_ANIM_MOVE_LEFT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_MOVE_RIGHT`, :cpp:enumerator:`LV_SCR_LOAD_ANIM_MOVE_TOP` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_MOVE_BOTTOM`: Move both the current and new screens towards the given direction
- :cpp:enumerator:`LV_SCR_LOAD_ANIM_FADE_IN` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_FADE_OUT`: Fade the new screen over the old screen, or vice versa
Setting ``auto_del`` to ``true`` will automatically delete the old
screen when the animation is finished.
The new screen will become active (returned by :cpp:func:`lv_screen_active`) when
the animation starts after ``delay`` time. All inputs are disabled
during the screen animation.
.. _layers_overview:
Layers
------
When an ``lv_display_t`` object is created, 4 Screens (layers) are created and
attached to it.
1. Bottom Layer
2. Active Screen
3. Top Layer
4. System Layer
1, 3 and 4 are independent of the :ref:`active_screen` and they will be shown (if
they contain anything that is visible) regardless of which screen is the Active
Screen. See :ref:`screen_layers` for more information.
.. _transparent_screens:
Transparent Screens
-------------------
Usually, the opacity of the Screen is :cpp:enumerator:`LV_OPA_COVER` to provide a
solid background for its children. If this is not the case (opacity <
100%) the display's ``bottom_layer`` will be visible. If the bottom layer's
opacity is also not :cpp:enumerator:`LV_OPA_COVER` LVGL will have no solid background
to draw.
This configuration (transparent Screen) could be useful to create, for example,
on-screen display (OSD) menus where a video is played on a different hardware layer
of the display panel, and a menu is overlaid on a higher layer.
To properly render a UI on a transparent Screen the Display's color format needs to
be set to one with an alpha channel (for example LV_COLOR_FORMAT_ARGB8888).
In summary, to enable transparent screens and displays for OSD menu-like UIs:
- Set the screen's ``bg_opa`` to transparent:
:cpp:expr:`lv_obj_set_style_bg_opa(lv_screen_active(), LV_OPA_TRANSP, LV_PART_MAIN)`
- Set the bottom layer's ``bg_opa`` to transparent:
:cpp:expr:`lv_obj_set_style_bg_opa(lv_layer_bottom(), LV_OPA_TRANSP, LV_PART_MAIN)`
- Set a color format with alpha channel. E.g.
:cpp:expr:`lv_display_set_color_format(disp, LV_COLOR_FORMAT_ARGB8888)`
.. _widget_parts:
Parts
*****
The widgets are built from multiple parts. For example a
:ref:`Base Widget <base_widget>` uses the main and scrollbar parts but a
:ref:`Slider <lv_slider>` uses the main, indicator and knob parts.
Parts are similar to *pseudo-elements* in CSS.
The following predefined parts exist in LVGL:
- :cpp:enumerator:`LV_PART_MAIN`: A background like rectangle
- :cpp:enumerator:`LV_PART_SCROLLBAR`: The scrollbar(s)
- :cpp:enumerator:`LV_PART_INDICATOR`: Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox
- :cpp:enumerator:`LV_PART_KNOB`: Like a handle to grab to adjust the value
- :cpp:enumerator:`LV_PART_SELECTED`: Indicate the currently selected option or section
- :cpp:enumerator:`LV_PART_ITEMS`: Used if the widget has multiple similar elements (e.g. table cells)
- :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. text area's or chart's cursor
- :cpp:enumerator:`LV_PART_CUSTOM_FIRST`: Custom parts can be added from here.
The main purpose of parts is to allow styling the "components" of the
widgets. They are described in more detail in the
:ref:`Style overview <styles>` section.
.. _widget_states:
States
******
The Widget can be in a combination of the following states:
- :cpp:enumerator:`LV_STATE_DEFAULT`: Normal, released state
- :cpp:enumerator:`LV_STATE_CHECKED`: Toggled or checked state
- :cpp:enumerator:`LV_STATE_FOCUSED`: Focused via keypad or encoder or clicked via touchpad/mouse
- :cpp:enumerator:`LV_STATE_FOCUS_KEY`: Focused via keypad or encoder but not via touchpad/mouse
- :cpp:enumerator:`LV_STATE_EDITED`: Edit by an encoder
- :cpp:enumerator:`LV_STATE_HOVERED`: Hovered by mouse (not supported now)
- :cpp:enumerator:`LV_STATE_PRESSED`: Being pressed
- :cpp:enumerator:`LV_STATE_SCROLLED`: Being scrolled
- :cpp:enumerator:`LV_STATE_DISABLED`: Disabled state
- :cpp:enumerator:`LV_STATE_USER_1`: Custom state
- :cpp:enumerator:`LV_STATE_USER_2`: Custom state
- :cpp:enumerator:`LV_STATE_USER_3`: Custom state
- :cpp:enumerator:`LV_STATE_USER_4`: Custom state
The states are usually automatically changed by the library as the user
interacts with a Widget (presses, releases, focuses, etc.). However,
the states can be changed manually as well. To set or clear given state (but
leave the other states untouched) use
:cpp:expr:`lv_obj_add_state(widget, LV_STATE_...)` and
:cpp:expr:`lv_obj_remove_state(widget, LV_STATE_...)`. In both cases OR-ed state
values can be used as well. E.g.
:cpp:expr:`lv_obj_add_state(widget, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED)`.
To learn more about the states read the related section of the
:ref:`Style overview <styles>`.
.. _lv_obj_flags:
Flags
*****
There are some Widget attributes which can be enabled/disabled by
:cpp:expr:`lv_obj_add_flag(widget, LV_OBJ_FLAG_...)` and
:cpp:expr:`lv_obj_remove_flag(widget, LV_OBJ_FLAG_...)`.
- :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` Make the Widget hidden. (Like it wasn't there at all)
- :cpp:enumerator:`LV_OBJ_FLAG_CLICKABLE` Make the Widget clickable by input devices
- :cpp:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE` Add focused state to the Widget when clicked
- :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` Toggle checked state when the Widget is clicked
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLLABLE` Make the Widget scrollable
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ELASTIC` Allow scrolling inside but with slower speed
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_MOMENTUM` Make the Widget scroll further when "thrown"
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ONE` Allow scrolling only one snappable children
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN_HOR` Allow propagating the horizontal scroll to a parent
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN_VER` Allow propagating the vertical scroll to a parent
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN` Simple packaging for (:cpp:expr:`LV_OBJ_FLAG_SCROLL_CHAIN_HOR | LV_OBJ_FLAG_SCROLL_CHAIN_VER`)
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ON_FOCUS` Automatically scroll Widget to make it visible when focused
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_WITH_ARROW` Allow scrolling the focused Widget with arrow keys
- :cpp:enumerator:`LV_OBJ_FLAG_SNAPPABLE` If scroll snap is enabled on the parent it can snap to this Widget
- :cpp:enumerator:`LV_OBJ_FLAG_PRESS_LOCK` Keep the Widget pressed even if the press slid from the Widget
- :cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` Propagate the events to the parent as well
- :cpp:enumerator:`LV_OBJ_FLAG_GESTURE_BUBBLE` Propagate the gestures to the parent
- :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` Allow performing more accurate hit (click) test. E.g. accounting for rounded corners
- :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` Make the Widget not positioned by the layouts
- :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` Do not scroll the Widget when the parent scrolls and ignore layout
- :cpp:enumerator:`LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` Enable sending ``LV_EVENT_DRAW_TASK_ADDED`` events
- :cpp:enumerator:`LV_OBJ_FLAG_OVERFLOW_VISIBLE` Do not clip the children's content to the parent's boundary
- :cpp:enumerator:`LV_OBJ_FLAG_FLEX_IN_NEW_TRACK` Start a new flex track on this item
- :cpp:enumerator:`LV_OBJ_FLAG_LAYOUT_1` Custom flag, free to use by layouts
- :cpp:enumerator:`LV_OBJ_FLAG_LAYOUT_2` Custom flag, free to use by layouts
- :cpp:enumerator:`LV_OBJ_FLAG_WIDGET_1` Custom flag, free to use by widget
- :cpp:enumerator:`LV_OBJ_FLAG_WIDGET_2` Custom flag, free to use by widget
- :cpp:enumerator:`LV_OBJ_FLAG_USER_1` Custom flag, free to use by user
- :cpp:enumerator:`LV_OBJ_FLAG_USER_2` Custom flag, free to use by user
- :cpp:enumerator:`LV_OBJ_FLAG_USER_3` Custom flag, free to use by user
- :cpp:enumerator:`LV_OBJ_FLAG_USER_4` Custom flag, free to use by user
Some examples:
.. code-block:: c
/* Hide on Widget */
lv_obj_add_flag(widget, LV_OBJ_FLAG_HIDDEN);
/* Make a Widget non-clickable */
lv_obj_remove_flag(widget, LV_OBJ_FLAG_CLICKABLE);
.. _lv_obj_events:
Base-Widget Events
******************
.. _widget_events:
Events from Input Devices
-------------------------
- :cpp:enumerator:`LV_EVENT_PRESSED` Widget has been pressed.
- :cpp:enumerator:`LV_EVENT_PRESSING` Widget is being pressed (sent continuously while pressing).
- :cpp:enumerator:`LV_EVENT_PRESS_LOST` Widget is still being pressed but slid cursor/finger off Widget.
- :cpp:enumerator:`LV_EVENT_SHORT_CLICKED` Widget was pressed for a short period of time, then released. Not sent if scrolled.
- :cpp:enumerator:`LV_EVENT_SINGLE_CLICKED` Sent for first short click within a small distance and short time.
- :cpp:enumerator:`LV_EVENT_DOUBLE_CLICKED` Sent for second short click within small distance and short time.
- :cpp:enumerator:`LV_EVENT_TRIPLE_CLICKED` Sent for third short click within small distance and short time.
- :cpp:enumerator:`LV_EVENT_LONG_PRESSED` Object has been pressed for at least `long_press_time`. Not sent if scrolled.
- :cpp:enumerator:`LV_EVENT_LONG_PRESSED_REPEAT` Sent after `long_press_time` in every `long_press_repeat_time` ms. Not sent if scrolled.
- :cpp:enumerator:`LV_EVENT_CLICKED` Sent on release if not scrolled (regardless to long press).
- :cpp:enumerator:`LV_EVENT_RELEASED` Sent in every cases when Widget has been released.
- :cpp:enumerator:`LV_EVENT_SCROLL_BEGIN` Scrolling begins. The event parameter is a pointer to the animation of the scroll. Can be modified.
- :cpp:enumerator:`LV_EVENT_SCROLL_THROW_BEGIN` Received when scrolling begins.
- :cpp:enumerator:`LV_EVENT_SCROLL_END` Scrolling ended.
- :cpp:enumerator:`LV_EVENT_SCROLL` Scrolling
- :cpp:enumerator:`LV_EVENT_GESTURE` A gesture is detected. Get gesture with `lv_indev_get_gesture_dir(lv_indev_active());`
- :cpp:enumerator:`LV_EVENT_KEY` A key is sent to Widget. Get key with `lv_indev_get_key(lv_indev_active());`
- :cpp:enumerator:`LV_EVENT_FOCUSED` Widget received focus,
- :cpp:enumerator:`LV_EVENT_DEFOCUSED` Widget's focus has been lost.
- :cpp:enumerator:`LV_EVENT_LEAVE` Widget's focus has been lost but is still selected.
- :cpp:enumerator:`LV_EVENT_HIT_TEST` Perform advanced hit-testing.
Special Events
--------------
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` when the :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` flag is
enabled and the Widget was clicked (on transition to/from the checked state)
Drawing Events
--------------
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN` Performing drawing of main part
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_BEGIN` Starting drawing of main part
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_END` Finishing drawing of main part
- :cpp:enumerator:`LV_EVENT_DRAW_POST` Perform the post draw phase (when all children are drawn)
- :cpp:enumerator:`LV_EVENT_DRAW_POST_BEGIN` Starting the post draw phase (when all children are drawn)
- :cpp:enumerator:`LV_EVENT_DRAW_POST_END` Finishing the post draw phase (when all children are drawn)
Other Events
------------
- :cpp:enumerator:`LV_EVENT_DELETE` Object is being deleted
- :cpp:enumerator:`LV_EVENT_CHILD_CHANGED` Child was removed, added, or its size, position were changed
- :cpp:enumerator:`LV_EVENT_CHILD_CREATED` Child was created, always bubbles up to all parents
- :cpp:enumerator:`LV_EVENT_CHILD_DELETED` Child was deleted, always bubbles up to all parents
- :cpp:enumerator:`LV_EVENT_SIZE_CHANGED` Object coordinates/size have changed
- :cpp:enumerator:`LV_EVENT_STYLE_CHANGED` Object's style has changed
- :cpp:enumerator:`LV_EVENT_LAYOUT_CHANGED` A child's position has changed due to a layout recalculation (when container has flex or grid layout style)
- :cpp:enumerator:`LV_EVENT_GET_SELF_SIZE` Get internal size of a widget
.. admonition:: Further Reading
Learn more about :ref:`events`.
.. _lv_obj_keys:
Keys
****
If :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` is enabled, :cpp:enumerator:`LV_KEY_RIGHT` and
:cpp:enumerator:`LV_KEY_UP` make the Widget checked, and :cpp:enumerator:`LV_KEY_LEFT` and
:cpp:enumerator:`LV_KEY_DOWN` make it unchecked.
If :cpp:enumerator:`LV_OBJ_FLAG_SCROLLABLE` is enabled, but the Widget is not editable
(as declared by the widget class), the arrow keys (:cpp:enumerator:`LV_KEY_UP`,
:cpp:enumerator:`LV_KEY_DOWN`, :cpp:enumerator:`LV_KEY_LEFT`, :cpp:enumerator:`LV_KEY_RIGHT`) scroll the Widget.
If the Widget can only scroll vertically, :cpp:enumerator:`LV_KEY_LEFT` and
:cpp:enumerator:`LV_KEY_RIGHT` will scroll up/down instead, making it compatible with
an encoder input device. See :ref:`Input devices overview <indev>` for
more on encoder behaviors and the edit mode.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _widget_snapshot:
Snapshot
********
A snapshot image can be generated for a Widget together with its
children. Check details in :ref:`snapshot`.
Example
*******
.. include:: ../../examples/widgets/obj/index.rst
.. _lv_obj_api:
API
***

130
docs/overview/scroll.rst → docs/details/base-widget/scroll.rst
View File

@ -1,22 +1,24 @@
.. _scroll:
.. _scrolling:
=========
Scrolling
=========
======
Scroll
======
Overview
********
In LVGL scrolling works very intuitively: if an object is outside its
In LVGL scrolling works very intuitively: if a Widget is outside its
parent content area (the size without padding), the parent becomes
scrollable and scrollbar(s) will appear. That's it.
Any object can be scrollable including ``lv_obj``, ``lv_image``,
Any Widget can be scrollable including :ref:`base_widget`, ``lv_image``,
``lv_button``, ``lv_meter``, etc
The object can either be scrolled horizontally or vertically in one
The Widget can either be scrolled horizontally or vertically in one
stroke; diagonal scrolling is not possible.
Scrollbar
---------
@ -28,10 +30,10 @@ following ``mode``\ (s) exist:
- :cpp:enumerator:`LV_SCROLLBAR_MODE_OFF`: Never show the scrollbars
- :cpp:enumerator:`LV_SCROLLBAR_MODE_ON`: Always show the scrollbars
- :cpp:enumerator:`LV_SCROLLBAR_MODE_ACTIVE`: Show scroll bars while an object is being scrolled
- :cpp:enumerator:`LV_SCROLLBAR_MODE_ACTIVE`: Show scroll bars while a Widget is being scrolled
- :cpp:enumerator:`LV_SCROLLBAR_MODE_AUTO`: Show scroll bars when the content is large enough to be scrolled
``lv_obj_set_scrollbar_mode(obj, LV_SCROLLBAR_MODE_...)`` sets the scrollbar mode on an object.
:cpp:expr:`lv_obj_set_scrollbar_mode(widget, LV_SCROLLBAR_MODE_...)` sets the scrollbar mode on a Widget.
Styling
^^^^^^^
@ -48,12 +50,12 @@ this:
...
lv_obj_add_style(obj, &style_red, LV_PART_SCROLLBAR);
lv_obj_add_style(widget, &style_red, LV_PART_SCROLLBAR);
An object goes to the :cpp:enumerator:`LV_STATE_SCROLLED` state while it's being
A Widget goes to the :cpp:enumerator:`LV_STATE_SCROLLED` state while it's being
scrolled. This allows adding different styles to the scrollbar or the
object itself when scrolled. This code makes the scrollbar blue when the
object is scrolled:
Widget itself when scrolled. This code makes the scrollbar blue when the
Widget is scrolled:
.. code-block:: c
@ -63,22 +65,23 @@ object is scrolled:
...
lv_obj_add_style(obj, &style_blue, LV_STATE_SCROLLED | LV_PART_SCROLLBAR);
lv_obj_add_style(widget, &style_blue, LV_STATE_SCROLLED | LV_PART_SCROLLBAR);
If the base direction of the :cpp:enumerator:`LV_PART_SCROLLBAR` is RTL
(:c:macro:`LV_BASE_DIR_RTL`) the vertical scrollbar will be placed on the left.
Note that, the ``base_dir`` style property is inherited. Therefore, it
can be set directly on the :cpp:enumerator:`LV_PART_SCROLLBAR` part of an object or on
the object's or any parent's main part to make a scrollbar inherit the
can be set directly on the :cpp:enumerator:`LV_PART_SCROLLBAR` part of a Widget or on
the Widget's or any parent's main part to make a scrollbar inherit the
base direction.
``pad_left/right/top/bottom`` sets the spacing around the scrollbars and
``width`` sets the scrollbar's width.
.. _scroll_events:
Events
------
Scrolling Events
----------------
The following events are related to scrolling:
@ -87,10 +90,6 @@ The following events are related to scrolling:
- :cpp:enumerator:`LV_EVENT_SCROLL_END`: Scrolling ends.
- :cpp:enumerator:`LV_EVENT_SCROLL`: Scroll happened. Triggered on every position change. Scroll events
Basic example
*************
TODO
Features of scrolling
*********************
@ -101,13 +100,14 @@ useful additional features.
Scrollable
----------
It's possible to make an object non-scrollable with
:cpp:expr:`lv_obj_remove_flag(obj, LV_OBJ_FLAG_SCROLLABLE)`.
It's possible to make a Widget non-scrollable with
:cpp:expr:`lv_obj_remove_flag(widget, LV_OBJ_FLAG_SCROLLABLE)`.
Non-scrollable objects can still propagate the scrolling (chain) to
Non-scrollable Widgets can still propagate the scrolling (chain) to
their parents.
The direction in which scrolling happens can be controlled by ``lv_obj_set_scroll_dir(obj, LV_DIR_...)``.
The direction in which scrolling happens can be controlled by
:cpp:expr:`lv_obj_set_scroll_dir(widget, LV_DIR_...)`.
The following values are possible for the direction:
@ -124,7 +124,7 @@ OR-ed values are also possible. E.g. :cpp:expr:`LV_DIR_TOP | LV_DIR_LEFT`.
Scroll chain
------------
If an object can't be scrolled further (e.g. its content has reached the
If a Widget can't be scrolled further (e.g. its content has reached the
bottom-most position) additional scrolling is propagated to its parent.
If the parent can be scrolled in that direction than it will be scrolled
instead. It continues propagating to the grandparent and
@ -132,14 +132,14 @@ grand-grandparents as well.
The propagation on scrolling is called "scroll chaining" and it can be
enabled/disabled with ``LV_OBJ_FLAG_SCROLL_CHAIN_HOR/VER`` flag. If
chaining is disabled the propagation stops on the object and the
chaining is disabled the propagation stops on the Widget and the
parent(s) won't be scrolled.
Scroll momentum
---------------
When the user scrolls an object and releases it, LVGL can emulate
inertial momentum for the scrolling. It's like the object was thrown and
When the user scrolls a Widget and releases it, LVGL can emulate
inertial momentum for the scrolling. It's like the Widget was thrown and
scrolling slows down smoothly.
The scroll momentum can be enabled/disabled with the
@ -148,36 +148,37 @@ The scroll momentum can be enabled/disabled with the
Elastic scroll
--------------
Normally an object can't be scrolled past the extremities of its
Normally a Widget can't be scrolled past the extremities of its
content. That is the top side of the content can't be below the top side
of the object.
of the Widget.
However, with :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ELASTIC` a fancy effect is added
when the user "over-scrolls" the content. The scrolling slows down, and
the content can be scrolled inside the object. When the object is
the content can be scrolled inside the Widget. When the Widget is
released the content scrolled in it will be animated back to the valid
position.
Snapping
--------
The children of an object can be snapped according to specific rules
The children of a Widget can be snapped according to specific rules
when scrolling ends. Children can be made snappable individually with
the :cpp:enumerator:`LV_OBJ_FLAG_SNAPPABLE` flag.
An object can align snapped children in four ways:
A Widget can align snapped children in four ways:
- :cpp:enumerator:`LV_SCROLL_SNAP_NONE`: Snapping is disabled. (default)
- :cpp:enumerator:`LV_SCROLL_SNAP_START`: Align the children to the left/top side of a scrolled object
- :cpp:enumerator:`LV_SCROLL_SNAP_END`: Align the children to the right/bottom side of a scrolled object
- :cpp:enumerator:`LV_SCROLL_SNAP_CENTER`: Align the children to the center of a scrolled object
- :cpp:enumerator:`LV_SCROLL_SNAP_START`: Align the children to the left/top side of a scrolled Widget
- :cpp:enumerator:`LV_SCROLL_SNAP_END`: Align the children to the right/bottom side of a scrolled Widget
- :cpp:enumerator:`LV_SCROLL_SNAP_CENTER`: Align the children to the center of a scrolled Widget
Snap alignment is set with
``lv_obj_set_scroll_snap_x/y(obj, LV_SCROLL_SNAP_...)``:
:cpp:expr:`lv_obj_set_scroll_snap_x(widget, LV_SCROLL_SNAP_...)` and
:cpp:expr:`lv_obj_set_scroll_snap_y(widget, LV_SCROLL_SNAP_...)`.
Under the hood the following happens:
1. User scrolls an object and releases the screen
1. User scrolls a Widget and releases the screen
2. LVGL calculates where the scroll would end considering scroll momentum
3. LVGL finds the nearest scroll point
4. LVGL scrolls to the snap point with an animation
@ -195,24 +196,25 @@ This feature can be enabled by the :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ONE` flag
Scroll on focus
---------------
Imagine that there a lot of objects in a group that are on a scrollable
object. Pressing the "Tab" button focuses the next object but it might
be outside the visible area of the scrollable object. If the "scroll on
focus" feature is enabled LVGL will automatically scroll objects to
Imagine that there a lot of Widgets in a group that are on a scrollable
Widget. Pressing the "Tab" button focuses the next Widget but it might
be outside the visible area of the scrollable Widget. If the "scroll on
focus" feature is enabled LVGL will automatically scroll Widgets to
bring their children into view. The scrolling happens recursively
therefore even nested scrollable objects are handled properly. The
object will be scrolled into view even if it's on a different page of a
therefore even nested scrollable Widgets are handled properly. The
Widget will be scrolled into view even if it's on a different page of a
tabview.
Scroll manually
***************
The following API functions allow manual scrolling of objects:
The following API functions allow manual scrolling of Widgets:
- ``lv_obj_scroll_by(obj, x, y, LV_ANIM_ON/OFF)`` scroll by ``x`` and ``y`` values
- ``lv_obj_scroll_to(obj, x, y, LV_ANIM_ON/OFF)`` scroll to bring the given coordinate to the top left corner
- ``lv_obj_scroll_to_x(obj, x, LV_ANIM_ON/OFF)`` scroll to bring the given coordinate to the left side
- ``lv_obj_scroll_to_y(obj, y, LV_ANIM_ON/OFF)`` scroll to bring the given coordinate to the top side
- ``lv_obj_scroll_by(widget, x, y, LV_ANIM_ON/OFF)`` scroll by ``x`` and ``y`` values
- ``lv_obj_scroll_to(widget, x, y, LV_ANIM_ON/OFF)`` scroll to bring the given coordinate to the top left corner
- ``lv_obj_scroll_to_x(widget, x, LV_ANIM_ON/OFF)`` scroll to bring the given coordinate to the left side
- ``lv_obj_scroll_to_y(widget, y, LV_ANIM_ON/OFF)`` scroll to bring the given coordinate to the top side
From time to time you may need to retrieve the scroll position of an
element, either to restore it later, or to display dynamically some
@ -235,32 +237,32 @@ to combine scroll event and store the scroll top position.
Scroll coordinates can be retrieved from different axes with these
functions:
- ``lv_obj_get_scroll_x(obj)`` Get the ``x`` coordinate of object
- ``lv_obj_get_scroll_y(obj)`` Get the ``y`` coordinate of object
- ``lv_obj_get_scroll_top(obj)`` Get the scroll coordinate from the top
- ``lv_obj_get_scroll_bottom(obj)`` Get the scroll coordinate from the bottom
- ``lv_obj_get_scroll_left(obj)`` Get the scroll coordinate from the left
- ``lv_obj_get_scroll_right(obj)`` Get the scroll coordinate from the right
- ``lv_obj_get_scroll_x(widget)`` Get the ``x`` coordinate of Widget
- ``lv_obj_get_scroll_y(widget)`` Get the ``y`` coordinate of Widget
- ``lv_obj_get_scroll_top(widget)`` Get the scroll coordinate from the top
- ``lv_obj_get_scroll_bottom(widget)`` Get the scroll coordinate from the bottom
- ``lv_obj_get_scroll_left(widget)`` Get the scroll coordinate from the left
- ``lv_obj_get_scroll_right(widget)`` Get the scroll coordinate from the right
Self size
*********
Self size is a property of an object. Normally, the user shouldn't use
Self size is a property of a Widget. Normally, the user shouldn't use
this parameter but if a custom widget is created it might be useful.
In short, self size establishes the size of an object's content. To
In short, self size establishes the size of a Widget's content. To
understand it better take the example of a table. Let's say it has 10
rows each with 50 px height. So the total height of the content is 500
px. In other words the "self height" is 500 px. If the user sets only
200 px height for the table LVGL will see that the self size is larger
and make the table scrollable.
This means not only the children can make an object scrollable but a
larger self size will too.
This means not only the children can make a Widget scrollable but a
larger self size will as well.
LVGL uses the :cpp:enumerator:`LV_EVENT_GET_SELF_SIZE` event to get the self size of
an object. Here is an example to see how to handle the event:
a Widget. Here is an example to see how to handle the event:
.. code-block:: c
@ -279,12 +281,14 @@ an object. Here is an example to see how to handle the event:
.. _scroll_example:
Examples
********
.. include:: ../examples/scroll/index.rst
.. include:: ../../examples/scroll/index.rst
.. _scroll_api:
API
***

11
docs/details/base-widget/styles/index.rst Normal file
View File

@ -0,0 +1,11 @@
.. _styles:
======
Styles
======
.. toctree::
:maxdepth: 2
style
style-properties

192
docs/overview/style-props.rst → docs/details/base-widget/styles/style-properties.rst
View File

@ -1,16 +1,18 @@
.. _style_properties:
================
Style properties
Style Properties
================
Size and position
-----------------
Properties related to size, position, alignment and layout of the objects.
Properties related to size, position, alignment and layout of Widgets.
width
~~~~~
Sets the width of object. Pixel, percentage and `LV_SIZE_CONTENT` values can be used. Percentage values are relative to the width of the parent's content area.
Sets width of Widget. Pixel, percentage and `LV_SIZE_CONTENT` values can be used. Percentage values are relative to the width of the parent's content area.
.. raw:: html
@ -52,7 +54,7 @@ Sets a maximal width. Pixel and percentage values can be used. Percentage values
height
~~~~~~
Sets the height of object. Pixel, percentage and `LV_SIZE_CONTENT` can be used. Percentage values are relative to the height of the parent's content area.
Sets height of Widget. Pixel, percentage and `LV_SIZE_CONTENT` can be used. Percentage values are relative to the height of the parent's content area.
.. raw:: html
@ -94,7 +96,7 @@ Sets a maximal height. Pixel and percentage values can be used. Percentage value
length
~~~~~~
Its meaning depends on the type of the widget. For example in case of lv_scale it means the length of the ticks.
Its meaning depends on the type of Widget. For example in case of lv_scale it means the length of the ticks.
.. raw:: html
@ -108,7 +110,7 @@ Its meaning depends on the type of the widget. For example in case of lv_scale i
x
~
Set the X coordinate of the object considering the set `align`. Pixel and percentage values can be used. Percentage values are relative to the width of the parent's content area.
Set X coordinate of Widget considering the ``align`` setting. Pixel and percentage values can be used. Percentage values are relative to the width of the parent's content area.
.. raw:: html
@ -122,7 +124,7 @@ Set the X coordinate of the object considering the set `align`. Pixel and percen
y
~
Set the Y coordinate of the object considering the set `align`. Pixel and percentage values can be used. Percentage values are relative to the height of the parent's content area.
Set Y coordinate of Widget considering the ``align`` setting. Pixel and percentage values can be used. Percentage values are relative to the height of the parent's content area.
.. raw:: html
@ -136,7 +138,7 @@ Set the Y coordinate of the object considering the set `align`. Pixel and percen
align
~~~~~
Set the alignment which tells from which point of the parent the X and Y coordinates should be interpreted. The possible values are: `LV_ALIGN_DEFAULT`, `LV_ALIGN_TOP_LEFT/MID/RIGHT`, `LV_ALIGN_BOTTOM_LEFT/MID/RIGHT`, `LV_ALIGN_LEFT/RIGHT_MID`, `LV_ALIGN_CENTER`. `LV_ALIGN_DEFAULT` means `LV_ALIGN_TOP_LEFT` with LTR base direction and `LV_ALIGN_TOP_RIGHT` with RTL base direction.
Set the alignment which tells from which point of the parent the X and Y coordinates should be interpreted. Possible values are: `LV_ALIGN_DEFAULT`, `LV_ALIGN_TOP_LEFT/MID/RIGHT`, `LV_ALIGN_BOTTOM_LEFT/MID/RIGHT`, `LV_ALIGN_LEFT/RIGHT_MID`, `LV_ALIGN_CENTER`. `LV_ALIGN_DEFAULT` means `LV_ALIGN_TOP_LEFT` with LTR base direction and `LV_ALIGN_TOP_RIGHT` with RTL base direction.
.. raw:: html
@ -150,7 +152,7 @@ Set the alignment which tells from which point of the parent the X and Y coordin
transform_width
~~~~~~~~~~~~~~~
Make the object wider on both sides with this value. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to the object's width.
Make Widget wider on both sides with this value. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to Widget's width.
.. raw:: html
@ -164,7 +166,7 @@ Make the object wider on both sides with this value. Pixel and percentage (with
transform_height
~~~~~~~~~~~~~~~~
Make the object higher on both sides with this value. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to the object's height.
Make Widget higher on both sides with this value. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to Widget's height.
.. raw:: html
@ -178,7 +180,7 @@ Make the object higher on both sides with this value. Pixel and percentage (with
translate_x
~~~~~~~~~~~
Move the object with this value in X direction. Applied after layouts, aligns and other positioning. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to the object's width.
Move Widget with this value in X direction. Applied after layouts, aligns and other positioning. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to Widget's width.
.. raw:: html
@ -192,7 +194,7 @@ Move the object with this value in X direction. Applied after layouts, aligns an
translate_y
~~~~~~~~~~~
Move the object with this value in Y direction. Applied after layouts, aligns and other positioning. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to the object's height.
Move Widget with this value in Y direction. Applied after layouts, aligns and other positioning. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to Widget's height.
.. raw:: html
@ -206,7 +208,7 @@ Move the object with this value in Y direction. Applied after layouts, aligns an
translate_radial
~~~~~~~~~~~~~~~~
Move the object around the centre of the parent object (e.g. around the circumference of a scale)
Move object around the centre of the parent object (e.g. around the circumference of a scale)
.. raw:: html
@ -220,7 +222,7 @@ Move the object around the centre of the parent object (e.g. around the circumfe
transform_scale_x
~~~~~~~~~~~~~~~~~
Zoom an objects horizontally. The value 256 (or `LV_SCALE_NONE`) means normal size, 128 half size, 512 double size, and so on
Zoom Widget horizontally. The value 256 (or `LV_SCALE_NONE`) means normal size, 128 half size, 512 double size, and so on
.. raw:: html
@ -234,7 +236,7 @@ Zoom an objects horizontally. The value 256 (or `LV_SCALE_NONE`) means normal si
transform_scale_y
~~~~~~~~~~~~~~~~~
Zoom an objects vertically. The value 256 (or `LV_SCALE_NONE`) means normal size, 128 half size, 512 double size, and so on
Zoom Widget vertically. The value 256 (or `LV_SCALE_NONE`) means normal size, 128 half size, 512 double size, and so on
.. raw:: html
@ -248,7 +250,7 @@ Zoom an objects vertically. The value 256 (or `LV_SCALE_NONE`) means normal size
transform_rotation
~~~~~~~~~~~~~~~~~~
Rotate an objects. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg.
Rotate Widget. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg.
.. raw:: html
@ -262,7 +264,7 @@ Rotate an objects. The value is interpreted in 0.1 degree units. E.g. 450 means
transform_pivot_x
~~~~~~~~~~~~~~~~~
Set the pivot point's X coordinate for transformations. Relative to the object's top left corner'
Set pivot point's X coordinate for transformations. Relative to Widget's top left corner'
.. raw:: html
@ -276,7 +278,7 @@ Set the pivot point's X coordinate for transformations. Relative to the object's
transform_pivot_y
~~~~~~~~~~~~~~~~~
Set the pivot point's Y coordinate for transformations. Relative to the object's top left corner'
Set pivot point's Y coordinate for transformations. Relative to Widget's top left corner'
.. raw:: html
@ -290,7 +292,7 @@ Set the pivot point's Y coordinate for transformations. Relative to the object's
transform_skew_x
~~~~~~~~~~~~~~~~
Skew an object horizontally. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg.
Skew Widget horizontally. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg.
.. raw:: html
@ -304,7 +306,7 @@ Skew an object horizontally. The value is interpreted in 0.1 degree units. E.g.
transform_skew_y
~~~~~~~~~~~~~~~~
Skew an object vertically. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg.
Skew Widget vertically. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg.
.. raw:: html
@ -407,7 +409,7 @@ Sets the padding between the columns. Used by the layouts.
pad_radial
~~~~~~~~~~
Pad the text labels away from the scale ticks/remainder of the LV_PART_
Pad text labels away from the scale ticks/remainder of the LV_PART_
.. raw:: html
@ -421,12 +423,12 @@ Pad the text labels away from the scale ticks/remainder of the LV_PART_
Margin
------
Properties to describe spacing around an object. Very similar to the margin properties in HTML.
Properties to describe spacing around a Widget. Very similar to the margin properties in HTML.
margin_top
~~~~~~~~~~
Sets the margin on the top. The object will keep this space from its siblings in layouts.
Sets margin on the top. Widget will keep this space from its siblings in layouts.
.. raw:: html
@ -440,7 +442,7 @@ Sets the margin on the top. The object will keep this space from its siblings in
margin_bottom
~~~~~~~~~~~~~
Sets the margin on the bottom. The object will keep this space from its siblings in layouts.
Sets margin on the bottom. Widget will keep this space from its siblings in layouts.
.. raw:: html
@ -454,7 +456,7 @@ Sets the margin on the bottom. The object will keep this space from its siblings
margin_left
~~~~~~~~~~~
Sets the margin on the left. The object will keep this space from its siblings in layouts.
Sets margin on the left. Widget will keep this space from its siblings in layouts.
.. raw:: html
@ -468,7 +470,7 @@ Sets the margin on the left. The object will keep this space from its siblings i
margin_right
~~~~~~~~~~~~
Sets the margin on the right. The object will keep this space from its siblings in layouts.
Sets margin on the right. Widget will keep this space from its siblings in layouts.
.. raw:: html
@ -482,12 +484,12 @@ Sets the margin on the right. The object will keep this space from its siblings
Background
----------
Properties to describe the background color and image of the objects.
Properties to describe the background color and image of Widget.
bg_color
~~~~~~~~
Set the background color of the object.
Set background color of Widget.
.. raw:: html
@ -501,7 +503,7 @@ Set the background color of the object.
bg_opa
~~~~~~
Set the opacity of the background. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Set opacity of the background. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -515,7 +517,7 @@ Set the opacity of the background. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means
bg_grad_color
~~~~~~~~~~~~~
Set the gradient color of the background. Used only if `grad_dir` is not `LV_GRAD_DIR_NONE`
Set gradient color of the background. Used only if `grad_dir` is not `LV_GRAD_DIR_NONE`
.. raw:: html
@ -529,7 +531,7 @@ Set the gradient color of the background. Used only if `grad_dir` is not `LV_GRA
bg_grad_dir
~~~~~~~~~~~
Set the direction of the gradient of the background. The possible values are `LV_GRAD_DIR_NONE/HOR/VER`.
Set direction of the gradient of the background. Possible values are `LV_GRAD_DIR_NONE/HOR/VER`.
.. raw:: html
@ -543,7 +545,7 @@ Set the direction of the gradient of the background. The possible values are `LV
bg_main_stop
~~~~~~~~~~~~
Set the point from which the background color should start for gradients. 0 means to top/left side, 255 the bottom/right side, 128 the center, and so on
Set point from which background color should start for gradients. 0 means to top/left side, 255 the bottom/right side, 128 the center, and so on
.. raw:: html
@ -557,7 +559,7 @@ Set the point from which the background color should start for gradients. 0 mean
bg_grad_stop
~~~~~~~~~~~~
Set the point from which the background's gradient color should start. 0 means to top/left side, 255 the bottom/right side, 128 the center, and so on
Set point from which background's gradient color should start. 0 means to top/left side, 255 the bottom/right side, 128 the center, and so on
.. raw:: html
@ -571,7 +573,7 @@ Set the point from which the background's gradient color should start. 0 means t
bg_main_opa
~~~~~~~~~~~
Set the opacity of the first gradient color
Set opacity of the first gradient color
.. raw:: html
@ -585,7 +587,7 @@ Set the opacity of the first gradient color
bg_grad_opa
~~~~~~~~~~~
Set the opacity of the second gradient color
Set opacity of the second gradient color
.. raw:: html
@ -599,7 +601,7 @@ Set the opacity of the second gradient color
bg_grad
~~~~~~~
Set the gradient definition. The pointed instance must exist while the object is alive. NULL to disable. It wraps `BG_GRAD_COLOR`, `BG_GRAD_DIR`, `BG_MAIN_STOP` and `BG_GRAD_STOP` into one descriptor and allows creating gradients with more colors too. If it's set other gradient related properties will be ignored'
Set gradient definition. The pointed instance must exist while Widget is alive. NULL to disable. It wraps `BG_GRAD_COLOR`, `BG_GRAD_DIR`, `BG_MAIN_STOP` and `BG_GRAD_STOP` into one descriptor and allows creating gradients with more colors as well. If it's set other gradient related properties will be ignored'
.. raw:: html
@ -627,7 +629,7 @@ Set a background image. Can be a pointer to `lv_image_dsc_t`, a path to a file o
bg_image_opa
~~~~~~~~~~~~
Set the opacity of the background image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Set opacity of the background image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -655,7 +657,7 @@ Set a color to mix to the background image.
bg_image_recolor_opa
~~~~~~~~~~~~~~~~~~~~
Set the intensity of background image recoloring. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means no mixing, 255, `LV_OPA_100` or `LV_OPA_COVER` means full recoloring, other values or LV_OPA_10, LV_OPA_20, etc are interpreted proportionally.
Set intensity of background image recoloring. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means no mixing, 255, `LV_OPA_100` or `LV_OPA_COVER` means full recoloring, other values or LV_OPA_10, LV_OPA_20, etc are interpreted proportionally.
.. raw:: html
@ -669,7 +671,7 @@ Set the intensity of background image recoloring. Value 0, `LV_OPA_0` or `LV_OPA
bg_image_tiled
~~~~~~~~~~~~~~
If enabled the background image will be tiled. The possible values are `true` or `false`.
If enabled the background image will be tiled. Possible values are `true` or `false`.
.. raw:: html
@ -688,7 +690,7 @@ Properties to describe the borders
border_color
~~~~~~~~~~~~
Set the color of the border
Set color of the border
.. raw:: html
@ -702,7 +704,7 @@ Set the color of the border
border_opa
~~~~~~~~~~
Set the opacity of the border. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Set opacity of the border. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -716,7 +718,7 @@ Set the opacity of the border. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means full
border_width
~~~~~~~~~~~~
Set the width of the border. Only pixel values can be used.
Set width of the border. Only pixel values can be used.
.. raw:: html
@ -730,7 +732,7 @@ Set the width of the border. Only pixel values can be used.
border_side
~~~~~~~~~~~
Set only which side(s) the border should be drawn. The possible values are `LV_BORDER_SIDE_NONE/TOP/BOTTOM/LEFT/RIGHT/INTERNAL`. OR-ed values can be used as well, e.g. `LV_BORDER_SIDE_TOP | LV_BORDER_SIDE_LEFT`.
Set only which side(s) the border should be drawn. Possible values are `LV_BORDER_SIDE_NONE/TOP/BOTTOM/LEFT/RIGHT/INTERNAL`. OR-ed values can be used as well, e.g. `LV_BORDER_SIDE_TOP | LV_BORDER_SIDE_LEFT`.
.. raw:: html
@ -763,7 +765,7 @@ Properties to describe the outline. It's like a border but drawn outside of the
outline_width
~~~~~~~~~~~~~
Set the width of the outline in pixels.
Set width of outline in pixels.
.. raw:: html
@ -777,7 +779,7 @@ Set the width of the outline in pixels.
outline_color
~~~~~~~~~~~~~
Set the color of the outline.
Set color of outline.
.. raw:: html
@ -791,7 +793,7 @@ Set the color of the outline.
outline_opa
~~~~~~~~~~~
Set the opacity of the outline. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Set opacity of outline. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -805,7 +807,7 @@ Set the opacity of the outline. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means ful
outline_pad
~~~~~~~~~~~
Set the padding of the outline, i.e. the gap between object and the outline.
Set padding of outline, i.e. the gap between Widget and the outline.
.. raw:: html
@ -824,7 +826,7 @@ Properties to describe the shadow drawn under the rectangles.
shadow_width
~~~~~~~~~~~~
Set the width of the shadow in pixels. The value should be >= 0.
Set width of the shadow in pixels. The value should be >= 0.
.. raw:: html
@ -838,7 +840,7 @@ Set the width of the shadow in pixels. The value should be >= 0.
shadow_offset_x
~~~~~~~~~~~~~~~
Set an offset on the shadow in pixels in X direction.
Set an offset on the shadow in pixels in X direction.
.. raw:: html
@ -852,7 +854,7 @@ Set an offset on the shadow in pixels in X direction.
shadow_offset_y
~~~~~~~~~~~~~~~
Set an offset on the shadow in pixels in Y direction.
Set an offset on the shadow in pixels in Y direction.
.. raw:: html
@ -866,7 +868,7 @@ Set an offset on the shadow in pixels in Y direction.
shadow_spread
~~~~~~~~~~~~~
Make the shadow calculation to use a larger or smaller rectangle as base. The value can be in pixel to make the area larger/smaller
Make shadow calculation to use a larger or smaller rectangle as base. The value can be in pixels to make the area larger/smaller
.. raw:: html
@ -880,7 +882,7 @@ Make the shadow calculation to use a larger or smaller rectangle as base. The va
shadow_color
~~~~~~~~~~~~
Set the color of the shadow
Set color of shadow
.. raw:: html
@ -894,7 +896,7 @@ Set the color of the shadow
shadow_opa
~~~~~~~~~~
Set the opacity of the shadow. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Set opacity of shadow. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -913,7 +915,7 @@ Properties to describe the images
image_opa
~~~~~~~~~
Set the opacity of an image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Set opacity of an image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -927,7 +929,7 @@ Set the opacity of an image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully
image_recolor
~~~~~~~~~~~~~
Set color to mixt to the image.
Set color to mix with the image.
.. raw:: html
@ -941,7 +943,7 @@ Set color to mixt to the image.
image_recolor_opa
~~~~~~~~~~~~~~~~~
Set the intensity of the color mixing. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Set intensity of color mixing. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -955,12 +957,12 @@ Set the intensity of the color mixing. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` me
Line
----
Properties to describe line-like objects
Properties to describe line-like Widgets
line_width
~~~~~~~~~~
Set the width of the lines in pixel.
Set width of lines in pixels.
.. raw:: html
@ -974,7 +976,7 @@ Set the width of the lines in pixel.
line_dash_width
~~~~~~~~~~~~~~~
Set the width of dashes in pixel. Note that dash works only on horizontal and vertical lines
Set width of dashes in pixels. Note that dash works only on horizontal and vertical lines
.. raw:: html
@ -988,7 +990,7 @@ Set the width of dashes in pixel. Note that dash works only on horizontal and ve
line_dash_gap
~~~~~~~~~~~~~
Set the gap between dashes in pixel. Note that dash works only on horizontal and vertical lines
Set gap between dashes in pixels. Note that dash works only on horizontal and vertical lines
.. raw:: html
@ -1002,7 +1004,7 @@ Set the gap between dashes in pixel. Note that dash works only on horizontal and
line_rounded
~~~~~~~~~~~~
Make the end points of the lines rounded. `true`: rounded, `false`: perpendicular line ending
Make end points of the lines rounded. `true`: rounded, `false`: perpendicular line ending
.. raw:: html
@ -1016,7 +1018,7 @@ Make the end points of the lines rounded. `true`: rounded, `false`: perpendicula
line_color
~~~~~~~~~~
Set the color of the lines.
Set color of lines.
.. raw:: html
@ -1030,7 +1032,7 @@ Set the color of the lines.
line_opa
~~~~~~~~
Set the opacity of the lines.
Set opacity of lines.
.. raw:: html
@ -1049,7 +1051,7 @@ TODO
arc_width
~~~~~~~~~
Set the width (thickness) of the arcs in pixel.
Set width (thickness) of arcs in pixels.
.. raw:: html
@ -1063,7 +1065,7 @@ Set the width (thickness) of the arcs in pixel.
arc_rounded
~~~~~~~~~~~
Make the end points of the arcs rounded. `true`: rounded, `false`: perpendicular line ending
Make end points of arcs rounded. `true`: rounded, `false`: perpendicular line ending
.. raw:: html
@ -1077,7 +1079,7 @@ Make the end points of the arcs rounded. `true`: rounded, `false`: perpendicular
arc_color
~~~~~~~~~
Set the color of the arc.
Set color of arc.
.. raw:: html
@ -1091,7 +1093,7 @@ Set the color of the arc.
arc_opa
~~~~~~~
Set the opacity of the arcs.
Set opacity of arcs.
.. raw:: html
@ -1105,7 +1107,7 @@ Set the opacity of the arcs.
arc_image_src
~~~~~~~~~~~~~
Set an image from which the arc will be masked out. It's useful to display complex effects on the arcs. Can be a pointer to `lv_image_dsc_t` or a path to a file
Set an image from which arc will be masked out. It's useful to display complex effects on the arcs. Can be a pointer to `lv_image_dsc_t` or a path to a file
.. raw:: html
@ -1124,7 +1126,7 @@ Properties to describe the properties of text. All these properties are inherite
text_color
~~~~~~~~~~
Sets the color of the text.
Sets color of text.
.. raw:: html
@ -1138,7 +1140,7 @@ Sets the color of the text.
text_opa
~~~~~~~~
Set the opacity of the text. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Set opacity of text. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -1152,7 +1154,7 @@ Set the opacity of the text. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully
text_font
~~~~~~~~~
Set the font of the text (a pointer `lv_font_t *`).
Set font of text (a pointer `lv_font_t *`).
.. raw:: html
@ -1166,7 +1168,7 @@ Set the font of the text (a pointer `lv_font_t *`).
text_letter_space
~~~~~~~~~~~~~~~~~
Set the letter space in pixels
Set letter space in pixels
.. raw:: html
@ -1180,7 +1182,7 @@ Set the letter space in pixels
text_line_space
~~~~~~~~~~~~~~~
Set the line space in pixels.
Set line space in pixels.
.. raw:: html
@ -1194,7 +1196,7 @@ Set the line space in pixels.
text_decor
~~~~~~~~~~
Set decoration for the text. The possible values are `LV_TEXT_DECOR_NONE/UNDERLINE/STRIKETHROUGH`. OR-ed values can be used as well.
Set decoration for the text. Possible values are `LV_TEXT_DECOR_NONE/UNDERLINE/STRIKETHROUGH`. OR-ed values can be used as well.
.. raw:: html
@ -1208,7 +1210,7 @@ Set decoration for the text. The possible values are `LV_TEXT_DECOR_NONE/UNDERLI
text_align
~~~~~~~~~~
Set how to align the lines of the text. Note that it doesn't align the object itself, only the lines inside the object. The possible values are `LV_TEXT_ALIGN_LEFT/CENTER/RIGHT/AUTO`. `LV_TEXT_ALIGN_AUTO` detect the text base direction and uses left or right alignment accordingly
Set how to align the lines of the text. Note that it doesn't align the Widget itself, only the lines inside the Widget. Possible values are `LV_TEXT_ALIGN_LEFT/CENTER/RIGHT/AUTO`. `LV_TEXT_ALIGN_AUTO` detect the text base direction and uses left or right alignment accordingly
.. raw:: html
@ -1227,7 +1229,7 @@ Mixed properties for various purposes.
radius
~~~~~~
Set the radius on every corner. The value is interpreted in pixel (>= 0) or `LV_RADIUS_CIRCLE` for max. radius
Set radius on every corner. The value is interpreted in pixels (>= 0) or `LV_RADIUS_CIRCLE` for max. radius
.. raw:: html
@ -1241,7 +1243,7 @@ Set the radius on every corner. The value is interpreted in pixel (>= 0) or `LV_
radial_offset
~~~~~~~~~~~~~
Move the start point of the object (e.g. scale tick) radially
Move start point of object (e.g. scale tick) radially
.. raw:: html
@ -1269,7 +1271,7 @@ Enable to clip the overflowed content on the rounded corner. Can be `true` or `f
opa
~~~
Scale down all opacity values of the object by this factor. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
Scale down all opacity values of the Widget by this factor. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -1283,7 +1285,7 @@ Scale down all opacity values of the object by this factor. Value 0, `LV_OPA_0`
opa_layered
~~~~~~~~~~~
First draw the object on the layer, then scale down layer opacity factor. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
First draw Widget on the layer, then scale down layer opacity factor. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency.
.. raw:: html
@ -1297,7 +1299,7 @@ First draw the object on the layer, then scale down layer opacity factor. Value
color_filter_dsc
~~~~~~~~~~~~~~~~
Mix a color to all colors of the object.
Mix a color with all colors of the Widget.
.. raw:: html
@ -1325,7 +1327,7 @@ The intensity of mixing of color filter.
anim
~~~~
The animation template for the object's animation. Should be a pointer to `lv_anim_t`. The animation parameters are widget specific, e.g. animation time could be the E.g. blink time of the cursor on the text area or scroll time of a roller. See the widgets' documentation to learn more.
Animation template for Widget's animation. Should be a pointer to `lv_anim_t`. The animation parameters are widget specific, e.g. animation time could be the E.g. blink time of the cursor on the text area or scroll time of a roller. See Widgets' documentation to learn more.
.. raw:: html
@ -1339,7 +1341,7 @@ The animation template for the object's animation. Should be a pointer to `lv_an
anim_duration
~~~~~~~~~~~~~
The animation duration in milliseconds. Its meaning is widget specific. E.g. blink time of the cursor on the text area or scroll time of a roller. See the widgets' documentation to learn more.
Animation duration in milliseconds. Its meaning is widget specific. E.g. blink time of the cursor on the text area or scroll time of a roller. See Widgets' documentation to learn more.
.. raw:: html
@ -1353,7 +1355,7 @@ The animation duration in milliseconds. Its meaning is widget specific. E.g. bli
transition
~~~~~~~~~~
An initialized `lv_style_transition_dsc_t` to describe a transition.
An initialized ``lv_style_transition_dsc_t`` to describe a transition.
.. raw:: html
@ -1367,7 +1369,7 @@ An initialized `lv_style_transition_dsc_t` to describe a transition.
blend_mode
~~~~~~~~~~
Describes how to blend the colors to the background. The possible values are `LV_BLEND_MODE_NORMAL/ADDITIVE/SUBTRACTIVE/MULTIPLY`
Describes how to blend the colors to the background. Possible values are `LV_BLEND_MODE_NORMAL/ADDITIVE/SUBTRACTIVE/MULTIPLY`
.. raw:: html
@ -1381,7 +1383,7 @@ Describes how to blend the colors to the background. The possible values are `LV
layout
~~~~~~
Set the layout if the object. The children will be repositioned and resized according to the policies set for the layout. For the possible values see the documentation of the layouts.
Set layout of Widget. Children will be repositioned and resized according to policies set for the layout. For possible values see documentation of the layouts.
.. raw:: html
@ -1395,7 +1397,7 @@ Set the layout if the object. The children will be repositioned and resized acco
base_dir
~~~~~~~~
Set the base direction of the object. The possible values are `LV_BIDI_DIR_LTR/RTL/AUTO`.
Set base direction of Widget. Possible values are `LV_BIDI_DIR_LTR/RTL/AUTO`.
.. raw:: html
@ -1409,7 +1411,7 @@ Set the base direction of the object. The possible values are `LV_BIDI_DIR_LTR/R
bitmap_mask_src
~~~~~~~~~~~~~~~
If set a layer will be created for the widget and the layer will be masked with this A8 bitmap mask.
If set, a layer will be created for the widget and the layer will be masked with this A8 bitmap mask.
.. raw:: html
@ -1423,7 +1425,7 @@ If set a layer will be created for the widget and the layer will be masked with
rotary_sensitivity
~~~~~~~~~~~~~~~~~~
Adjust the sensitivity for rotary encoders in 1/256 unit. It means, 128: slow down the rotary to half, 512: speeds up to double, 256: no change
Adjust sensitivity for rotary encoders in 1/256 unit. It means, 128: slow down the rotary to half, 512: speeds up to double, 256: no change
.. raw:: html
@ -1498,7 +1500,7 @@ Defines how to align the tracks of the flow
flex_grow
~~~~~~~~~
Defines how much space to take proportionally from the free space of the object's track
Defines how much space to take proportionally from the free space of the Widget's track
.. raw:: html
@ -1573,7 +1575,7 @@ Defines how to distribute the rows.
grid_cell_column_pos
~~~~~~~~~~~~~~~~~~~~
Set the column in which the object should be placed
Set column in which Widget should be placed.
.. raw:: html
@ -1587,7 +1589,7 @@ Set the column in which the object should be placed
grid_cell_x_align
~~~~~~~~~~~~~~~~~
Set how to align the object horizontally.
Set how to align Widget horizontally.
.. raw:: html
@ -1601,7 +1603,7 @@ Set how to align the object horizontally.
grid_cell_column_span
~~~~~~~~~~~~~~~~~~~~~
Set how many columns the object should span. Needs to be >= 1
Set how many columns Widget should span. Needs to be >= 1.
.. raw:: html
@ -1615,7 +1617,7 @@ Set how many columns the object should span. Needs to be >= 1
grid_cell_row_pos
~~~~~~~~~~~~~~~~~
Set the row in which the object should be placed
Set row in which Widget should be placed.
.. raw:: html
@ -1629,7 +1631,7 @@ Set the row in which the object should be placed
grid_cell_y_align
~~~~~~~~~~~~~~~~~
Set how to align the object vertically.
Set how to align Widget vertically.
.. raw:: html
@ -1643,7 +1645,7 @@ Set how to align the object vertically.
grid_cell_row_span
~~~~~~~~~~~~~~~~~~
Set how many rows the object should span. Needs to be >= 1
Set how many rows Widget should span. Needs to be >= 1.
.. raw:: html

157
docs/overview/style.rst → docs/details/base-widget/styles/style.rst
View File

@ -1,20 +1,20 @@
.. _styles:
.. _style_details:
======
Styles
======
=============
Style Details
=============
*Styles* are used to set the appearance of objects. Styles in lvgl are
heavily inspired by CSS. The concept in a nutshell is as follows: - A
*Styles* are used to set the appearance of Widgets. Styles in lvgl are
heavily inspired by CSS. The concept in a nutshell is that a
style is an :cpp:type:`lv_style_t` variable which can hold properties like
border width, text color and so on. It's similar to a ``class`` in CSS.
border width, font, text color and so on. It's similar to a ``class`` in CSS.
- Styles can be assigned to objects to change their appearance. Upon
- Styles can be assigned to Widgets to change their appearance. Upon
assignment, the target part (*pseudo-element* in CSS) and target state
(*pseudo class*) can be specified. For example one can add
``style_blue`` to the knob of a slider when it's in pressed state.
- The same style can be used by any number of objects.
- Styles can be cascaded which means multiple styles may be assigned to an object and
- The same style can be used by any number of Widgets.
- Styles can be cascaded which means multiple styles may be assigned to a Widget and
each style can have different properties. Therefore, not all properties
have to be specified in a style. LVGL will search for a property until a
style defines it or use a default if it's not specified by any of the
@ -22,19 +22,19 @@ border width, text color and so on. It's similar to a ``class`` in CSS.
and ``style_btn_red`` can add only a ``background-color=red`` to
overwrite the background color.
- The most recently added style has higher precedence. This means if a property
is specified in two styles the newest style in the object will be used.
- Some properties (e.g. text color) can be inherited from a parent(s) if it's not specified in an object.
- Objects can also have local styles with higher precedence than "normal" styles.
is specified in two styles the newest style in the Widget will be used.
- Some properties (e.g. text color) can be inherited from a parent(s) if it's not specified in a Widget.
- Widgets can also have local styles with higher precedence than "normal" styles.
- Unlike CSS (where pseudo-classes describe different states, e.g. ``:focus``),
in LVGL a property is assigned to a given state.
- Transitions can be applied when the object changes state.
- Transitions can be applied when the Widget changes state.
.. _styles_states:
States
******
The objects can be in the combination of the following states:
The Widgets can be in the combination of the following states:
- :cpp:enumerator:`LV_STATE_DEFAULT`: (0x0000) Normal, released state
- :cpp:enumerator:`LV_STATE_CHECKED`: (0x0001) Toggled or checked state
@ -50,7 +50,7 @@ The objects can be in the combination of the following states:
- :cpp:enumerator:`LV_STATE_USER_3`: (0x4000) Custom state
- :cpp:enumerator:`LV_STATE_USER_4`: (0x8000) Custom state
An object can be in a combination of states such as being focused and
A Widget can be in a combination of states such as being focused and
pressed at the same time. This is represented as :cpp:expr:`LV_STATE_FOCUSED | LV_STATE_PRESSED`.
A style can be added to any state or state combination. For example,
@ -70,35 +70,35 @@ defined like this:
- :cpp:enumerator:`LV_STATE_PRESSED`: gray
- :cpp:enumerator:`LV_STATE_FOCUSED`: red
1. Initially the object is in the default state, so it's a simple case:
the property is perfectly defined in the object's current state as
1. Initially the Widget is in the default state, so it's a simple case:
the property is perfectly defined in the Widget's current state as
white.
2. When the object is pressed there are 2 related properties: default
2. When the Widget is pressed there are 2 related properties: default
with white (default is related to every state) and pressed with gray.
The pressed state has 0x0020 precedence which is higher than the
default state's 0x0000 precedence, so gray color will be used.
3. When the object is focused the same thing happens as in pressed state
3. When the Widget has focus the same thing happens as in pressed state
and red color will be used. (Focused state has higher precedence than
default state).
4. When the object is focused and pressed both gray and red would work,
4. When the Widget has focus and pressed both gray and red would work,
but the pressed state has higher precedence than focused so gray
color will be used.
5. It's possible to set e.g. rose color for :cpp:expr:`LV_STATE_PRESSED | LV_STATE_FOCUSED`.
In this case, this combined state has 0x0020 + 0x0002 = 0x0022 precedence, which is higher than
the pressed state's precedence so rose color would be used.
6. When the object is in the checked state there is no property to set
6. When the Widget is in the checked state there is no property to set
the background color for this state. So for lack of a better option,
the object remains white from the default state's property.
the Widget remains white from the default state's property.
Some practical notes:
- The precedence (value) of states is quite intuitive, and it's something the
user would expect naturally. E.g. if an object is focused the user will still
user would expect naturally. E.g. if a Widget has focus the user will still
want to see if it's pressed, therefore the pressed state has a higher
precedence. If the focused state had a higher precedence it would overwrite
the pressed color.
- If you want to set a property for all states (e.g. red background color)
just set it for the default state. If the object can't find a property
just set it for the default state. If the Widget can't find a property
for its current state it will fall back to the default state's property.
- Use ORed states to describe the properties for complex cases. (E.g.
pressed + checked + focused)
@ -115,7 +115,7 @@ Cascading styles
****************
It's not required to set all the properties in one style. It's possible
to add more styles to an object and have the latter added style modify
to add more styles to a Widget and have the latter added style modify
or extend appearance. For example, create a general gray button style
and create a new one for red buttons where only the new background color
is set.
@ -144,10 +144,10 @@ Inheritance
***********
Some properties (typically those related to text) can be inherited from
the parent object's styles. Inheritance is applied only if the given
property is not set in the object's styles (even in default state). In
the parent Widget's styles. Inheritance is applied only if the given
property is not set in the Widget's styles (even in default state). In
this case, if the property is inheritable, the property's value will be
searched in the parents until an object specifies a value for the
searched in the parents until a Widget specifies a value for the
property. The parents will use their own state to determine the value.
So if a button is pressed, and the text color comes from here, the
pressed text color will be used.
@ -157,7 +157,7 @@ pressed text color will be used.
Parts
*****
Objects can be composed of *parts* which may each have their own styles.
Widgets can be composed of *parts* which may each have their own styles.
The following predefined parts exist in LVGL:
@ -177,7 +177,7 @@ For example a :ref:`Slider <lv_slider>` has three parts:
- Knob
This means all three parts of the slider can have their own styles. See
later how to add styles to objects and parts.
later how to add styles to Widgets and parts.
.. _styles_initialize:
@ -220,7 +220,7 @@ To get a property's value from a style:
lv_style_value_t v;
lv_result_t res = lv_style_get_prop(&style, LV_STYLE_BG_COLOR, &v);
if(res == LV_RESULT_OK) { /*Found*/
if(res == LV_RESULT_OK) { /* Found */
do_something(v.color);
}
@ -236,7 +236,7 @@ To reset a style (free all its data) use:
lv_style_reset(&style);
Styles can be built as ``const`` too to save RAM:
Styles can be built as ``const`` as well to save RAM:
.. code-block:: c
@ -256,35 +256,35 @@ new properties cannot be added.
Add and remove styles to a widget
*********************************
A style on its own is not that useful. It must be assigned to an object
A style on its own is not that useful. It must be assigned to a Widget
to take effect.
Add styles
----------
To add a style to an object use
``lv_obj_add_style(obj, &style, <selector>)``. ``<selector>`` is an
To add a style to a Widget use
``lv_obj_add_style(widget, &style, <selector>)``. ``<selector>`` is an
OR-ed value of parts and state to which the style should be added. Some
examples:
- :cpp:expr:`LV_PART_MAIN | LV_STATE_DEFAULT`
- :cpp:enumerator:`LV_STATE_PRESSED`: The main part in pressed state. :cpp:enumerator:`LV_PART_MAIN` can be omitted
- :cpp:enumerator:`LV_PART_SCROLLBAR`: The scrollbar part in the default state. :cpp:enumerator:`LV_STATE_DEFAULT` can be omitted.
- :cpp:expr:`LV_PART_SCROLLBAR | LV_STATE_SCROLLED`: The scrollbar part when the object is being scrolled
- :cpp:expr:`LV_PART_INDICATOR | LV_STATE_PRESSED | LV_STATE_CHECKED` The indicator part when the object is pressed and checked at the same time.
- :cpp:expr:`LV_PART_SCROLLBAR | LV_STATE_SCROLLED`: The scrollbar part when the Widget is being scrolled
- :cpp:expr:`LV_PART_INDICATOR | LV_STATE_PRESSED | LV_STATE_CHECKED` The indicator part when the Widget is pressed and checked at the same time.
Using :cpp:func:`lv_obj_add_style`:
.. code-block:: c
lv_obj_add_style(btn, &style_btn, 0); /*Default button style*/
lv_obj_add_style(btn, &btn_red, LV_STATE_PRESSED); /*Overwrite only some colors to red when pressed*/
lv_obj_add_style(btn, &style_btn, 0); /* Default button style */
lv_obj_add_style(btn, &btn_red, LV_STATE_PRESSED); /* Overwrite only some colors to red when pressed */
Replace styles
--------------
To replace a specific style of an object use
:cpp:expr:`lv_obj_replace_style(obj, old_style, new_style, selector)`. This
To replace a specific style of a Widget use
:cpp:expr:`lv_obj_replace_style(widget, old_style, new_style, selector)`. This
function will only replace ``old_style`` with ``new_style`` if the
``selector`` matches the ``selector`` used in ``lv_obj_add_style``. Both
styles, i.e. ``old_style`` and ``new_style``, must not be ``NULL`` (for
@ -298,16 +298,16 @@ Using :cpp:func:`lv_obj_replace_style`:
.. code-block:: c
lv_obj_add_style(btn, &style_btn, 0); /*Add a button style*/
lv_obj_replace_style(btn, &style_btn, &new_style_btn, 0); /*Replace the button style with a different one*/
lv_obj_add_style(btn, &style_btn, 0); /* Add a button style */
lv_obj_replace_style(btn, &style_btn, &new_style_btn, 0); /* Replace the button style with a different one */
Remove styles
-------------
To remove all styles from an object use :cpp:expr:`lv_obj_remove_style_all(obj)`.
To remove all styles from a Widget use :cpp:expr:`lv_obj_remove_style_all(widget)`.
To remove specific styles use
:cpp:expr:`lv_obj_remove_style(obj, style, selector)`. This function will remove
:cpp:expr:`lv_obj_remove_style(widget, style, selector)`. This function will remove
``style`` only if the ``selector`` matches with the ``selector`` used in
:cpp:func:`lv_obj_add_style`. ``style`` can be ``NULL`` to check only the
``selector`` and remove all matching styles. The ``selector`` can use
@ -317,65 +317,66 @@ any state or part.
Report style changes
--------------------
If a style which is already assigned to an object changes (i.e. a
property is added or changed), the objects using that style should be
If a style which is already assigned to a Widget changes (i.e. a
property is added or changed), the Widgets using that style should be
notified. There are 3 options to do this:
1. If you know that the changed properties can be applied by a simple redraw
(e.g. color or opacity changes) just call :cpp:expr:`lv_obj_invalidate(obj)`
(e.g. color or opacity changes) just call :cpp:expr:`lv_obj_invalidate(widget)`
or :cpp:expr:`lv_obj_invalidate(lv_screen_active())`.
2. If more complex style properties were changed or added, and you know which
object(s) are affected by that style call :cpp:expr:`lv_obj_refresh_style(obj, part, property)`.
To refresh all parts and properties use :cpp:expr:`lv_obj_refresh_style(obj, LV_PART_ANY, LV_STYLE_PROP_ANY)`.
3. To make LVGL check all objects to see if they use a style and refresh them
Widget(s) are affected by that style call :cpp:expr:`lv_obj_refresh_style(widget, part, property)`.
To refresh all parts and properties use :cpp:expr:`lv_obj_refresh_style(widget, LV_PART_ANY, LV_STYLE_PROP_ANY)`.
3. To make LVGL check all Widgets to see if they use a style and refresh them
when needed, call :cpp:expr:`lv_obj_report_style_change(&style)`. If ``style``
is ``NULL`` all objects will be notified about a style change.
is ``NULL`` all Widgets will be notified about a style change.
Get a property's value on an object
Get a property's value on a Widget
-----------------------------------
To get a final value of property
- considering cascading, inheritance, local styles and transitions (see below)
- property get functions like this can be used: ``lv_obj_get_style_<property_name>(obj, <part>)``.
These functions use the object's current state and if no better candidate exists they return a default value.
- property get functions like this can be used: ``lv_obj_get_style_<property_name>(widget, <part>)``.
These functions use the Widget's current state and if no better candidate exists they return a default value.
For example:
.. code-block:: c
lv_color_t color = lv_obj_get_style_bg_color(btn, LV_PART_MAIN);
lv_color_t color = lv_obj_get_style_bg_color(btn, LV_PART_MAIN);
.. _styles_local:
Local styles
************
In addition to "normal" styles, objects can also store local styles.
In addition to "normal" styles, Widgets can also store local styles.
This concept is similar to inline styles in CSS
(e.g. ``<div style="color:red">``) with some modification.
Local styles are like normal styles, but they can't be shared among
other objects. If used, local styles are allocated automatically, and
freed when the object is deleted. They are useful to add local
customization to an object.
other Widgets. If used, local styles are allocated automatically, and
freed when the Widget is deleted. They are useful to add local
customization to a Widget.
Unlike in CSS, LVGL local styles can be assigned to states
(*pseudo-classes*) and parts (*pseudo-elements*).
To set a local property use functions like
``lv_obj_set_style_<property_name>(obj, <value>, <selector>);`` For example:
``lv_obj_set_style_<property_name>(widget, <value>, <selector>);`` For example:
.. code-block:: c
lv_obj_set_style_bg_color(slider, lv_color_red(), LV_PART_INDICATOR | LV_STATE_FOCUSED);
lv_obj_set_style_bg_color(slider, lv_color_red(), LV_PART_INDICATOR | LV_STATE_FOCUSED);
.. _styles_properties:
Properties
**********
.. _style_properties_overview:
Style Properties Overview
*************************
For the full list of style properties click :ref:`here <style_properties>`.
For the full list of style properties click
:ref:`here <style_properties>`.
Typical background properties
-----------------------------
@ -397,7 +398,7 @@ background properties" are the ones related to:
Transitions
***********
By default, when an object changes state (e.g. it's pressed) the new
By default, when a Widget changes state (e.g. it's pressed) the new
properties from the new state are set immediately. However, with
transitions it's possible to play an animation on state change. For
example, on pressing a button its background color can be animated to
@ -413,7 +414,7 @@ possible to set
The transition properties can be defined for each state. For example,
setting a 500 ms transition time in the default state means that when
the object goes to the default state a 500 ms transition time is
the Widget goes to the default state a 500 ms transition time is
applied. Setting a 100 ms transition time in the pressed state causes a
100 ms transition when going to the pressed state. This example
configuration results in going to the pressed state quickly and then
@ -424,10 +425,10 @@ initialized and added to a style:
.. code-block:: c
/*Only its pointer is saved so must static, global or dynamically allocated */
/* Only its pointer is saved so must static, global or dynamically allocated */
static const lv_style_prop_t trans_props[] = {
LV_STYLE_BG_OPA, LV_STYLE_BG_COLOR,
0, /*End marker*/
0, /* End marker */
};
static lv_style_transition_dsc_t trans1;
@ -500,12 +501,12 @@ example shows how to set the "default" theme:
.. code-block:: c
lv_theme_t * th = lv_theme_default_init(display, /*Use the DPI, size, etc from this display*/
LV_COLOR_PALETTE_BLUE, LV_COLOR_PALETTE_CYAN, /*Primary and secondary palette*/
false, /*Light or dark mode*/
&lv_font_montserrat_10, &lv_font_montserrat_14, &lv_font_montserrat_18); /*Small, normal, large fonts*/
lv_theme_t * th = lv_theme_default_init(display, /* Use the DPI, size, etc from this display */
LV_COLOR_PALETTE_BLUE, LV_COLOR_PALETTE_CYAN, /* Primary and secondary palette */
false, /* Light or dark mode */
&lv_font_montserrat_10, &lv_font_montserrat_14, &lv_font_montserrat_18); /* Small, normal, large fonts */
lv_display_set_theme(display, th); /*Assign the theme to the display*/
lv_display_set_theme(display, th); /* Assign the theme to the display */
The included themes are enabled in ``lv_conf.h``. If the default theme
is enabled by :c:macro:`LV_USE_THEME_DEFAULT` LVGL automatically initializes
@ -529,7 +530,7 @@ There is an example for it below.
Examples
********
.. include:: ../examples/styles/index.rst
.. include:: ../../../examples/styles/index.rst
.. _styles_api:

0
docs/overview/debugging/gdb_plugin.rst → docs/details/debugging/gdb_plugin.rst
View File

6
docs/overview/debugging/index.rst → docs/details/debugging/index.rst
View File

@ -1,8 +1,8 @@
.. _debugging:
==============
Debugging LVGL
==============
=========
Debugging
=========
.. toctree::
:maxdepth: 2

6
docs/overview/debugging/log.rst → docs/details/debugging/log.rst
View File

@ -20,9 +20,9 @@ To enable logging, set :c:macro:`LV_USE_LOG` in ``lv_conf.h`` and set
- :c:macro:`LV_LOG_LEVEL_USER`: Only user messages
- :c:macro:`LV_LOG_LEVEL_NONE`: Do not log anything
The events which have a higher level than the set log level will be
logged too. E.g. if you :c:macro:`LV_LOG_LEVEL_WARN`, errors will be also
logged.
The events which have a higher level than the set log level will be logged
as well. E.g. if you :c:macro:`LV_LOG_LEVEL_WARN`, errors will be also logged.
Printing logs
*************

0
docs/overview/debugging/profiler.rst → docs/details/debugging/profiler.rst
View File

2
docs/overview/debugging/vg_lite_tvg.rst → docs/details/debugging/vg_lite_tvg.rst
View File

@ -18,7 +18,7 @@ and simulate the same rendering images as the real hardware on the simulator.
Configuration
*************
1. Enable VG-Lite rendering backend, see `VG-Lite Rendering Backend <overview/renderers/vg_lite>`__.
1. Enable VG-Lite rendering backend, see :ref:`vglite`.
2. Enable ThorVG and turn on the configuration :c:macro:`LV_USE_THORVG_INTERNAL` or :c:macro:`LV_USE_THORVG_EXTERNAL`.
It is recommended to use the internal ThorVG library to ensure uniform rendering results.

17
docs/details/index.rst Normal file
View File

@ -0,0 +1,17 @@
.. _reference:
=========
Reference
=========
.. toctree::
:maxdepth: 2
base-widget/index
widgets/index
main-components/index
other-components/index
../examples
debugging/index
integration/index
libs/index

4
docs/integration/bindings/api_json.rst → docs/details/integration/bindings/api_json.rst
View File

@ -105,7 +105,7 @@ The different "json_types" are as follows:
- ``"name"``: The name of the function pointer.
- ``"type"``: This contains the return type information for the function pointer.
- ``"docstring"``: you should know what this is.
- ``"args"``: array of ``"arg"`` objects. This describes the fuction arguments/parameters.
- ``"args"``: array of ``"arg"`` Widgets. This describes the fuction arguments/parameters.
- ``"quals"``: array of qualifiers, IE "const"
@ -144,7 +144,7 @@ The different "json_types" are as follows:
type as the type for the members of this enumeration group. Check the
enumeration members type to get the correct type.
- ``"docstring"``: you should know what this is.
- ``"members"``: array of ``"enum_member"`` objects
- ``"members"``: array of ``"enum_member"`` Widgets
- ``"enum_member"``: Describes an enumeration item/member. Only found under

0
docs/integration/bindings/cpp.rst → docs/details/integration/bindings/cpp.rst
View File

0
docs/integration/bindings/index.rst → docs/details/integration/bindings/index.rst
View File

0
docs/integration/bindings/javascript.rst → docs/details/integration/bindings/javascript.rst
View File

4
docs/integration/bindings/micropython.rst → docs/details/integration/bindings/micropython.rst
View File

@ -59,7 +59,7 @@ MicroPython + LVGL could be used for:
- Fast prototyping GUI.
- Shortening the cycle of changing and fine-tuning the GUI.
- Modelling the GUI in a more abstract way by defining reusable composite objects, taking advantage of Python's language features
- Modelling the GUI in a more abstract way by defining reusable composite Widgets, taking advantage of Python's language features
such as Inheritance, Closures, List Comprehension, Generators, Exception Handling, Arbitrary Precision Integers and others.
- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system. This goes well with
`CircuitPython vision <https://learn.adafruit.com/welcome-to-circuitpython/what-is-circuitpython>`__.
@ -110,7 +110,7 @@ edit a python script and run it.
`Click here to experiment on the online simulator <https://sim.lvgl.io/>`__
Many `LVGL examples <https://docs.lvgl.io/master/examples.html>`__ are available also for MicroPython. Just click the link!
Many :ref:`LVGL examples <examples>` are available also for MicroPython. Just click the link!
PC Simulator

0
docs/integration/bindings/pikascript.rst → docs/details/integration/bindings/pikascript.rst
View File

2
docs/integration/building/cmake.rst → docs/details/integration/building/cmake.rst
View File

@ -1,7 +1,7 @@
.. _build_cmake:
=====
cmake
CMake
=====

0
docs/integration/building/index.rst → docs/details/integration/building/index.rst
View File

0
docs/integration/building/make.rst → docs/details/integration/building/make.rst
View File

0
docs/integration/chip/arm.rst → docs/details/integration/chip/arm.rst
View File

4
docs/integration/chip/espressif.rst → docs/details/integration/chip/espressif.rst
View File

@ -176,8 +176,8 @@ The process is described in details below, using ``SPIFFS`` as demonstration.
}
lv_obj_t * obj = lv_image_create(lv_screen_active());
lv_image_set_src(obj, "A:/spiffs/logo.bin");
lv_obj_center(obj);
lv_image_set_src(widget, "A:/spiffs/logo.bin");
lv_obj_center(widget);
}
- **Build and flash**

0
docs/integration/chip/index.rst → docs/details/integration/chip/index.rst
View File

2
docs/integration/chip/nxp.rst → docs/details/integration/chip/nxp.rst
View File

@ -5,7 +5,7 @@ NXP
NXP has integrated LVGL into the MCUXpresso SDK packages for several of our
microcontrollers as an optional software component, allowing easy evaluation and
migration into your product design. LVGL is a free and open-source embedded
graphic library with features that enable you need to create embedded GUIs with
graphic library with features that enable you to create embedded GUIs with
intuitive graphical elements, beautiful visual effects and a low memory
footprint. The complete graphic framework includes a variety of widgets for you
to use in the creation of your GUI, and supports more advanced functions such as

0
docs/integration/chip/renesas.rst → docs/details/integration/chip/renesas.rst
View File

34
docs/integration/chip/stm32.rst → docs/details/integration/chip/stm32.rst
View File

@ -19,9 +19,9 @@ Including LVGL in a Project
navigating to **C/C++ Build** -> **Settings** -> **Include paths**, and
ensuring that the LVGL directory is listed.
Now that the source files are included in your project, follow the
instructions for `Porting <https://docs.lvgl.io/master/porting/project.html>`_ your
project to create the ``lv_conf.h`` file, and initialise the display.
Now that the source files are included in your project, follow the instructions to
:ref:`add_lvgl_to_your_project` and to create the ``lv_conf.h`` file, and
initialise the display.
Bare Metal Example
@ -39,8 +39,8 @@ the *main.c* file. \* Create some frame buffer(s) as global variables:
/* Frame buffers
* Static or global buffer(s). The second buffer is optional
* TODO: Adjust color format and choose buffer size. DISPLAY_WIDTH * 10 is one suggestion. */
#define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /*will be 2 for RGB565 */
#define BUFF_SIZE (DISPLAY_WIDTH * 10 * BYTE_PER_PIXEL)
#define BYTES_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /* will be 2 for RGB565 */
#define BUFF_SIZE (DISPLAY_WIDTH * 10 * BYTES_PER_PIXEL)
static uint8_t buf_1[BUFF_SIZE];
static uint8_t buf_2[BUFF_SIZE];
@ -55,15 +55,15 @@ the *main.c* file. \* Create some frame buffer(s) as global variables:
//Initialise LVGL UI library
lv_init();
lv_display_t * disp = lv_display_create(WIDTH, HEIGHT); /*Basic initialization with horizontal and vertical resolution in pixels*/
lv_display_set_flush_cb(disp, my_flush_cb); /*Set a flush callback to draw to the display*/
lv_display_set_buffers(disp, buf_1, buf_2, sizeof(buf_1), LV_DISPLAY_RENDER_MODE_PARTIAL); /*Set an initialized buffer*/
lv_display_t * disp = lv_display_create(WIDTH, HEIGHT); /* Basic initialization with horizontal and vertical resolution in pixels */
lv_display_set_flush_cb(disp, my_flush_cb); /* Set a flush callback to draw to the display */
lv_display_set_buffers(disp, buf_1, buf_2, sizeof(buf_1), LV_DISPLAY_RENDER_MODE_PARTIAL); /* Set an initialized buffer */
- Create some dummy objects to test the output:
- Create some dummy Widgets to test the output:
.. code-block:: c
/* Change the active screen's background color */
/* Change Active Screen's background color */
lv_obj_set_style_bg_color(lv_screen_active(), lv_color_hex(0x003a57), LV_PART_MAIN);
lv_obj_set_style_text_color(lv_screen_active(), lv_color_hex(0xffffff), LV_PART_MAIN);
@ -138,7 +138,7 @@ the *main.c* file. \* Create some frame buffer(s) as global variables:
HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_SET);
/* IMPORTANT!!!
* Inform the graphics library that you are ready with the flushing*/
* Inform the graphics library that you are ready with the flushing */
lv_display_flush_ready(disp);
}
@ -148,17 +148,17 @@ FreeRTOS Example
A minimal example using STM32CubeIDE, HAL, and CMSISv1 (FreeRTOS).
*Note that we have not used Mutexes in this example, however LVGL is* **NOT**
*thread safe and so Mutexes should be used*. See: :ref:`os_interrupt`
*thread safe and so Mutexes should be used*. See: :ref:`threading`
\* ``#include "lvgl.h"`` \* Create your frame buffer(s) as global variables:
.. code-block:: c
/* Frame buffers
* Static or global buffer(s). The second buffer is optional */
#define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /* will be 2 for RGB565 */
#define BYTES_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /* will be 2 for RGB565 */
/* TODO: Declare your own BUFF_SIZE appropriate to your system. */
static lv_color_t buf_1[BUFF_SIZE];
#define BUFF_SIZE (DISPLAY_WIDTH * 10 * BYTE_PER_PIXEL)
#define BUFF_SIZE (DISPLAY_WIDTH * 10 * BYTES_PER_PIXEL)
static uint8_t buf_1[BUFF_SIZE];
static lv_color_t buf_2[BUFF_SIZE];
@ -178,11 +178,11 @@ A minimal example using STM32CubeIDE, HAL, and CMSISv1 (FreeRTOS).
/* Register the touch controller with LVGL - Not included here for brevity. */
- Create some dummy objects to test the output:
- Create some dummy Widgets to test the output:
.. code-block:: c
/* Change the active screen's background color */
/* Change Active Screen's background color */
lv_obj_set_style_bg_color(lv_screen_active(), lv_color_hex(0x003a57), LV_PART_MAIN);
lv_obj_set_style_text_color(lv_screen_active(), lv_color_hex(0xffffff), LV_PART_MAIN);
@ -266,7 +266,7 @@ A minimal example using STM32CubeIDE, HAL, and CMSISv1 (FreeRTOS).
HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_SET);
/* IMPORTANT!!!
* Inform the graphics library that you are ready with the flushing*/
* Inform the graphics library that you are ready with the flushing */
lv_display_flush_ready(display);
}

14
docs/integration/driver/X11.rst → docs/details/integration/driver/X11.rst
View File

@ -32,26 +32,26 @@ Configure X11 driver
- Direct Exit
.. code-block:: c
#define LV_X11_DIRECT_EXIT 1 /*preferred default - ends the application automatically if last window has been closed*/
#define LV_X11_DIRECT_EXIT 1 /* preferred default - ends the application automatically if last window has been closed */
// or
#define LV_X11_DIRECT_EXIT 0 /*application is responsible for ending the application (e.g. by own LV_EVENT_DELETE handler*/
#define LV_X11_DIRECT_EXIT 0 /* application is responsible for ending the application (e.g. by own LV_EVENT_DELETE handler */
- Double buffering
.. code-block:: c
#define LV_X11_DOUBLE_BUFFER 1 /*preferred default*/
#define LV_X11_DOUBLE_BUFFER 1 /* preferred default */
// or
#define LV_X11_DOUBLE_BUFFER 0 /*not recommended*/
#define LV_X11_DOUBLE_BUFFER 0 /* not recommended */
- Render mode
.. code-block:: c
#define LV_X11_RENDER_MODE_PARTIAL 1 /*LV_DISPLAY_RENDER_MODE_PARTIAL, preferred default*/
#define LV_X11_RENDER_MODE_PARTIAL 1 /* LV_DISPLAY_RENDER_MODE_PARTIAL, preferred default */
// or
#define LV_X11_RENDER_MODE_DIRECT 1 /*LV_DISPLAY_RENDER_MODE_DIRECT, not recommended for X11 driver*/
#define LV_X11_RENDER_MODE_DIRECT 1 /* LV_DISPLAY_RENDER_MODE_DIRECT, not recommended for X11 driver */
// or
#define LV_X11_RENDER_MODE_DULL 1 /*LV_DISPLAY_RENDER_MODE_FULL, not recommended for X11 driver*/
#define LV_X11_RENDER_MODE_DULL 1 /* LV_DISPLAY_RENDER_MODE_FULL, not recommended for X11 driver */
Usage
-----

0
docs/integration/driver/display/fbdev.rst → docs/details/integration/driver/display/fbdev.rst
View File

0
docs/integration/driver/display/gen_mipi.rst → docs/details/integration/driver/display/gen_mipi.rst
View File

0
docs/integration/driver/display/ili9341.rst → docs/details/integration/driver/display/ili9341.rst
View File

0
docs/integration/driver/display/index.rst → docs/details/integration/driver/display/index.rst
View File

40
docs/integration/driver/display/lcd_stm32_guide.rst → docs/details/integration/driver/display/lcd_stm32_guide.rst
View File

@ -11,9 +11,9 @@ This guide is intended to be a step-by-step instruction of how to configure the
.. tip::
ST Micro provide their own TFT-LCD drivers in their X-CUBE-DISPLAY Software Extension Package. While these drivers can be used with LVGL as well, the LVGL LCD drivers do not depend on this package.
The LVGL LCD drivers are meant as an alternative, simple to use API to implement LCD support for your LVGL-based project on any platform. Moreover, even in the initial release we support more LCD controllers than X-CUBE-DISPLAY currently provides, and we plan to add support for even more LCD controllers in the future.
Please note however, that – unlike X-CUBE-DISPLAY – the LVGL LCD drivers do not implement the communication part, whether SPI, parallel i8080 bus or other. It is the user's responsibility to implement – and optimize – these on their chosen platform. LVGL will only provide examples for the most popular platforms.
By following the steps you will have a fully functional program, which can be used as the foundation of your own LVGL-based project. If you are in a hurry and not interested in the details, you can find the final project `here <https://github.com/lvgl/lv_port_lcd_stm32>`__. You will only need to configure LVGL to use the driver corresponding to your hardware (if it is other than the ST7789), and implement the function ``ui_init()`` to create your widgets.
@ -25,7 +25,7 @@ By following the steps you will have a fully functional program, which can be us
.. note::
Although the example uses FreeRTOS, this is not a strict requirement with the LVGL LCD display drivers.
You can find the source code snippets of this guide in the `lv_port_lcd_stm32_template.c <https://github.com/lvgl/lvgl/examples/porting/lv_port_lcd_stm32_template.c>`__ example.
Hardware configuration
@ -79,30 +79,30 @@ Step-by-step instructions
#. Open the Project Manager tab, and select Advanced Settings. On the right hand side there is a Register Callback window. Select SPI and set it to ENABLE.
#. We are ready with the hardware configuration. Save the configuration and let STM32Cube generate the source.
#. In the project tree clone the LVGL repository into the Middlewares/Third_Party folder (this tutorial uses the release/v9.0 branch of LVGL):
.. code-block:: dosbatch
git clone https://github.com/lvgl/lvgl.git -b release/v9.0
#. Cloning should create an 'lvgl' subfolder inside the 'Third_Party' folder. From the 'lvgl' folder copy 'lv_conf_template.h' into the 'Middlewares' folder, and rename it to 'lv_conf.h'. Refresh the project tree.
#. Open 'lv_conf.h', and in line 15 change ``#if 0`` to ``#if 1``.
#. Search for the string ``LV_USE_ST7735``, and enable the appropriate LCD driver by setting its value to 1. This example uses the ST7789 driver:
.. code-block:: c
#define LV_USE_ST7789 1
#. Right click the folder 'Middlewares/Third_Party/lvgl/tests', select Resource Configurations/Exclude from Build..., check both Debug and Release, then press OK.
#. Right click the project name and select "Properties". In the C/C++ Build/Settings panel select MCU GCC Compiler/Include paths. In the Configuration dropdown select [ All configurations ]. Add the following Include path:
.. code-block:: c
../Middlewares/Third_Party/lvgl
#. Open Core/Src/stm32xxx_it.c (the file name depends on the processor variation). Add 'lv_tick.h' to the Private includes section:
.. code-block:: c
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
#include "./src/tick/lv_tick.h"
@ -146,7 +146,7 @@ Step-by-step instructions
#. Add the following lines to the Private variables:
.. code-block:: c
osThreadId LvglTaskHandle;
lv_display_t *lcd_disp;
volatile int lcd_bus_busy = 0;
@ -251,7 +251,7 @@ Step-by-step instructions
#. Add the LVGL_Task() function. Replace the ``lv_st7789_create()`` call with the appropriate driver. You can change the default orientation by adjusting the parameter of ``lv_display_set_rotation()``. You will also need to create the display buffers here. This example uses a double buffering scheme with 1/10th size partial buffers. In most cases this is a good compromise between the required memory size and performance, but you are free to experiment with other settings.
.. code-block:: c
void LVGL_Task(void const *argument)
{
/* Initialize LVGL */
@ -310,11 +310,11 @@ Step-by-step instructions
/* create label */
obj = lv_label_create(scr);
lv_obj_set_align(obj, LV_ALIGN_CENTER);
lv_obj_set_height(obj, LV_SIZE_CONTENT);
lv_obj_set_width(obj, LV_SIZE_CONTENT);
lv_obj_set_style_text_font(obj, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(obj, lv_color_black(), 0);
lv_label_set_text(obj, "Hello World!");
lv_obj_set_align(widget, LV_ALIGN_CENTER);
lv_obj_set_height(widget, LV_SIZE_CONTENT);
lv_obj_set_width(widget, LV_SIZE_CONTENT);
lv_obj_set_style_text_font(widget, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(widget, lv_color_black(), 0);
lv_label_set_text(widget, "Hello World!");
}

0
docs/integration/driver/display/renesas_glcdc.rst → docs/details/integration/driver/display/renesas_glcdc.rst
View File

0
docs/integration/driver/display/st7735.rst → docs/details/integration/driver/display/st7735.rst
View File

0
docs/integration/driver/display/st7789.rst → docs/details/integration/driver/display/st7789.rst
View File

0
docs/integration/driver/display/st7796.rst → docs/details/integration/driver/display/st7796.rst
View File

12
docs/integration/driver/display/st_ltdc.rst → docs/details/integration/driver/display/st_ltdc.rst
View File

@ -92,11 +92,11 @@ option.
It must not be enabled at the same time as :c:macro:`LV_USE_DRAW_DMA2D`.
See the :ref:`DMA2D support <dma2d>`.
Further Reading
***************
You may be interested in enabling the :ref:`Nema GFX renderer <stm32_nema_gfx>`
if your STM32 has a GPU which is supported by Nema GFX.
.. admonition:: Further Reading
`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
is a way to quick way to get started with LTDC on LVGL.
You may be interested in enabling the :ref:`Nema GFX renderer <stm32_nema_gfx>`
if your STM32 has a GPU which is supported by Nema GFX.
`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
is a way to quick way to get started with LTDC on LVGL.

2
docs/integration/driver/index.rst → docs/details/integration/driver/index.rst
View File

@ -1,3 +1,5 @@
.. _drivers:
=======
Drivers
=======

0
docs/integration/driver/libinput.rst → docs/details/integration/driver/libinput.rst
View File

14
docs/integration/driver/opengles.rst → docs/details/integration/driver/opengles.rst
View File

@ -1,3 +1,5 @@
.. _opengl_es_driver:
===============================
OpenGL ES Display/Inputs Driver
===============================
@ -63,7 +65,7 @@ Basic Usage
lv_image_set_src(cursor_obj, &mouse_cursor_icon);
lv_indev_set_cursor(mouse, cursor_obj);
/* create objects on the screen */
/* create Widgets on the screen */
lv_demo_widgets();
while (1)
@ -121,7 +123,7 @@ used to add content to a texture and the driver will draw the texture in the win
lv_image_set_src(cursor_obj, &mouse_cursor_icon);
lv_indev_set_cursor(main_texture_mouse, cursor_obj);
/* create objects on the screen of the main texture */
/* create Widgets on the screen of the main texture */
lv_demo_widgets();
/**********************
@ -137,7 +139,7 @@ used to add content to a texture and the driver will draw the texture in the win
unsigned int sub_texture_id = lv_opengles_texture_get_texture_id(sub_texture);
lv_glfw_texture_t * window_sub_texture = lv_glfw_window_add_texture(window, sub_texture_id, sub_texture_w, sub_texture_h);
/* create objects on the screen of the sub texture */
/* create Widgets on the screen of the sub texture */
lv_display_set_default(sub_texture);
lv_example_keyboard_2();
lv_display_set_default(main_texture);
@ -210,9 +212,13 @@ Known Limitations
~~~~~~~~~~~~~~~~~
- Performance will be the same or slightly worse if the drawn areas are never found in the cache
due to objects with continuously varying colors or shapes. One example is a label whose color
due to Widgets with continuously varying colors or shapes. One example is a label whose color
is set to a random value every frame, as in the "Multiple labels" scene of the benchmark demo.
- Layers with transparent pixels and an overall layer transparency will not blend correctly.
The effect can be observed in the "Containers with opa_layer" scene of the benchmark demo
in the border corners.
- Layers with rotation are not currently supported. Images with rotation are fine.
.. Comment: The above blank line is necessary for Sphinx to not complain,
since it looks for the blank line after a bullet list.

0
docs/integration/driver/touchpad/evdev.rst → docs/details/integration/driver/touchpad/evdev.rst
View File

0
docs/integration/driver/touchpad/ft6x36.rst → docs/details/integration/driver/touchpad/ft6x36.rst
View File

0
docs/integration/driver/touchpad/index.rst → docs/details/integration/driver/touchpad/index.rst
View File

2
docs/integration/driver/wayland.rst → docs/details/integration/driver/wayland.rst
View File

@ -1,3 +1,5 @@
.. _wayland_driver:
=============================
Wayland Display/Inputs driver
=============================

0
docs/integration/driver/windows.rst → docs/details/integration/driver/windows.rst
View File

6
docs/integration/framework/arduino.rst → docs/details/integration/framework/arduino.rst
View File

@ -5,7 +5,7 @@ Arduino
The `LVGL library <https://github.com/lvgl/lvgl>`__ is directly available as Arduino libraries.
Note that you need to choose a board powerful enough to run LVGL and
your GUI. See the `requirements of LVGL <https://docs.lvgl.io/master/intro/index.html#requirements>`__.
your GUI. See the :ref:`requirements of LVGL <requirements>`.
For example ESP32 is a good candidate to create UI's with LVGL.
@ -87,8 +87,8 @@ section ``log settings``:
.. code-block:: c
/*Log settings*/
#define USE_LV_LOG 1 /*Enable/disable the log module*/
/* Log settings */
#define USE_LV_LOG 1 /* Enable/disable the log module */
#if LV_USE_LOG
/* How important log should be added:
* LV_LOG_LEVEL_TRACE A lot of logs to give detailed information

0
docs/integration/framework/index.rst → docs/details/integration/framework/index.rst
View File

0
docs/integration/framework/platformio.rst → docs/details/integration/framework/platformio.rst
View File

2
docs/integration/framework/tasmota-berry.rst → docs/details/integration/framework/tasmota-berry.rst
View File

@ -62,7 +62,7 @@ Tasmota + Berry + LVGL could be used for:
- Fast prototyping GUI.
- Shortening the cycle of changing and fine-tuning the GUI.
- Modelling the GUI in a more abstract way by defining reusable composite objects, taking
- Modelling the GUI in a more abstract way by defining reusable composite Widgets, taking
advantage of Berry's language features such as Inheritance, Closures, Exception Handling…
- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system.

0
docs/integration/ide/index.rst → docs/details/integration/ide/index.rst
View File

0
docs/integration/ide/mdk.rst → docs/details/integration/ide/mdk.rst
View File

6
docs/integration/ide/pc-simulator.rst → docs/details/integration/ide/pc-simulator.rst
View File

@ -25,11 +25,11 @@ Select an IDE
The simulator is ported to various IDEs (Integrated Development Environments).
Choose your favorite IDE, read its README on GitHub, download the project, and load it to the IDE.
- `Eclipse with SDL driver <https://github.com/lvgl/lv_sim_eclipse_sdl>`__: Recommended on Linux and Mac, supports CMake too
- `Eclipse with SDL driver <https://github.com/lvgl/lv_sim_eclipse_sdl>`__: Recommended on Linux and Mac, supports CMake as well
- `VisualStudio <https://github.com/lvgl/lv_port_pc_visual_studio>`__: Recommended on Windows
- `VSCode with SDL driver <https://github.com/lvgl/lv_port_pc_vscode>`__: Recommended on Linux (SDL) and Mac (SDL)
- `CodeBlocks <https://github.com/lvgl/lv_sim_codeblocks_win>`__: Recommended on Windows
- `PlatformIO with SDL driver <https://github.com/lvgl/lv_platformio>`__: Recommended on Linux and Mac but has an STM32 environment too
- `PlatformIO with SDL driver <https://github.com/lvgl/lv_platformio>`__: Recommended on Linux and Mac but has an STM32 environment as well
- `Generic Linux <https://github.com/lvgl/lv_port_linux>`__: CMake based project where you can easily switch between fbdev, DRM, and SDL.
- `MDK with FastModel <https://github.com/lvgl/lv_port_an547_cm55_sim>`__: For Windows
@ -40,7 +40,7 @@ External project not maintained by the LVGL organization:
Built-in drivers
----------------
LVGL comes with several `built-in drivers <https://docs.lvgl.io/master/integration/driver/index.html>`__.
LVGL comes with several :ref:`built-in drivers <drivers>`.
Even if a simulator project comes with e.g. SDL, you can easily replace it by enabling
another driver in ``lv_conf.h`` and calling its ``create`` function.

3
docs/integration/index.rst → docs/details/integration/index.rst
View File

@ -1,3 +1,5 @@
.. _integration_index:
=======================
Integration and Drivers
=======================
@ -9,6 +11,7 @@ Integration and Drivers
building/index
chip/index
driver/index
renderers/index
framework/index
ide/index
os/index

0
docs/integration/os/freertos.rst → docs/details/integration/os/freertos.rst
View File

0
docs/integration/os/index.rst → docs/details/integration/os/index.rst
View File

2
docs/integration/os/mqx.rst → docs/details/integration/os/mqx.rst
View File

@ -1,3 +1,5 @@
.. _mqx:
========
MQX RTOS
========

4
docs/integration/os/nuttx.rst → docs/details/integration/os/nuttx.rst
View File

@ -152,3 +152,7 @@ Where can I find more information?
LPCXpresso54628 <https://acassis.wordpress.com/2018/07/19/running-nuttx-on-lpcxpresso54628-om13098/>`__
- NuttX mailing list: `Apache NuttX Mailing
List <http://nuttx.incubator.apache.org/community/>`__
.. Comment: The above blank line is necessary for Sphinx to not complain,
since it looks for the blank line after a bullet list.

0
docs/integration/os/px5.rst → docs/details/integration/os/px5.rst
View File

16
docs/integration/os/qnx.rst → docs/details/integration/os/qnx.rst
View File

@ -1,9 +1,11 @@
.. _qnx:
===
QNX
===
What is QNX?
------------
************
QNX is a commercial operating system first released in 1980. The operating
system is based on a micro-kernel design, with the file system(s), network
@ -13,7 +15,7 @@ address space.
See www.qnx.com for more details.
Highlight of QNX
~~~~~~~~~~~~~~~~
----------------
- 64-bit only, runs on x86_64 and ARMv8
- Requires an MMU as the design mandates separation among processes
@ -24,14 +26,14 @@ Highlight of QNX
- Safety certification to various automotive, industrial and medical standards
How to run LVGL on QNX?
-----------------------
***********************
There are two ways to use LVGL in your QNX project. The first is similar to how
LVGL is used on other systems. The second is to build LVGL as either a shared or
a static library.
Include LVGL in Your Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
Follow the generic instructions for getting started with LVGL. After copying
`lv_conf_template.h` to `lv_conf.h` make the following changes to the latter:
@ -55,7 +57,7 @@ Follow the generic instructions for getting started with LVGL. After copying
#define LV_QNX_BUF_COUNT 2
Build LVGL as a Library
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
**Note that this method is an alternative to including LVGL in your project. If
you choose to build a library then you do not need to follow the instructions in
@ -88,7 +90,7 @@ Before building the library, you may wish to edit
double-buffering.
Writing a LVGL Application
~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------
To create a LVGL application for QNX, follow these steps in your code:
@ -134,7 +136,7 @@ The following code shows how to create a "Hello World" application:
}
Build the Application
~~~~~~~~~~~~~~~~~~~~~
---------------------
Building the application consists of compiling the source with the LVGL headers,
and then linking against the library. This can be done in many ways, using

0
docs/integration/os/rt-thread.rst → docs/details/integration/os/rt-thread.rst
View File

37
docs/integration/os/yocto/core_components.rst → docs/details/integration/os/yocto/core_components.rst
View File

@ -1,8 +1,11 @@
Yocto Project Core Components
#############################
.. _yocto_project_core_components:
The BitBake task executor together with various types of configuration files
form the OpenEmbedded-Core (OE-Core). This section overviews these components
=============================
Yocto Project Core Components
=============================
The BitBake task executor together with various types of configuration files
form the OpenEmbedded-Core (OE-Core). This section overviews these components
by describing their use and how they interact.
BitBake handles the parsing and execution of the data files. The data
@ -18,20 +21,20 @@ itself is of various types:
everything together.
BitBake knows how to combine multiple data sources together and refers
to each data source as a layer.
to each data source as a layer.
Here are some brief details on these core components.
Here are some brief details on these core components.
.. _bitbake_section:
BitBake
*******
BitBake is the tool at the heart of the OpenEmbedded Build System and is
responsible for parsing the Metadata, generating a list of tasks from it, and
BitBake is the tool at the heart of the OpenEmbedded Build System and is
responsible for parsing the Metadata, generating a list of tasks from it, and
then executing those tasks.
This section briefly introduces BitBake. If you want more information on
This section briefly introduces BitBake. If you want more information on
BitBake, see the `BitBake User Manual <https://docs.yoctoproject.org/bitbake/2.
8/index.html>`_.
@ -54,7 +57,7 @@ Several different versions of ``matchbox-desktop`` might exist. BitBake chooses
the one selected by the distribution configuration. You can get more details
about how BitBake chooses between different target versions and providers in the
"`Preferences <https://docs.yoctoproject.org/bitbake/2.8/bitbake-user-manual/
bitbake-user-manual-execution.html#preferences>`_" section of the BitBake User
bitbake-user-manual-execution.html#preferences>`_" section of the BitBake User
Manual.
BitBake also tries to execute any dependent tasks first. So for example,
@ -133,14 +136,14 @@ several pieces of hardware.
There are many layers working in the Yocto Project development environment. The
`Yocto Project Compatible Layer Index <https://www.yoctoproject.org/development/
yocto-project-compatible-layers/>`_ and `OpenEmbedded Layer Index <https://
layers.openembedded.org/layerindex/branch/master/layers/>`_ both contain layers
layers.openembedded.org/layerindex/branch/master/layers/>`_ both contain layers
from
which you can use or leverage.
By convention, layers in the Yocto Project follow a specific form. Conforming
to a known structure allows BitBake to make assumptions during builds on where
to find types of metadata. You can find procedures and learn about tools (i.e.
``bitbake-layers``) for creating layers suitable for the Yocto Project in the
By convention, layers in the Yocto Project follow a specific form. Conforming
to a known structure allows BitBake to make assumptions during builds on where
to find types of metadata. You can find procedures and learn about tools (i.e.
``bitbake-layers``) for creating layers suitable for the Yocto Project in the
"`understanding and creating layers <https://docs.yoctoproject.org/dev-manual/
layers.html#understanding-and-creating-layers>`_" section of the
Yocto Project Development Tasks Manual.
layers.html#understanding-and-creating-layers>`_" section of the
Yocto Project Development Tasks Manual.

23
docs/integration/os/yocto/index.rst → docs/details/integration/os/yocto/index.rst
View File

@ -1,16 +1,19 @@
Yocto
#####
.. _yocto:
The Yocto Project (YP) is an open source collaboration project that helps
developers create custom Linux-based systems regardless of the hardware
=====
Yocto
=====
The Yocto Project (YP) is an open source collaboration project that helps
developers create custom Linux-based systems regardless of the hardware
architecture.
The project provides a flexible set of tools and a space where embedded
developers worldwide can share technologies, software stacks, configurations,
and best practices that can be used to create tailored Linux images for
The project provides a flexible set of tools and a space where embedded
developers worldwide can share technologies, software stacks, configurations,
and best practices that can be used to create tailored Linux images for
embedded and IOT devices, or anywhere a customized Linux OS is needed.
This section objective is to ease to process of understanding the basic
This section objective is to ease to process of understanding the basic
concepts of Yocto and to help beginners to start with Yocto.
@ -21,5 +24,5 @@ concepts of Yocto and to help beginners to start with Yocto.
core_components
lvgl_recipe
terms_and_variables

435
docs/integration/os/yocto/lvgl_recipe.rst → docs/details/integration/os/yocto/lvgl_recipe.rst
View File

@ -1,27 +1,30 @@
LVGL in Yocto
#############
.. _yocto_lvgl_recipe:
This chapter serves as a guide to help you create a recipe for an application
using LVGL. While the process will be demonstrated for the Raspberry Pi 3
=============
LVGL in Yocto
=============
This chapter serves as a guide to help you create a recipe for an application
using LVGL. While the process will be demonstrated for the Raspberry Pi 3
(64-bit), it can be applied to any board in a similar way.
Build Host Packages
Build Host Packages
*******************
You must install essential host packages on your build host. The following
You must install essential host packages on your build host. The following
command installs the host packages based on an Ubuntu distribution
.. code-block::
sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential \
chrpath socat cpio python3 python3-pip python3-pexpect xz-utils \
debianutils iputils-ping python3-git python3-jinja2 python3-subunit zstd \
debianutils iputils-ping python3-git python3-jinja2 python3-subunit zstd \
liblz4-tool file locales libacl1
.. note::
For host package requirements on all supported Linux distributions, see the
For host package requirements on all supported Linux distributions, see the
`Required Packages for the Build Host <https://docs.yoctoproject.org/
ref-manual/system-requirements.html#required-packages-for-the-build-host>`_
ref-manual/system-requirements.html#required-packages-for-the-build-host>`_
section in the Yocto Project Reference Manual.
@ -35,7 +38,7 @@ After this section the folder tree will be like this
lvgl_yocto_guide/
├── build/
│ ├── cache/
│ ├── conf/
│ ├── conf/
│ ├── downloads/
│ └── ...
└── sources/
@ -53,32 +56,32 @@ Clone Poky, meta-openembedded and meta-raspberrypi in the sources
.. code-block::
cd lvgl_yocto_guide/sources
cd lvgl_yocto_guide/sources
git clone --branch scarthgap https://git.yoctoproject.org/poky.git
git clone --branch scarthgap https://git.openembedded.org/meta-openembedded
git clone --branch scarthgap https://git.openembedded.org/meta-openembedded
git clone --branch scarthgap git://git.yoctoproject.org/meta-raspberrypi
Build a base image
******************
To understand better what is going on, let's build the image like it is
To understand better what is going on, let's build the image like it is
prepared for us
.. code-block:: none
cd ../ # go back to the root folder
source sources/poky/oe-init-build-env
cd ../ # go back to the root folder
source sources/poky/oe-init-build-env
Now you should have a folder named ``build`` next to ``sources``. The last
command
also sets the current directory to the build directory.
Now you should have a folder named ``build`` next to ``sources``. The last
command
also sets the current directory to the build directory.
In the build directory, there is a ``conf`` folder with some files in it
.. code-block:: none
└── build/
└── conf/
└── conf/
├── bblayers.conf
├── conf-notes.txt
├── conf-summary.txt
@ -87,11 +90,11 @@ In the build directory, there is a ``conf`` folder with some files in it
The important files for us are ``local.conf`` and ``bblayers.conf``
To add layers to the project there are 2 options:
To add layers to the project there are 2 options:
**Bitbake commands (Option 1)**
You need to be in the same terminal you did the ``source`` command. Add the
You need to be in the same terminal you did the ``source`` command. Add the
layers with the Bitbake command like this
.. code-block::
@ -104,7 +107,7 @@ layers with the Bitbake command like this
Open ``conf/bblayers.conf`` file and add manually the paths:
.. code-block:: bash
# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"
@ -123,12 +126,12 @@ Open ``conf/bblayers.conf`` file and add manually the paths:
${TOPDIR}/../sources/meta-openembedded/meta-python \
"
To ensure the layers were added as expected, run the Bitbake command to show
To ensure the layers were added as expected, run the Bitbake command to show
all the layers::
bitbake-layers show-layers
The following layers should be listed:
The following layers should be listed:
- core
- yocto
- yoctobsp
@ -147,14 +150,14 @@ The available machine configurations for Raspberrypi can be listed like this
ls ../sources/meta-raspberrypi/conf/machine/*.conf
To build an image for Raspberrypi3 64 bits, modify the file ``local.conf`` file
To build an image for Raspberrypi3 64 bits, modify the file ``local.conf`` file
replacing the ``MACHINE ??=`` default value like this
.. code-block:: bash
MACHINE ??= "raspberrypi3-64"
To build the image we will target, it is also needed to add this to the file:
To build the image we will target, it is also needed to add this to the file:
.. code-block:: bash
@ -162,105 +165,105 @@ To build the image we will target, it is also needed to add this to the file:
.. note::
You can find more information about this variable `here <https://meta-raspberrypi.readthedocs.io/en/latest/ipcompliance.html#linux-firmware-rpidistro>`_.
You can find more information about this variable `here <https://meta-raspberrypi.readthedocs.io/en/latest/ipcompliance.html#linux-firmware-rpidistro>`_.
Everything is setup, time to build the image::
bitbake core-image-base
Overview of the build
Overview of the build
=====================
Let's go through the build folders to understand what happened.
Downloads
Downloads
---------
The folder location can be changed with the ``DL_DIR`` variable.
The Downloads folder is a fundamental part of the Yocto build environment,
serving as a local cache for all external sources and dependencies. This
caching mechanism is essential for efficient builds, ensuring that repeated
The Downloads folder is a fundamental part of the Yocto build environment,
serving as a local cache for all external sources and dependencies. This
caching mechanism is essential for efficient builds, ensuring that repeated
builds do not waste time downloading the same files again.
tmp/deploy
tmp/deploy
----------
This folder contains the final output artifacts that are ready for deployment.
These artifacts include kernel images, root filesystems, packages, SDKs,
bootloader files, and other components that are generated during the Yocto
This folder contains the final output artifacts that are ready for deployment.
These artifacts include kernel images, root filesystems, packages, SDKs,
bootloader files, and other components that are generated during the Yocto
build process.
There are some key folders:
- **images**: it contains the images that can be flashed or deployed to
There are some key folders:
- **images**: it contains the images that can be flashed or deployed to
the target device. Files like the Linux kernel, root filesystem (e.g., .
ext4, .tar.gz, .squashfs), bootloaders (e.g., U-Boot), and other
bootable images for the device are found here. t’s organized by the
ext4, .tar.gz, .squashfs), bootloaders (e.g., U-Boot), and other
bootable images for the device are found here. t’s organized by the
machine (or target board) for which the image was built.
- **rmp/deb/ipk**: These folders contain the individual software packages
generated during the build, in the specified package format (RPM, DEB,
or IPK). These packages are typically created when you’re building your
Yocto project with package management support enabled. These can later
- **rmp/deb/ipk**: These folders contain the individual software packages
generated during the build, in the specified package format (RPM, DEB,
or IPK). These packages are typically created when you’re building your
Yocto project with package management support enabled. These can later
be installed on the target device using package management tools
- **sdk**: This subdirectory contains Software Development Kits (SDKs)
that you can use to cross-compile applications for your target system.
The SDKs are generated when you use the ``bitbake -c populate_sdk``
- **sdk**: This subdirectory contains Software Development Kits (SDKs)
that you can use to cross-compile applications for your target system.
The SDKs are generated when you use the ``bitbake -c populate_sdk``
command.
tmp/sysroots-components
-----------------------
This folder is a modular approach introduced in Yocto to handle sysroots. It
divides the sysroot into individual components, which can be thought of as the
This folder is a modular approach introduced in Yocto to handle sysroots. It
divides the sysroot into individual components, which can be thought of as the
building blocks or packages that make up the entire sysroot environment.
Each component corresponds to a specific package or dependency that is staged
into the sysroot. This approach allows for more efficient reuse of sysroots
across multiple packages or builds, and it helps with dependency tracking and
Each component corresponds to a specific package or dependency that is staged
into the sysroot. This approach allows for more efficient reuse of sysroots
across multiple packages or builds, and it helps with dependency tracking and
management during the build process.
The sysroot-components directory helps optimize the build process because if
one package changes, Yocto only needs to update the corresponding component
The sysroot-components directory helps optimize the build process because if
one package changes, Yocto only needs to update the corresponding component
rather than rebuilding or copying the entire sysroot.
If you followed the previous steps, here are the folders you will find:
If you followed the previous steps, here are the folders you will find:
- ``all``: Architecture-independent files.
- ``cortexa53``: Files for the Cortex-A53 (ARMv8-A) architecture.
- ``manifests``: Track files installed in the sysroot by package.
- ``raspberrypi3_64``: Files specific to the Raspberry Pi 3 (64-bit).
- ``x86_64``: Files for the x86_64 (PC) architecture, typically for
- ``x86_64``: Files for the x86_64 (PC) architecture, typically for
cross-compilation tools.
- ``x86_64-nativesdk``: Files related to the SDK for cross-compilation on
- ``x86_64-nativesdk``: Files related to the SDK for cross-compilation on
an x86_64 host.
Each folder corresponds to components relevant to the specific architecture,
and they collectively form the complete environment needed to compile and run
Each folder corresponds to components relevant to the specific architecture,
and they collectively form the complete environment needed to compile and run
software for the target and host systems.
tmp/sysroots-uninative
----------------------
The sysroots-uninative directory in Yocto is used to support the "uninative"
feature, which allows for more reproducible builds by ensuring that the build
environment remains consistent across different host systems. It essentially
provides a way to use the same native build tools across different Linux
The sysroots-uninative directory in Yocto is used to support the "uninative"
feature, which allows for more reproducible builds by ensuring that the build
environment remains consistent across different host systems. It essentially
provides a way to use the same native build tools across different Linux
distributions.
tmp/work
--------
The ``work`` folder in Yocto is a key directory in the ``tmp`` folder that
holds all the temporary build artifacts for each package during the build
process. It is where the actual building and compiling of individual packages
or recipes takes place. Each package (or "recipe") that BitBake processes
The ``work`` folder in Yocto is a key directory in the ``tmp`` folder that
holds all the temporary build artifacts for each package during the build
process. It is where the actual building and compiling of individual packages
or recipes takes place. Each package (or "recipe") that BitBake processes
generates temporary files and directories inside this ``work`` folder.
The ``work`` folder is typically structured by machine architecture and
The ``work`` folder is typically structured by machine architecture and
package. Here's how it generally works:
.. code-block:: none
.. code-block:: none
work/
└── <architecture>/
@ -271,8 +274,8 @@ package. Here's how it generally works:
├── sysroot-destdir/
└── image/
This folder is very important and helps a lot during debug phases. The ``temp``
subfolder contains important logs that can help you diagnose build issues. This
This folder is very important and helps a lot during debug phases. The ``temp``
subfolder contains important logs that can help you diagnose build issues. This
is where you'll look when a build fails to figure out what went wrong.
@ -284,37 +287,37 @@ Find more information about recipes in :ref:`recipes_section` section.
There is a recipe in ``meta-openembedded`` since ``honister``.
.. list-table:: lvgl recipe version
:widths: 200 100
:widths: 200 100
:header-rows: 1
* - Branch
- Recipe
* - scarthgap (Yocto Project 5.0)
- lvgl 9.1.0
* - nanbield (Yocto Project 4.3)
* - nanbield (Yocto Project 4.3)
- lvgl 8.3.10
* - mickledore (Yocto Project 4.2)
- lvgl 8.1.0
* - langdale (Yocto Project 4.1)
* - mickledore (Yocto Project 4.2)
- lvgl 8.1.0
* - langdale (Yocto Project 4.1)
- lvgl 8.1.0
* - kirkstone (Yocto Project 4.0)
* - langdale (Yocto Project 4.1)
- lvgl 8.1.0
* - kirkstone (Yocto Project 4.0)
- lvgl 8.0.3
In this guide, we are on the ``scarthgap`` branch, so we are using lvgl 9.1.0.
Let's dive into this recipe to understand what is done. The objective is to add
this library as a shared object in the target rootfs, and also to generate a
Let's dive into this recipe to understand what is done. The objective is to add
this library as a shared object in the target rootfs, and also to generate a
SDK with lvgl.
This is the path of lvgl recipes: ``lvgl_yocto_guide/sources/meta-openembedded/
meta-oe/recipes-graphics/lvgl``
Here is the architecture of lvgl recipes folder:
Here is the architecture of lvgl recipes folder:
.. code-block:: bash
lvgl
├── files
│ ├── 0002-fix-sdl-handle-both-LV_IMAGE_SRC_FILE-and-LV_IMAGE_S.patch
@ -328,9 +331,9 @@ Here is the architecture of lvgl recipes folder:
├── lvgl_9.1.0.bb
└── lvgl-demo-fb_9.1.0.bb
- ``file`` folder contains all the patches that can be applied when
- ``file`` folder contains all the patches that can be applied when
building the recipe.
- ``lv_conf.inc`` is an include file, usually containing common configuration
- ``lv_conf.inc`` is an include file, usually containing common configuration
settings for LVGL that can be shared between multiple recipes.
- ``lvgl_9.1.0.bb`` is the recipe to build lvgl library.
- ``lvgl-demo-fb_9.1.0.bb`` is a recipe to build an application using lvgl.
@ -373,48 +376,48 @@ For now let's understand the recipe of lvgl library.
${includedir}/${PN}/ \
"
**LICENSE**: Indicates the licensing of the software, stating that it is
**LICENSE**: Indicates the licensing of the software, stating that it is
distributed under the MIT License.
**LIC_FILES_CHKSUM**: This variable contains a checksum (in this case, an MD5 hash)
for the license file (here assumed to be LICENCE.txt). This helps to ensure the
integrity of the license file included in the package. In LVGL repository,
there is a LICENSE.txt. To get the value of the hash of the file, you can do
**LIC_FILES_CHKSUM**: This variable contains a checksum (in this case, an MD5 hash)
for the license file (here assumed to be LICENCE.txt). This helps to ensure the
integrity of the license file included in the package. In LVGL repository,
there is a LICENSE.txt. To get the value of the hash of the file, you can do
this command: ``md5sum LICENSE.txt``
SRC_URI: Specifies the locations of the source code and patches for the recipe:
- The main source repository for LVGL specifying the master branch.
- The following arguments are the local patch files that will be applied to
the source code during the build process.
- The following arguments are the local patch files that will be applied to
the source code during the build process.
**SRCREV**: Defines the specific commit (in this case, a Git SHA hash) from
which the source code will be fetched. This ensures that the build uses a
**SRCREV**: Defines the specific commit (in this case, a Git SHA hash) from
which the source code will be fetched. This ensures that the build uses a
consistent version of the code.
**inherit**: This line indicates that the recipe uses the ``cmake`` class,
which provides functionality for building projects that use CMake as
**inherit**: This line indicates that the recipe uses the ``cmake`` class,
which provides functionality for building projects that use CMake as
their build system.
**EXTRA_OECMAKE**: Additional options passed to CMake during the
**EXTRA_OECMAKE**: Additional options passed to CMake during the
configuration step.
**S**: This variable defines the source directory where the unpacked source
code will be located after fetching. ``${WORKDIR}`` is a standard
**S**: This variable defines the source directory where the unpacked source
code will be located after fetching. ``${WORKDIR}`` is a standard
variable in BitBake that points to the working directory for the recipe.
require: This line includes another configuration file, ``lv-conf.inc``,
which likely contains additional configuration options or variables
require: This line includes another configuration file, ``lv-conf.inc``,
which likely contains additional configuration options or variables
specific to the LVGL library.
**FILES**: This is a BitBake variable used to specify the files that should
be included in a particular package. In this case, the variable is
specifying files for a package related to development (i.e., header
**FILES**: This is a BitBake variable used to specify the files that should
be included in a particular package. In this case, the variable is
specifying files for a package related to development (i.e., header
files).
Recipe Tasks
************
When a recipe is compiled, it will run multiple tasks. You can run each task
manually to understand what is generated each step, or you can run ``bitbake
When a recipe is compiled, it will run multiple tasks. You can run each task
manually to understand what is generated each step, or you can run ``bitbake
lvgl`` to run all the tasks.
Fetch (do_fetch)
@ -424,17 +427,17 @@ Fetch (do_fetch)
Fetch task fetches the package source from the local or remote repository.
The fetch Repo address has to be stored in **SRC_URI** variable. In
The fetch Repo address has to be stored in **SRC_URI** variable. In
**SRCREV** Variable the commit hash of github repo is defined.
When the fetch task has been completed, you can find the fetched sources in
When the fetch task has been completed, you can find the fetched sources in
``build/downloads``.
For this recipe, you will find a new folder here: ``lvgl_yocto_guide
build/downloads/git2/github.com.lvgl.lvgl``.
You can also find the folder architecture created in ``lvgl_yocto_guide/
build/tmp/work/cortexa53-poky-linux/lvgl`` but these folders are empty since
build/tmp/work/cortexa53-poky-linux/lvgl`` but these folders are empty since
only the fetch was done.
@ -443,28 +446,28 @@ Fetch (do_fetch)
Unpack (do_upack)
.. code-block:: bash
bitbake lvgl -c unpack
bitbake lvgl -c unpack
Unpack task unpacks the package that has been downloaded with Fetch task.
In the ``lvgl_yocto_guide/build/tmp/work/cortexa53-poky-linux/lvgl/9.1.0``
folder, you can now find the source code in ``git`` (as it was defined in
the recipe). You will also see the patches that will be applied on the next
step. So for now, the sources are unmodified and the same than the commit
In the ``lvgl_yocto_guide/build/tmp/work/cortexa53-poky-linux/lvgl/9.1.0``
folder, you can now find the source code in ``git`` (as it was defined in
the recipe). You will also see the patches that will be applied on the next
step. So for now, the sources are unmodified and the same than the commit
that was specified.
Patch (do_patch)
.. code-block:: bash
bitbake lvgl -c patch
Patch task locates the patch files and applies the patches to the sources
if any patch is available. This is optional task, executes if patch is
Patch task locates the patch files and applies the patches to the sources
if any patch is available. This is optional task, executes if patch is
available.
Patch file is also defined in **SRC_URI** variable. By default it runs in
Patch file is also defined in **SRC_URI** variable. By default it runs in
current source directory **${S}**.
Configure (do_configure)
@ -472,21 +475,21 @@ Configure (do_configure)
bitbake lvgl -c configure
The Configuration task configures the source by enabling and disabling any
build-time and configuration options for the software being built before
The Configuration task configures the source by enabling and disabling any
build-time and configuration options for the software being built before
compilation if any configuration is available.
This is a optional steps, executes if configuration is available.
In this case, it creates a build directory, It invokes CMake to configure
the project, specifying build options and paths based on variables in your
In this case, it creates a build directory, It invokes CMake to configure
the project, specifying build options and paths based on variables in your
recipe. It generates Makefiles or project files needed for the build. Also,
there are operations added in the task in ``lv-conf.inc``.
there are operations added in the task in ``lv-conf.inc``.
So at the end of the task, in the ``lvgl_yocto_guide/build/tmp/work/
cortexa53-poky-linux/lvgl/9.1.0``, you will find a ``build`` folder that was
generated running the CMake command, but nothing is built yet. Also, the
sysroots have everything required to build lvgl library.
cortexa53-poky-linux/lvgl/9.1.0``, you will find a ``build`` folder that was
generated running the CMake command, but nothing is built yet. Also, the
sysroots have everything required to build lvgl library.
Compile (do_compile)
@ -494,17 +497,17 @@ Compile (do_compile)
bitbake lvgl -c compile
The Compilation task compiles the source code if any compilation steps are
The Compilation task compiles the source code if any compilation steps are
available and generates a binary file.
This is a optional steps, executes if compilation is available.
If there are any compilation steps, then these steps are define in
If there are any compilation steps, then these steps are define in
do_compile() funtion of bitbake.
Like in the previous task, this is handle by ``inherit cmake``.
Like in the previous task, this is handle by ``inherit cmake``.
In the build folder, you can now see the built library. The ``.so`` files
In the build folder, you can now see the built library. The ``.so`` files
are available in ``lvgl_yocto_guide/build/tmp/work/ cortexa53-poky-linux/lvgl/9.1.0/build/lib``.
After this task has been completed, everything is ready to be installed.
@ -514,22 +517,22 @@ Install (do_install)
bitbake lvgl -c install
The Install task copies files that are to be packaged into the holding area
**${D}**. This task runs with the current working directory **${S}** which
The Install task copies files that are to be packaged into the holding area
**${D}**. This task runs with the current working directory **${S}** which
is the compilation directory.
It creates the necessary directory for the header files in the destination
It creates the necessary directory for the header files in the destination
installation directory.
It installs the ``lv_conf.h`` header file from the source directory into the
appropriate include directory in the destination path, ensuring it has the
It installs the ``lv_conf.h`` header file from the source directory into the
appropriate include directory in the destination path, ensuring it has the
correct permissions.
The lvgl library (``.so`` files) are also ready to be installed in the final
image. A new folder ``image`` was created.
The lvgl library (``.so`` files) are also ready to be installed in the final
image. A new folder ``image`` was created.
.. important::
In the file ``build/conf/local.conf``, add these 2 lines at the end of the
In the file ``build/conf/local.conf``, add these 2 lines at the end of the
file:
.. code-block:: bash
@ -537,41 +540,41 @@ Install (do_install)
IMAGE_INSTALL:append = " lvgl"
TOOLCHAIN_HOST_TASK:append = " lvgl"
This will add the lvgl library in the generated image, and it will also add
This will add the lvgl library in the generated image, and it will also add
the library to the host SDK we will generate later on.
With these modifications, you can now run the image recipe again::
With these modifications, you can now run the image recipe again::
bitbake core-image-base
This will execute all the previous described tasks.
If everything went well, you should now found this file ``build/tmp/deploy/
rpm/cortexa53/lvgl-9.1.0-r0.cortexa53.rpm`` and other rpm files related to
rpm/cortexa53/lvgl-9.1.0-r0.cortexa53.rpm`` and other rpm files related to
lvgl.
SDK generation
**************
Generating a Software Development Kit (SDK) in Yocto serves several important
purposes, particularly in embedded development:
Generating a Software Development Kit (SDK) in Yocto serves several important
purposes, particularly in embedded development:
- **Development Environment**: The SDK provides developers with a
ready-to-use development environment tailored for a specific target
hardware platform.
This includes the necessary tools, libraries, and headers to build
- **Development Environment**: The SDK provides developers with a
ready-to-use development environment tailored for a specific target
hardware platform.
This includes the necessary tools, libraries, and headers to build
applications that run on the target device.
- **Cross-Compilation**: The SDK allows developers to cross-compile
applications from a host machine (typically x86 or x86_64 architecture)
for a different architecture (e.g., ARM). This is essential for embedded
- **Cross-Compilation**: The SDK allows developers to cross-compile
applications from a host machine (typically x86 or x86_64 architecture)
for a different architecture (e.g., ARM). This is essential for embedded
systems, where development often occurs on more powerful machines.
- **Simplified Development**: By packaging all required components, the SDK
simplifies the process of setting up a development environment.
Developers don't need to manually install and configure tools and
- **Simplified Development**: By packaging all required components, the SDK
simplifies the process of setting up a development environment.
Developers don't need to manually install and configure tools and
libraries; everything needed is included in the SDK.
- **Consistent Build Environment**: The SDK ensures that developers are
working with the same versions of and tools used in the Yocto
build, which helps to avoid compatibility issues and ensures that
- **Consistent Build Environment**: The SDK ensures that developers are
working with the same versions of and tools used in the Yocto
build, which helps to avoid compatibility issues and ensures that
applications will behave as expected on the target device.
To generate an SDK of the environment, run the following command:
@ -579,21 +582,21 @@ To generate an SDK of the environment, run the following command:
.. code-block:: bash
bitbake core-image-base -c populate_sdk
This will create a sript ``build/tmp/deploy/sdk/
poky-glibc-x86_64-core-image-base-cortexa53-raspberrypi3-64-toolchain-5.0.4.
sh``. This script allows you to install the SDK where you prefer. Here is the
sh``. This script allows you to install the SDK where you prefer. Here is the
execution output of the scrips
.. code-block:: bash
$ ./sdk/poky-glibc-x86_64-core-image-base-cortexa53-raspberrypi3-64-toolchain-5.0.4.sh
$ ./sdk/poky-glibc-x86_64-core-image-base-cortexa53-raspberrypi3-64-toolchain-5.0.4.sh
Poky (Yocto Project Reference Distro) SDK installer version 5.0.4
=================================================================
Enter target directory for SDK (default: /opt/poky/5.0.4): /opt/poky/sdk-with-lvgl
You are about to install the SDK to "/opt/poky/sdk-with-lvgl". Proceed [Y/n]? y
If you want to ensure the SDK was generated with lvgl being installed, go to
If you want to ensure the SDK was generated with lvgl being installed, go to
the path you extracted the SDK and find all lvgl files:
.. code-block:: bash
@ -611,18 +614,18 @@ Now to use the SDK environment and cross-compile an application:
.. note::
The tools available in LVGL library will depend on the build configuration
The tools available in LVGL library will depend on the build configuration
the recipe was done with.
Custom recipe
Custom recipe
*************
Until this section, everything was already done for you. We used existing
recipes. The objective here is to create a recipe from scratch and to add the
Until this section, everything was already done for you. We used existing
recipes. The objective here is to create a recipe from scratch and to add the
generated binary in the image.
Create a layer
Create a layer
==============
First, create a layer and add it to the configuration file
@ -632,7 +635,7 @@ First, create a layer and add it to the configuration file
bitbake-layers create-layer ../sources/meta-mylvgl
bitbake-layers add-layer ../sources/meta-mylvgl
In the ``sources`` folder, a new folder was created: ``meta-mylvgl`` and the
In the ``sources`` folder, a new folder was created: ``meta-mylvgl`` and the
directory tree should look like the following
.. code-block:: none
@ -646,28 +649,28 @@ directory tree should look like the following
└── example_0.1.bb
Create a recipe
Create a recipe
===============
Following this structure, create a folder containing the recipies to build 1
Following this structure, create a folder containing the recipies to build 1
or multiple applications using lvgl
.. code-block::
cd ../sources/meta-mylvgl
mkdir -p recipes-lvglapp/lvgl-fbdev-benchmark/files
touch recipes-lvglapp/lvgl-fbdev-benchmark/lvglbenchmarkfbdev_2.4.bb
We will focus on 1 application that will clone an lvgl git repository and patch
We will focus on 1 application that will clone an lvgl git repository and patch
it for our needs.
The content of ``recipes-lvglapp/lvgl-fbdev-benchmark/lvglbenchmarkfbdev_2.4.
bb``
.. code-block:: none
DESCRIPTION = "My C++ lvgl app with CMake"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
@ -675,7 +678,7 @@ bb``
SRC_URI = "gitsm://github.com/lvgl/lv_port_linux.git;branch=master;protocol=https \
file://0001-change-config-file-to-run-fbdev-with-2-threads.patch \
file://0002-adapt-CMakeLists-file-to-compile-and-link-fbdev.patch \
"
"
S = "${WORKDIR}/git"
@ -727,7 +730,7 @@ Content of ``0001-change-config-file-to-run-fbdev-with-2-threads.patch``
+#define LV_USE_STDLIB_MALLOC LV_STDLIB_CLIB
+#define LV_USE_STDLIB_STRING LV_STDLIB_CLIB
+#define LV_USE_STDLIB_SPRINTF LV_STDLIB_CLIB
#define LV_STDINT_INCLUDE <stdint.h>
#define LV_STDDEF_INCLUDE <stddef.h>
@@ -89,7 +89,7 @@
@ -736,22 +739,22 @@ Content of ``0001-change-config-file-to-run-fbdev-with-2-threads.patch``
* - LV_OS_CUSTOM */
-#define LV_USE_OS LV_OS_NONE
+#define LV_USE_OS LV_OS_PTHREAD
#if LV_USE_OS == LV_OS_CUSTOM
#define LV_OS_CUSTOM_INCLUDE <stdint.h>
@@ -117,12 +117,12 @@
* and can't be drawn in chunks. */
/*The target buffer size for simple layer chunks.*/
-#define LV_DRAW_LAYER_SIMPLE_BUF_SIZE (24 * 1024) /*[bytes]*/
+#define LV_DRAW_LAYER_SIMPLE_BUF_SIZE (512 * 1024) /*[bytes]*/
/* The target buffer size for simple layer chunks. */
-#define LV_DRAW_LAYER_SIMPLE_BUF_SIZE (24 * 1024) /* [bytes] */
+#define LV_DRAW_LAYER_SIMPLE_BUF_SIZE (512 * 1024) /* [bytes] */
/* The stack size of the drawing thread.
* NOTE: If FreeType or ThorVG is enabled, it is recommended to set it to 32KB or more.
*/
-#define LV_DRAW_THREAD_STACK_SIZE (8 * 1024) /*[bytes]*/
+#define LV_DRAW_THREAD_STACK_SIZE (32 * 1024) /*[bytes]*/
-#define LV_DRAW_THREAD_STACK_SIZE (8 * 1024) /* [bytes] */
+#define LV_DRAW_THREAD_STACK_SIZE (32 * 1024) /* [bytes] */
#define LV_USE_DRAW_SW 1
#if LV_USE_DRAW_SW == 1
@@ -147,7 +147,7 @@
@ -760,7 +763,7 @@ Content of ``0001-change-config-file-to-run-fbdev-with-2-threads.patch``
* > 1 means multiple threads will render the screen in parallel */
- #define LV_DRAW_SW_DRAW_UNIT_CNT 1
+ #define LV_DRAW_SW_DRAW_UNIT_CNT 2
/* Use Arm-2D to accelerate the sw render */
#define LV_USE_DRAW_ARM2D_SYNC 0
@@ -979,8 +979,8 @@
@ -773,26 +776,26 @@ Content of ``0001-change-config-file-to-run-fbdev-with-2-threads.patch``
+ #define LV_LINUX_FBDEV_BUFFER_COUNT 2
#define LV_LINUX_FBDEV_BUFFER_SIZE 60
#endif
@@ -1069,19 +1069,19 @@
#define LV_USE_DEMO_WIDGETS 1
/*Demonstrate the usage of encoder and keyboard*/
/* Demonstrate the usage of encoder and keyboard */
-#define LV_USE_DEMO_KEYPAD_AND_ENCODER 1
+#define LV_USE_DEMO_KEYPAD_AND_ENCODER 0
/*Benchmark your system*/
/* Benchmark your system */
#define LV_USE_DEMO_BENCHMARK 1
/*Render test for each primitives. Requires at least 480x272 display*/
/* Render test for each primitives. Requires at least 480x272 display */
-#define LV_USE_DEMO_RENDER 1
+#define LV_USE_DEMO_RENDER 0
/*Stress test for LVGL*/
/* Stress test for LVGL */
-#define LV_USE_DEMO_STRESS 1
+#define LV_USE_DEMO_STRESS 0
/*Music player demo*/
/* Music player demo */
-#define LV_USE_DEMO_MUSIC 1
+#define LV_USE_DEMO_MUSIC 0
#if LV_USE_DEMO_MUSIC
@ -800,26 +803,26 @@ Content of ``0001-change-config-file-to-run-fbdev-with-2-threads.patch``
#define LV_DEMO_MUSIC_LANDSCAPE 0
@@ -1091,16 +1091,16 @@
#endif
/*Flex layout demo*/
/* Flex layout demo */
-#define LV_USE_DEMO_FLEX_LAYOUT 1
+#define LV_USE_DEMO_FLEX_LAYOUT 0
/*Smart-phone like multi-language demo*/
/* Smart-phone like multi-language demo */
-#define LV_USE_DEMO_MULTILANG 1
+#define LV_USE_DEMO_MULTILANG 0
/*Widget transformation demo*/
/* Widget transformation demo */
-#define LV_USE_DEMO_TRANSFORM 1
+#define LV_USE_DEMO_TRANSFORM 0
/*Demonstrate scroll settings*/
/* Demonstrate scroll settings */
-#define LV_USE_DEMO_SCROLL 1
+#define LV_USE_DEMO_SCROLL 0
/*Vector graphic demo*/
/* Vector graphic demo */
#define LV_USE_DEMO_VECTOR_GRAPHIC 0
--
--
2.34.1
@ -852,21 +855,21 @@ Content of ``0002-adapt-CMakeLists-file-to-compile-and-link-fbdev.patch``
@@ -1,8 +1,8 @@
cmake_minimum_required(VERSION 3.10)
project(lvgl)
-set(CMAKE_C_STANDARD 99)#C99 # lvgl officially support C99 and above
-set(CMAKE_CXX_STANDARD 17)#C17
+set(CMAKE_C_STANDARD 99)
+set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(EXECUTABLE_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/bin)
@@ -10,15 +10,8 @@ set(EXECUTABLE_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/bin)
add_subdirectory(lvgl)
target_include_directories(lvgl PUBLIC ${PROJECT_SOURCE_DIR})
-add_executable(main main.c mouse_cursor_icon.c)
+add_executable(lvglbenchmark main.c mouse_cursor_icon.c)
-include(${CMAKE_CURRENT_LIST_DIR}/lvgl/tests/FindLibDRM.cmake)
-include_directories(${Libdrm_INCLUDE_DIRS})
-
@ -878,11 +881,11 @@ Content of ``0002-adapt-CMakeLists-file-to-compile-and-link-fbdev.patch``
-add_custom_target (run COMMAND ${EXECUTABLE_OUTPUT_PATH}/main DEPENDS main)
+target_link_libraries(lvglbenchmark lvgl lvgl::examples lvgl::demos lvgl::thorvg m pthread)
+add_custom_target (run COMMAND ${EXECUTABLE_OUTPUT_PATH}/lvglbenchmark DEPENDS main)
--
--
2.34.1
Build the recipe
Build the recipe
================
You should now be able to see the recipe listing the existing recipes
@ -891,7 +894,7 @@ You should now be able to see the recipe listing the existing recipes
bitbake-layers show-recipes | grep lvglbenchmarkfbdev
Now add the recipe to the project. Modify ``build/conf/local.conf`` file adding
Now add the recipe to the project. Modify ``build/conf/local.conf`` file adding
this line
.. code-block::
@ -904,7 +907,7 @@ Now build the image
bitbake core-image-base
Run this command to ensure the binary was generated and was installed in the
Run this command to ensure the binary was generated and was installed in the
rootfs
.. code-block::

127
docs/integration/os/yocto/terms_and_variables.rst → docs/details/integration/os/yocto/terms_and_variables.rst
View File

@ -1,52 +1,55 @@
Yocto Project Terms
###################
.. _yocto_project_terms:
Getting started in Yocto can be overwheming. There are many terms used that are
===================
Yocto Project Terms
===================
Getting started in Yocto can be overwheming. There are many terms used that are
specific to Yocto and Bitbake environment.
A list of terms and definitions users new to the Yocto Project
A list of terms and definitions users new to the Yocto Project
development environment might find helpful can be found `here <https://docs.
yoctoproject.org/ref-manual/terms.html>`_.
Yocto Variables Glossary
########################
************************
This chapter lists basic variables used in the LVGL Yocto guide and gives an
This chapter lists basic variables used in the LVGL Yocto guide and gives an
overview of their function and contents.
A More complete variable glossary can be found in `Yocto Variable Glossary
<https://docs.yoctoproject.org/ref-manual/variables.html>`_. This section
A More complete variable glossary can be found in `Yocto Variable Glossary
<https://docs.yoctoproject.org/ref-manual/variables.html>`_. This section
covers a lot of variables used in the OpenEmbedded build system.
.. _S:
S
=
S
-
The location in the Build Directory where unpacked recipe source code resides.
By default, this directory is ${WORKDIR}/${BPN}-${PV}, where ${BPN} is the
base recipe name and ${PV} is the recipe version. If the source tarball
extracts the code to a directory named anything other than ${BPN}-${PV}, or if
the source code is fetched from an SCM such as Git or Subversion, then you
must set S in the recipe so that the OpenEmbedded build system knows where to
By default, this directory is ${WORKDIR}/${BPN}-${PV}, where ${BPN} is the
base recipe name and ${PV} is the recipe version. If the source tarball
extracts the code to a directory named anything other than ${BPN}-${PV}, or if
the source code is fetched from an SCM such as Git or Subversion, then you
must set S in the recipe so that the OpenEmbedded build system knows where to
find the unpacked source.
As an example, assume a Source Directory top-level folder named poky and a
default Build Directory at poky/build. In this case, the work directory the
As an example, assume a Source Directory top-level folder named poky and a
default Build Directory at poky/build. In this case, the work directory the
build system uses to keep the unpacked recipe for db is the following:
.. code-block:: bash
.. code-block:: bash
poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
The unpacked source code resides in the db-5.1.19 folder.
This next example assumes a Git repository. By default, Git repositories are
cloned to ${WORKDIR}/git during do_fetch. Since this path is different from the
This next example assumes a Git repository. By default, Git repositories are
cloned to ${WORKDIR}/git during do_fetch. Since this path is different from the
default value of S, you must set it specifically so the source can be located:
.. code-block:: bash
.. code-block:: bash
SRC_URI = "git://path/to/repo.git;branch=main"
S = "${WORKDIR}/git"
@ -54,10 +57,10 @@ default value of S, you must set it specifically so the source can be located:
.. _D:
D
=
D
-
The destination directory. The location in the Build Directory where components
The destination directory. The location in the Build Directory where components
are installed by the do_install task. This location defaults to:
.. code-block:: bash
@ -70,35 +73,35 @@ are installed by the do_install task. This location defaults to:
.. _B:
B
=
B
-
The directory within the Build Directory in which the OpenEmbedded build system
places generated objects during a recipe's build process. By default, this
The directory within the Build Directory in which the OpenEmbedded build system
places generated objects during a recipe's build process. By default, this
directory is the same as the S directory, which is defined as:
.. code-block:: bash
.. code-block:: bash
S = "${WORKDIR}/${BP}"
You can separate the (S) directory and the directory pointed to by the B
variable. Most Autotools-based recipes support separating these directories.
The build system defaults to using separate directories for gcc and some kernel
You can separate the (S) directory and the directory pointed to by the B
variable. Most Autotools-based recipes support separating these directories.
The build system defaults to using separate directories for gcc and some kernel
recipes.
.. _WORKDIR:
WORKDIR
=======
-------
The pathname of the work directory in which the OpenEmbedded build system
builds a recipe. This directory is located within the TMPDIR directory
structure and is specific to the recipe being built and the system for which it
The pathname of the work directory in which the OpenEmbedded build system
builds a recipe. This directory is located within the TMPDIR directory
structure and is specific to the recipe being built and the system for which it
is being built.
The WORKDIR directory is defined as follows:
.. code-block:: bash
.. code-block:: bash
${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
@ -107,45 +110,45 @@ The actual directory depends on several things:
- **TMPDIR**: The top-level build output directory
- **MULTIMACH_TARGET_SYS**: The target system identifier
- **PN**: The recipe name
- **EXTENDPE**: The epoch — if PE is not specified, which is usually the
- **EXTENDPE**: The epoch — if PE is not specified, which is usually the
case for most recipes, then EXTENDPE is blank.
- **PV**: The recipe version
- **PR**: The recipe revision
As an example, assume a Source Directory top-level folder name poky, a default
Build Directory at poky/build, and a qemux86-poky-linux machine target system.
Furthermore, suppose your recipe is named foo_1.3.0-r0.bb. In this case, the
As an example, assume a Source Directory top-level folder name poky, a default
Build Directory at poky/build, and a qemux86-poky-linux machine target system.
Furthermore, suppose your recipe is named foo_1.3.0-r0.bb. In this case, the
work directory the build system uses to build the package would be as follows:
.. code-block:: bash
.. code-block:: bash
poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
.. _PN:
PN
==
PN
--
This variable can have two separate functions depending on the context: a
This variable can have two separate functions depending on the context: a
recipe name or a resulting package name.
PN refers to a recipe name in the context of a file used by the OpenEmbedded
build system as input to create a package. The name is normally extracted from
the recipe file name. For example, if the recipe is named expat_2.0.1.bb, then
PN refers to a recipe name in the context of a file used by the OpenEmbedded
build system as input to create a package. The name is normally extracted from
the recipe file name. For example, if the recipe is named expat_2.0.1.bb, then
the default value of PN will be “expat”.
The variable refers to a package name in the context of a file created or
The variable refers to a package name in the context of a file created or
produced by the OpenEmbedded build system.
If applicable, the PN variable also contains any special suffix or prefix. For
example, using bash to build packages for the native machine, PN is
bash-native. Using bash to build packages for the target and for Multilib, PN
If applicable, the PN variable also contains any special suffix or prefix. For
example, using bash to build packages for the native machine, PN is
bash-native. Using bash to build packages for the target and for Multilib, PN
would be bash and lib64-bash, respectively.
.. _PR:
PR
==
--
The revision of the recipe. The default value for this variable is
"r0". Subsequent revisions of the recipe conventionally have the
@ -154,8 +157,8 @@ PR is conventionally reset to "r0".
.. note::
The OpenEmbedded build system does not need the aid of PR to know when to
rebuild a recipe. The build system uses the task input checksums along with
The OpenEmbedded build system does not need the aid of PR to know when to
rebuild a recipe. The build system uses the task input checksums along with
the stamp and shared state cache mechanisms.
The PR variable primarily becomes significant when a package
@ -176,18 +179,18 @@ packaging fixes.
Because manually managing PR can be cumbersome and error-prone,
an automated solution exists. See the
"`working with a pr service <https://docs.yoctoproject.org/dev-manual/packages.
html#working-with-a-pr-service>`_" section in the Yocto Project Development
html#working-with-a-pr-service>`_" section in the Yocto Project Development
Tasks Manual for more information.
.. _PV:
PV
==
--
The version of the recipe. The version is normally extracted from the recipe
filename. For example, if the recipe is named expat_2.0.1.bb, then the default
value of PV will be “2.0.1”. PV is generally not overridden within a recipe
unless it is building an unstable (i.e. development) version from a source code
The version of the recipe. The version is normally extracted from the recipe
filename. For example, if the recipe is named expat_2.0.1.bb, then the default
value of PV will be “2.0.1”. PV is generally not overridden within a recipe
unless it is building an unstable (i.e. development) version from a source code
repository (e.g. Git or Subversion).
PV is the default value of the PKGV variable.
PV is the default value of the PKGV variable.

0
docs/integration/os/zephyr.rst → docs/details/integration/os/zephyr.rst
View File

0
docs/overview/renderers/arm2d.rst → docs/details/integration/renderers/arm2d.rst
View File

8
docs/overview/renderers/index.rst → docs/details/integration/renderers/index.rst
View File

@ -5,12 +5,10 @@ Renderers and GPUs
.. toctree::
:maxdepth: 2
sw
arm2d
nema_gfx
pxp
nxp_pxp
nxp_vglite
sdl
stm32_dma2d
sw
vglite
vg_lite

0
docs/overview/renderers/nema_gfx.rst → docs/details/integration/renderers/nema_gfx.rst
View File

2
docs/overview/renderers/pxp.rst → docs/details/integration/renderers/nxp_pxp.rst
View File

@ -3,7 +3,7 @@ NXP PXP GPU
===========
API
---
***
:ref:`lv_draw_pxp_h`

26
docs/overview/renderers/vg_lite.rst → docs/details/integration/renderers/nxp_vglite.rst
View File

@ -1,6 +1,8 @@
===================
VG-Lite General GPU
===================
.. _vglite:
===============
NXP VG-Lite GPU
===============
This is a generic VG-Lite rendering backend implementation that is designed to utilize
`VeriSilicon <https://verisilicon.com/>`_'s generic API to operate GPU hardware as much as possible.
@ -65,4 +67,20 @@ VG-Lite Simulator
LVGL integrates a VG-Lite simulator based on ThorVG.
Its purpose is to simplify the debugging of VG-Lite adaptation and reduce the time of debugging and locating problems on hardware devices.
For detailed instructions, see `VG-Lite Simulator <overview/vg_lite_tvg>`__.
For detailed instructions, see :ref:`vg_lite_tvg`.
API
***
:ref:`lv_draw_vglite_h`
:ref:`lv_vglite_buf_h`
:ref:`lv_vglite_matrix_h`
:ref:`lv_vglite_path_h`
:ref:`lv_vglite_utils_h`

4
docs/overview/renderers/sdl.rst → docs/details/integration/renderers/sdl.rst
View File

@ -1,9 +1,9 @@
============
SDL renderer
SDL Renderer
============
API
---
***
:ref:`lv_draw_sdl_h`

9
docs/details/integration/renderers/stm32_dma2d.rst Normal file
View File

@ -0,0 +1,9 @@
===============
STM32 DMA2D GPU
===============
API
***
:ref:`lv_draw_dma2d_h`

4
docs/overview/renderers/sw.rst → docs/details/integration/renderers/sw.rst
View File

@ -1,9 +1,9 @@
=================
Software renderer
Software Renderer
=================
API
---
***
:ref:`lv_draw_sw_h`

0
docs/libs/arduino_esp_littlefs.rst → docs/details/libs/arduino_esp_littlefs.rst
View File

0
docs/libs/arduino_sd.rst → docs/details/libs/arduino_sd.rst
View File

Some files were not shown because too many files have changed in this diff Show More