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

docs: fix references, lists, texts (#5193)

Browse Source
This commit is contained in:
PGNetHun
2024-01-06 08:34:02 +01:00
committed by GitHub
parent 4f69d10b22
commit e37658c061
55 changed files with 285 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/CHANGELOG.rst
View File

@@ -34,9 +34,9 @@ Main new features
- Run time display color format adjustment with RGB888 support - Run time display color format adjustment with RGB888 support
- Built-in support ``pthread``, ``FreeRTOS`` and other (RT)OSes which are used during rendering - Built-in support ``pthread``, ``FreeRTOS`` and other (RT)OSes which are used during rendering
- Built-in support LVGL's, C library, and other ``stdlib``s - Built-in support LVGL's, C library, and other ``stdlib``s
- Better parallel rendering architecture. See the details `here </porting/draw>`__ - Better parallel rendering architecture. See the details :ref:`here <porting_draw>`
- Built in display and touch driver: SDL, Linux Frame buffer, NuttX LCD and touch drivers, ST7789 and ILI9341 driver are available and more will come soon - Built in display and touch driver: SDL, Linux Frame buffer, NuttX LCD and touch drivers, ST7789 and ILI9341 driver are available and more will come soon
- `lv_observer </others/observer>`__ allows to bind data to UI elements and create a uniform and easy to maintain API - :ref:`observer` allows to bind data to UI elements and create a uniform and easy to maintain API
- GitHub CodeSpace integration makes possible to run LVGL in an Online VSCode editor with 3 click. See more `here <https://blog.lvgl.io/2023-04-13/monthly-newsletter>`__ - GitHub CodeSpace integration makes possible to run LVGL in an Online VSCode editor with 3 click. See more `here <https://blog.lvgl.io/2023-04-13/monthly-newsletter>`__
- Add vector graphics support via ThorVG. It can be used to draw vector graphics to a `Canvas <https://github.com/lvgl/lvgl/blob/master/examples/widgets/canvas/lv_example_canvas_8.c>`__ - Add vector graphics support via ThorVG. It can be used to draw vector graphics to a `Canvas <https://github.com/lvgl/lvgl/blob/master/examples/widgets/canvas/lv_example_canvas_8.c>`__
- :ref:`lv_image` supports aligning, stretching or tiling the image source if the widget is larger or smaller. - :ref:`lv_image` supports aligning, stretching or tiling the image source if the widget is larger or smaller.

42
docs/CONTRIBUTING.rst
View File

@@ -37,6 +37,8 @@ Before getting started here are some guidelines to make contribution smoother:
details instead of sending a pull request directly. details instead of sending a pull request directly.
- Please read and follow the Coding style guide. - Please read and follow the Coding style guide.
.. _contributing_pull_request:
Pull request Pull request
------------ ------------
@@ -73,7 +75,7 @@ same way for the other repositories.
"Fork" button in the top right corner. It will "copy" the ``lvgl`` "Fork" button in the top right corner. It will "copy" the ``lvgl``
repository to your GitHub account (``https://github.com/<YOUR_NAME>?tab=repositories``) repository to your GitHub account (``https://github.com/<YOUR_NAME>?tab=repositories``)
2. Clone your forked repository. 2. Clone your forked repository.
3. Add your changes. You can create a *feature branch* from *master* for the updates: ``git checkout -b the-new-feature`` 3. Add your changes. You can create a *feature branch* from *master* for the updates: ``git checkout -b <the-new-feature-branch-name>``
4. Commit and push your changes to the forked ``lvgl`` repository. 4. Commit and push your changes to the forked ``lvgl`` repository.
5. Create a PR on GitHub from the page of your ``lvgl`` repository (``https://github.com/<YOUR_NAME>/lvgl``) by 5. Create a PR on GitHub from the page of your ``lvgl`` repository (``https://github.com/<YOUR_NAME>/lvgl``) by
clicking the *"New pull request"* button. Don't forget to select the branch where you added your changes. clicking the *"New pull request"* button. Don't forget to select the branch where you added your changes.
@@ -83,6 +85,8 @@ same way for the other repositories.
8. If you need to make more changes, just update your forked ``lvgl`` repo with new commits. 8. If you need to make more changes, just update your forked ``lvgl`` repo with new commits.
They will automatically appear in the PR. They will automatically appear in the PR.
.. _contributing_commit_message_format:
Commit message format Commit message format
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
@@ -118,7 +122,7 @@ commit. It's usually one word and can be chosen freely. For example
- use the imperative, present tense: "change" not "changed" nor "changes" - use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize the first letter - don't capitalize the first letter
- no dot (.) at the end - no dot (``.``) at the end
- max 90 characters - max 90 characters
``<body>`` optional and can be used to describe the details of this ``<body>`` optional and can be used to describe the details of this
@@ -142,6 +146,8 @@ Some examples:
It's similar to HTML <span> It's similar to HTML <span>
- docs(porting): fix typo - docs(porting): fix typo
.. _contributing_dco:
Developer Certification of Origin (DCO) Developer Certification of Origin (DCO)
--------------------------------------- ---------------------------------------
@@ -217,6 +223,8 @@ single line of LVGL code.
Below we have collected some opportunities about the ways you can Below we have collected some opportunities about the ways you can
contribute to LVGL. contribute to LVGL.
.. _contributing_star:
Give LVGL a Star Give LVGL a Star
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@@ -235,11 +243,13 @@ Star
This simple click makes LVGL more visible on GitHub and makes it more This simple click makes LVGL more visible on GitHub and makes it more
attractive to other people. So with this, you already helped a lot! attractive to other people. So with this, you already helped a lot!
.. _contributing_achieved:
Tell what you have achieved Tell what you have achieved
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
Have you already started using LVGL in a Have you already started using LVGL in a
`Simulator </get-started/platforms/pc-simulator>`__, a development :ref:`simulator`, a development
board, or on your custom hardware? Was it easy or were there some board, or on your custom hardware? Was it easy or were there some
obstacles? Are you happy with the result? Showing your project to others obstacles? Are you happy with the result? Showing your project to others
is a win-win situation because it increases your and LVGL's reputation is a win-win situation because it increases your and LVGL's reputation
@@ -272,6 +282,8 @@ If you don't want to speak about your project publicly, feel free to use
`Contact form <https://lvgl.io/#contact>`__ on lvgl.io to private `Contact form <https://lvgl.io/#contact>`__ on lvgl.io to private
message to us. message to us.
.. _contributing_write_examples:
Write examples Write examples
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
@@ -279,12 +291,12 @@ As you learn LVGL you will probably play with the features of widgets.
Why not publish your experiments? Why not publish your experiments?
Each widgets' documentation contains examples. For instance, here are Each widgets' documentation contains examples. For instance, here are
the examples of the `Drop-down list </widgets/dropdown#examples>`__ the examples of the :ref:`Drop-down list <lv_dropdown_example>`
widget. The examples are directly loaded from the widget. The examples are directly loaded from the
`lvgl/examples <https://github.com/lvgl/lvgl/tree/master/examples>`__ `lvgl/examples <https://github.com/lvgl/lvgl/tree/master/examples>`__
folder. folder.
So all you need to do is send a `Pull request <#pull-request>`__ to the So all you need to do is send a :ref:`contributing_pull_request` to the
`lvgl <https://github.com/lvgl/lvgl>`__ repository and follow some `lvgl <https://github.com/lvgl/lvgl>`__ repository and follow some
conventions: conventions:
@@ -296,6 +308,8 @@ conventions:
`lvgl/examples/widgets <https://github.com/lvgl/lvgl/tree/master/examples/widgets>`__ `lvgl/examples/widgets <https://github.com/lvgl/lvgl/tree/master/examples/widgets>`__
folder. folder.
.. _contributing_improve_docs:
Improve the docs Improve the docs
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@@ -308,6 +322,8 @@ GitHub.
Note that the documentation is also formatted in Note that the documentation is also formatted in
`Markdown <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet>`__. `Markdown <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet>`__.
.. _contributing_report_bugs:
Report bugs Report bugs
~~~~~~~~~~~ ~~~~~~~~~~~
@@ -321,17 +337,21 @@ When filing the issue be sure to fill out the template. It helps find
the root of the problem while avoiding extensive questions and exchanges the root of the problem while avoiding extensive questions and exchanges
with other developers. with other developers.
.. _contributing_send_fixes:
Send fixes Send fixes
~~~~~~~~~~ ~~~~~~~~~~
The beauty of open-source software is you can easily dig in to it to The beauty of open-source software is you can easily dig in to it to
understand how it works. You can also fix or adjust it as you wish. understand how it works. You can also fix or adjust it as you wish.
If you found and fixed a bug don't hesitate to send a `Pull If you found and fixed a bug don't hesitate to send a
request <#pull-request>`__ with the fix. :ref:`contributing_pull_request` with the fix.
In your Pull request please also add a line to In your Pull request please also add a line to
```CHANGELOG.md`` <https://github.com/lvgl/lvgl/blob/master/CHANGELOG.md>`__. `CHANGELOG.md <https://github.com/lvgl/lvgl/blob/master/CHANGELOG.md>`__.
.. _contributing_forum:
Join the conversations in the Forum Join the conversations in the Forum
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -352,6 +372,8 @@ hesitate to share your thoughts and suggestions.
Participating in the discussions is one of the best ways to become part Participating in the discussions is one of the best ways to become part
of the project and get to know like-minded people! of the project and get to know like-minded people!
.. _contributing_add_features:
Add features Add features
~~~~~~~~~~~~ ~~~~~~~~~~~~
@@ -365,7 +387,7 @@ folder. The
file describes the basics rules of contribution and also lists some file describes the basics rules of contribution and also lists some
ideas. ideas.
For further ideas take a look at the `Roadmap </ROADMAP>`__ page. If you For further ideas take a look at the :ref:`roadmap` page. If you
are interested in any of them feel free to share your opinion and/or are interested in any of them feel free to share your opinion and/or
participate in the implementation. participate in the implementation.
@@ -380,6 +402,8 @@ When adding a new features the following also needs to be updated:
- Add `examples <https://github.com/lvgl/lvgl/tree/master/examples>`__ - Add `examples <https://github.com/lvgl/lvgl/tree/master/examples>`__
- Update the `changelog <https://github.com/lvgl/lvgl/tree/master/docs/CHANGELOG.md>`__ - Update the `changelog <https://github.com/lvgl/lvgl/tree/master/docs/CHANGELOG.md>`__
.. _contributing_become_maintainer:
Become a maintainer Become a maintainer
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~

1
docs/ROADMAP.rst
View File

@@ -3,6 +3,7 @@
.. |uncheck| replace:: 🔲 .. |uncheck| replace:: 🔲
.. _roadmap:
Roadmap Roadmap
======= =======

2
docs/conf.py
View File

@@ -66,7 +66,7 @@ master_doc = 'index'
# General information about the project. # General information about the project.
project = 'LVGL' project = 'LVGL'
copyright = '2023, LVGL Kft' copyright = '2024, LVGL Kft'
author = 'LVGL community' author = 'LVGL community'

19
docs/layouts/flex.rst
View File

@@ -23,15 +23,15 @@ with :c:macro:`LV_USE_FLEX` in ``lv_conf.h``.
Terms Terms
***** *****
- tracks: the rows or columns - **tracks**: the rows or columns
- main direction: row or column, the direction in which the items are - **main direction**: row or column, the direction in which the items are
placed placed
- cross direction: perpendicular to the main direction - **cross direction**: perpendicular to the main direction
- wrap: if there is no more space in the track a new track is started - **wrap**: if there is no more space in the track a new track is started
- grow: if set on an item it will grow to fill the remaining space on - **grow**: if set on an item it will grow to fill the remaining space on
the track. The available space will be distributed among items the track. The available space will be distributed among items
respective to their grow value (larger value means more space) respective to their grow value (larger value means more space)
- gap: the space between the rows and columns or the items on a track - **gap**: the space between the rows and columns or the items on a track
Simple interface Simple interface
**************** ****************
@@ -75,7 +75,7 @@ To manage the placement of the children use
The possible values are: The possible values are:
- :cpp:enumerator:`LV_FLEX_ALIGN_START`: means left on a horizontally and top vertically. (default) - :cpp:enumerator:`LV_FLEX_ALIGN_START`: means left on a horizontally and top vertically (default)
- :cpp:enumerator:`LV_FLEX_ALIGN_END`: means right on a horizontally and bottom vertically - :cpp:enumerator:`LV_FLEX_ALIGN_END`: means right on a horizontally and bottom vertically
- :cpp:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center - :cpp:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center
- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_EVENLY`: items are distributed so - :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_EVENLY`: items are distributed so
@@ -117,8 +117,9 @@ Style interface
*************** ***************
All the Flex-related values are style properties under the hood and you All the Flex-related values are style properties under the hood and you
can use them similarly to any other style property. The following flex can use them similarly to any other style property.
related style properties exist:
The following flex related style properties exist:
- :cpp:enumerator:`FLEX_FLOW` - :cpp:enumerator:`FLEX_FLOW`
- :cpp:enumerator:`FLEX_MAIN_PLACE` - :cpp:enumerator:`FLEX_MAIN_PLACE`

15
docs/layouts/grid.rst
View File

@@ -23,10 +23,10 @@ with :c:macro:`LV_USE_GRID` in ``lv_conf.h``.
Terms Terms
***** *****
- tracks: the rows or columns - **tracks**: the rows or columns
- free unit (FR): if set on track's size is set in ``FR`` it will grow - **free unit (FR)**: if set on track's size is set in ``FR`` it will grow
to fill the remaining space on the parent. to fill the remaining space on the parent.
- gap: the space between the rows and columns or the items on a track - **gap**: the space between the rows and columns or the items on a track
Simple interface Simple interface
**************** ****************
@@ -74,13 +74,13 @@ To do this call
``column_align`` and ``row_align`` determine how to align the children ``column_align`` and ``row_align`` determine how to align the children
in its cell. The possible values are: in its cell. The possible values are:
- :cpp:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default) - :cpp:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically (default)
- :cpp:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically - :cpp:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically
- :cpp:enumerator:`LV_GRID_ALIGN_CENTER`: simply center ``column_pos`` and ``row_pos`` - :cpp:enumerator:`LV_GRID_ALIGN_CENTER`: simply center ``column_pos`` and ``row_pos``
means the zero based index of the cell into the item should be placed. means the zero based index of the cell into the item should be placed.
``column_span`` and ``row_span`` means how many tracks should the item ``column_span`` and ``row_span`` means how many tracks should the item
involve from the start cell. Must be >= 1. involve from the start cell. Must be ``>= 1``.
.. _grid_align: .. _grid_align:
@@ -131,8 +131,9 @@ Style interface
*************** ***************
All the Grid related values are style properties under the hood and you All the Grid related values are style properties under the hood and you
can use them similarly to any other style properties. The following Grid can use them similarly to any other style properties.
related style properties exist:
The following Grid related style properties exist:
- :cpp:enumerator:`GRID_COLUMN_DSC_ARRAY` - :cpp:enumerator:`GRID_COLUMN_DSC_ARRAY`
- :cpp:enumerator:`GRID_ROW_DSC_ARRAY` - :cpp:enumerator:`GRID_ROW_DSC_ARRAY`

8
docs/libs/bmp.rst
View File

@@ -4,9 +4,11 @@
BMP decoder BMP decoder
=========== ===========
This extension allows the use of BMP images in LVGL. This implementation This extension allows the use of BMP images in LVGL.
uses `bmp-decoder <https://github.com/caj-johnson/bmp-decoder>`__
library. The pixels are read on demand (not the whole image is loaded) Library source: https://github.com/caj-johnson/bmp-decoder
The pixels are read on demand (not the whole image is loaded)
so using BMP images requires very little RAM. so using BMP images requires very little RAM.
If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_BMP` LVGL will register a new If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_BMP` LVGL will register a new

15
docs/libs/ffmpeg.rst
View File

@@ -6,15 +6,18 @@ FFmpeg support
A complete, cross-platform solution to record, convert and stream audio and video. A complete, cross-platform solution to record, convert and stream audio and video.
Detailed introduction: `FFmpeg <https://www.ffmpeg.org/>`__ Detailed introduction: https://www.ffmpeg.org
Install FFmpeg Install FFmpeg
-------------- --------------
- Download FFmpeg from `here <https://www.ffmpeg.org/download.html>`__ Download first FFmpeg from `here <https://www.ffmpeg.org/download.html>`__, then install it:
- ``./configure --disable-all --disable-autodetect --disable-podpages --disable-asm --enable-avcodec --enable-avformat --enable-decoders --enable-encoders --enable-demuxers --enable-parsers --enable-protocol='file' --enable-swscale --enable-zlib``
- ``make`` .. code:: shell
- ``sudo make install``
./configure --disable-all --disable-autodetect --disable-podpages --disable-asm --enable-avcodec --enable-avformat --enable-decoders --enable-encoders --enable-demuxers --enable-parsers --enable-protocol='file' --enable-swscale --enable-zlib
make
sudo make install
Add FFmpeg to your project Add FFmpeg to your project
-------------------------- --------------------------
@@ -30,7 +33,7 @@ Enable :c:macro:`LV_USE_FFMPEG` in ``lv_conf.h``.
See the examples below. See the examples below.
Note that, the FFmpeg extension doesn't use LVGL's file system. You can :Note: FFmpeg extension doesn't use LVGL's file system. You can
simply pass the path to the image or video as usual on your operating simply pass the path to the image or video as usual on your operating
system or platform. system or platform.

7
docs/libs/freetype.rst
View File

@@ -4,8 +4,9 @@
FreeType support FreeType support
================ ================
Interface to `FreeType <https://www.freetype.org/>`__ to generate font Interface to FreeType library to generate font bitmaps run time.
bitmaps run time.
Detailed introduction: https://www.freetype.org
Add FreeType to your project Add FreeType to your project
---------------------------- ----------------------------
@@ -19,7 +20,7 @@ For UNIX
For UNIX systems, it is recommended to use the way of compiling and installing libraries. For UNIX systems, it is recommended to use the way of compiling and installing libraries.
- Enter the FreeType source code directory. - Enter the FreeType source code directory
- ``make`` - ``make``
- ``sudo make install`` - ``sudo make install``
- Add include path: ``/usr/include/freetype2`` (for GCC: ``-I/usr/include/freetype2 -L/usr/local/lib``) - Add include path: ``/usr/include/freetype2`` (for GCC: ``-I/usr/include/freetype2 -L/usr/local/lib``)

6
docs/libs/fs.rst
View File

@@ -10,9 +10,9 @@ to provide an abstraction layer for various file system drivers.
LVG has built in support for: LVG has built in support for:
- `FATFS <http://elm-chan.org/fsw/ff/00index_e.html>`__ - `FATFS <http://elm-chan.org/fsw/ff/00index_e.html>`__
- STDIO (Linux and Windows using C standard function .e.g fopen, fread) - STDIO (Linux and Windows using C standard function .e.g ``fopen``, ``fread``)
- POSIX (Linux and Windows using POSIX function .e.g open, read) - POSIX (Linux and Windows using POSIX function .e.g ``open``, ``read``)
- WIN32 (Windows using Win32 API function .e.g CreateFileA, ReadFile) - WIN32 (Windows using Win32 API function .e.g ``CreateFileA``, ``ReadFile``)
- MEMFS (read a file from a memory buffer) - MEMFS (read a file from a memory buffer)
You still need to provide the drivers and libraries, this extension You still need to provide the drivers and libraries, this extension

2
docs/libs/gif.rst
View File

@@ -6,7 +6,7 @@ GIF decoder
Allow using GIF images in LVGL. Allow using GIF images in LVGL.
Detailed introduction: `GIFdec <https://github.com/lecram/gifdec>`__ Detailed introduction: https://github.com/lecram/gifdec
When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_GIF` When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_GIF`
:cpp:expr:`lv_gif_create(parent)` can be used to create a gif widget. :cpp:expr:`lv_gif_create(parent)` can be used to create a gif widget.

12
docs/libs/libjpeg_turbo.rst
View File

@@ -4,10 +4,12 @@
libjpeg-turbo decoder libjpeg-turbo decoder
===================== =====================
`libjpeg-turbo <https://libjpeg-turbo.org/>`__ is a JPEG image codec that uses SIMD instructions to accelerate baseline JPEG compression and decompression on x86, **libjpeg-turbo** is a JPEG image codec that uses SIMD instructions to accelerate baseline JPEG compression and decompression on x86,
x86-64, Arm, PowerPC, and MIPS systems, as well as progressive JPEG compression on x86, x86-64, and Arm systems. x86-64, Arm, PowerPC, and MIPS systems, as well as progressive JPEG compression on x86, x86-64, and Arm systems.
Detailed introduction: `libjpeg-turbo <https://github.com/libjpeg-turbo/libjpeg-turbo>`__ Detailed introduction: https://libjpeg-turbo.org
Library source: https://github.com/libjpeg-turbo/libjpeg-turbo
.. _libjpeg_install: .. _libjpeg_install:
@@ -18,7 +20,7 @@ Install
sudo apt install libjpeg-turbo8-dev sudo apt install libjpeg-turbo8-dev
Add libjpge-turbo to your project Add libjpeg-turbo to your project
--------------------------------- ---------------------------------
.. code:: cmake .. code:: cmake
@@ -32,11 +34,11 @@ Add libjpge-turbo to your project
Usage Usage
----- -----
Enable :c:macro:`LV_USE_LIBJEPG_TURBO` in ``lv_conf.h``. Enable :c:macro:`LV_USE_LIBJPEG_TURBO` in ``lv_conf.h``.
See the examples below. See the examples below.
It should be noted that each image of this decoder needs to consume ``image width x image height x 3`` bytes of RAM, It should be noted that each image of this decoder needs to consume ``image width x image height x 3`` bytes of RAM,
and it needs to be combined with the ref:`overview_image_caching` feature to ensure that the memory usage is within a reasonable range. and it needs to be combined with the :ref:`overview_image_caching` feature to ensure that the memory usage is within a reasonable range.
.. _libjpeg_example: .. _libjpeg_example:

2
docs/libs/libpng.rst
View File

@@ -6,7 +6,7 @@ libpng decoder
libpng is the official PNG reference library. It supports almost all PNG features, is extensible, and has been extensively tested for over 28 years. libpng is the official PNG reference library. It supports almost all PNG features, is extensible, and has been extensively tested for over 28 years.
Detailed introduction: `libpng <http://www.libpng.org/pub/png/libpng.html>`__ Detailed introduction: http://www.libpng.org/pub/png/libpng.html
Install Install
------- -------

11
docs/libs/lodepng.rst
View File

@@ -6,13 +6,13 @@ LodePNG decoder
Allow the use of PNG images in LVGL. Allow the use of PNG images in LVGL.
Detailed introduction: `lodepng <https://github.com/lvandeve/lodepng>`__ Detailed introduction: https://github.com/lvandeve/lodepng
If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_LODEPNG` LVGL will register a new If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_LODEPNG` LVGL will register a new
image decoder automatically so PNG files can be directly used as any image decoder automatically so PNG files can be directly used as any
other image sources. other image sources.
Note that, a file system driver needs to be registered to open images from :Note: a file system driver needs to be registered to open images from
files. Read more about it :ref:`overview_file_system` or just files. Read more about it :ref:`overview_file_system` or just
enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` enable one in ``lv_conf.h`` with ``LV_USE_FS_...``
@@ -31,11 +31,8 @@ the image by using 8-bit palette colors, instead of 24/32 bit True color format.
Because embedded devices have limited (flash) storage, it is recommended Because embedded devices have limited (flash) storage, it is recommended
to compress images. to compress images.
There is a very good and free online PNG compressor site, in which the number One option is to use a free online PNG compressor site,
of colors can be reduced, and in the same time preview the result. for example Compress PNG: https://compresspng.com/
A batch of PNG files can be uploaded also.
Compress PNG site: https://compresspng.com/
.. _lodepng_example: .. _lodepng_example:

2
docs/libs/rle.rst
View File

@@ -78,7 +78,7 @@ The RLE image can be used same as other images.
Generate RLE compressed binary images Generate RLE compressed binary images
------------------------------------- -------------------------------------
The image can be directly generated using script `lvgl/script/LVGLImage.py` The image can be directly generated using script ``lvgl/script/LVGLImage.py``
.. code:: bash .. code:: bash

9
docs/libs/rlottie.rst
View File

@@ -13,11 +13,12 @@ be built separately.
Build Rlottie Build Rlottie
------------- -------------
To build Samsung's Rlottie C++14-compatible compiler and optionally To build Samsung's Rlottie C++14 compatible compiler and optionally
CMake 3.14 or higher is required. CMake 3.14 or higher is required.
To build on desktop you can follow the instructions from Rlottie's To build on desktop you can follow the instructions from Rlottie's
`README <https://github.com/Samsung/rlottie/blob/master/README.md>`__. `README <https://github.com/Samsung/rlottie/blob/master/README.md>`__.
In the most basic case it looks like this: In the most basic case it looks like this:
.. code:: shell .. code:: shell
@@ -69,7 +70,7 @@ Use Rlottie from raw string data
format. Instead storing the JSON string, a hex array is stored for the format. Instead storing the JSON string, a hex array is stored for the
following reasons: following reasons:
- avoid escaping ``"`` in the JSON file - avoid escaping ``"`` character in the JSON file
- some compilers don't support very long strings - some compilers don't support very long strings
``lvgl/scripts/filetohex.py`` can be used to convert a Lottie file a hex ``lvgl/scripts/filetohex.py`` can be used to convert a Lottie file a hex
@@ -160,11 +161,11 @@ probably has minimal issues, but a 300 frame animation playing over 10
seconds could very easily crash due to lack of memory as rlottie seconds could very easily crash due to lack of memory as rlottie
renders, depending on the complexity of the animation. renders, depending on the complexity of the animation.
Rlottie will not compile for the IDF using the -02 compiler option at Rlottie will not compile for the IDF using the ``-02`` compiler option at
this time. this time.
For stability in lottie animations, I found that they run best in the For stability in lottie animations, I found that they run best in the
IDF when enabling :c:macro:`LV_MEM_CUSTOM` (using stdlib.h) IDF when enabling :c:macro:`LV_MEM_CUSTOM` (using ``stdlib.h``)
For all its faults, when running right-sized animations, they provide a For all its faults, when running right-sized animations, they provide a
wonderful utility to LVGL on embedded LCDs and can look really good when wonderful utility to LVGL on embedded LCDs and can look really good when

4
docs/libs/tiny_ttf.rst
View File

@@ -9,9 +9,9 @@ Tiny TTF font engine
Usage Usage
----- -----
Allow using TrueType fonts LVGL. Allow using TrueType fonts in LVGL.
Detailed introduction: `stb <https://github.com/nothings/stb>`__ Detailed introduction: https://github.com/nothings/stb
When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_TINY_TTF` When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_TINY_TTF`
:cpp:expr:`lv_tiny_ttf_create_data(data, data_size, font_size)` can be used to :cpp:expr:`lv_tiny_ttf_create_data(data, data_size, font_size)` can be used to

23
docs/libs/tjpgd.rst
View File

@@ -4,8 +4,7 @@
Tiny JPEG Decompressor (TJpgDec) Tiny JPEG Decompressor (TJpgDec)
================================ ================================
TJpgDec - Tiny JPEG Decompressor. Allow the use of JPEG (JPG) images in LVGL.
Allow the use of JPG (JPEG) images in LVGL.
Detailed introduction: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__ Detailed introduction: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__
@@ -14,10 +13,10 @@ Detailed introduction: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__
Overview Overview
-------- --------
- JPG is decoded in 8x8 tiles. - JPEG is decoded in 8x8 tiles.
- Only baseline JPG files are supported (no progressive JPG support). - Only baseline JPEG files are supported (no progressive JPEG support).
- Read from file and C array are implemented. - Read from file and C array are implemented.
- Only the required portions of the JPG images are decoded, - Only the required portions of the JPEG images are decoded,
therefore they can't be zoomed or rotated. therefore they can't be zoomed or rotated.
.. _tjpgd_usage: .. _tjpgd_usage:
@@ -26,21 +25,23 @@ Usage
----- -----
If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_TJPGD` LVGL will register a new If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_TJPGD` LVGL will register a new
image decoder automatically so JPG files can be used directly image decoder automatically so JPEG files can be used directly
as image sources. For example: as image sources.
For example:
.. code:: c .. code:: c
lv_image_set_src(my_img, "S:path/to/picture.jpg"); lv_image_set_src(my_img, "S:path/to/picture.jpg");
Note that a file system driver needs to be registered to open images from :Note: a file system driver needs to be registered to open images from
files. Read more about it :ref:`overview_file_system` or just files. Read more about :ref:`overview_file_system` or just
enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` config.
Converter Converter
--------- ---------
Converting JPG to C array Converting JPEG to C array
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
- Use lvgl online tool https://lvgl.io/tools/imageconverter - Use lvgl online tool https://lvgl.io/tools/imageconverter

8
docs/others/file_explorer.rst
View File

@@ -59,7 +59,9 @@ Sort
You can use You can use
:cpp:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` to set :cpp:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` to set
sorting method. There are the following sorting methods: sorting method.
There are the following sorting methods:
- :cpp:enumerator:`LV_EXPLORER_SORT_NONE` - :cpp:enumerator:`LV_EXPLORER_SORT_NONE`
- :cpp:enumerator:`LV_EXPLORER_SORT_KIND` - :cpp:enumerator:`LV_EXPLORER_SORT_KIND`
@@ -73,9 +75,9 @@ default sorting to :cpp:enumerator:`LV_EXPLORER_SORT_NONE`. The default is
Events Events
------ ------
- :cpp:enumerator:`LV_EVENT_READY` sent when a directory is opened. You can customize - :cpp:enumerator:`LV_EVENT_READY` Sent when a directory is opened. You can customize
the sort. the sort.
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when an item(file) in the file list - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when an item (file) in the file list
is clicked. is clicked.
You can use :cpp:func:`lv_file_explorer_get_cur_path` to get the current path You can use :cpp:func:`lv_file_explorer_get_cur_path` to get the current path

8
docs/others/gridnav.rst
View File

@@ -13,15 +13,15 @@ respective direction.
It doesn't matter how the children are positioned, as only the current x It doesn't matter how the children are positioned, as only the current x
and y coordinates are considered. This means that gridnav works with and y coordinates are considered. This means that gridnav works with
manually positioned children, as well as `Flex </layouts/flex>`__ and manually positioned children, as well as :ref:`flex` and
`Grid </layouts/grid>`__ layouts. :ref:`grid` layouts.
Gridnav also works if the children are arranged into a single row or Gridnav also works if the children are arranged into a single row or
column. That makes it useful, for example, to simplify navigation on a column. That makes it useful, for example, to simplify navigation on a
`List widget </widgets/list>`__. :ref:`List widget <lv_list>`.
Gridnav assumes that the object to which gridnav is added is part of a Gridnav assumes that the object to which gridnav is added is part of a
`group </overview/indev.html#groups>`__. This way, if the object with :ref:`group <indev_groups>`. This way, if the object with
gridnav is focused, the arrow key presses are automatically forwarded to gridnav is focused, the arrow key presses are automatically forwarded to
the object so that gridnav can process the arrow keys. the object so that gridnav can process the arrow keys.

10
docs/others/imgfont.rst
View File

@@ -1,13 +1,13 @@
.. _lv_imgfont: .. _lv_imgfont:
======================= ==========
Image font (lv_imgfont) Image font
======================= ==========
Draw image in label or span obj with :cpp:type:`lv_imgfont`. This is often used to Draw image in **label** or **span** obj with :cpp:type:`lv_imgfont`. This is often used to
display Unicode emoji icons in text. display Unicode emoji icons in text.
Supported image formats: determined by enabled LVGL image decoders. Supported image formats: determined by enabled LVGL :ref:`image decoders <overview_image_decoder>`.
.. _lv_imgfont_usage: .. _lv_imgfont_usage:

5
docs/others/obj_id.rst
View File

@@ -26,8 +26,9 @@ to get a string representation of the ID.
Use custom ID generator Use custom ID generator
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
Set :c:macro:`LV_USE_OBJ_ID_BUILTIN` to `0` in ``lv_conf.h``. Below APIs needed to be implemented and Set :c:macro:`LV_USE_OBJ_ID_BUILTIN` to `0` in ``lv_conf.h``.
linked to lvgl.
Below APIs needed to be implemented and linked to lvgl.
.. code:: c .. code:: c

8
docs/others/observer.rst
View File

@@ -11,7 +11,7 @@ Overview
The ``lv_observer`` module implements a standard `Observer pattern <https://en.wikipedia.org/wiki/Observer_pattern>`__. The ``lv_observer`` module implements a standard `Observer pattern <https://en.wikipedia.org/wiki/Observer_pattern>`__.
It consists of It consists of:
- **subjects**: each containing a value - **subjects**: each containing a value
- **observers**: attached to subjects to be notified on value change - **observers**: attached to subjects to be notified on value change
@@ -78,7 +78,7 @@ Subject
Subject initialization Subject initialization
---------------------- ----------------------
Subjects have to be static or global :cpp:expr:`lv_subject_t` type variables. Subjects have to be static or global :cpp:type:`lv_subject_t` type variables.
To initialize a subject use :cpp:expr:`lv_subject_init_<type>(&subject, params, init_value)`. To initialize a subject use :cpp:expr:`lv_subject_init_<type>(&subject, params, init_value)`.
The following initializations exist for types: The following initializations exist for types:
@@ -285,8 +285,8 @@ Label
----- -----
Bind an integer, string, or pointer (pointing to a string) subject to a label. Bind an integer, string, or pointer (pointing to a string) subject to a label.
An optional format string can be added with 1 format specifier (e.g. "%d °C") An optional format string can be added with 1 format specifier (e.g. ``"%d °C"``)
If the format string is NULL the value will be used directly. In this case on string and pointer type subjects can be used. If the format string is ``NULL`` the value will be used directly. In this case on string and pointer type subjects can be used.
.. code:: c .. code:: c

2
docs/overview/coord.rst
View File

@@ -88,7 +88,7 @@ the screen of ``obj``.
Removing styles Removing styles
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
As it's described in the `Using styles <#using-styles>`__ section, As it's described in the :ref:`coord_using_styles` section,
coordinates can also be set via style properties. To be more precise, coordinates can also be set via style properties. To be more precise,
under the hood every style coordinate related property is stored as a 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`` style property. If you use :cpp:expr:`lv_obj_set_x(obj, 20)` LVGL saves ``x=20``

2
docs/overview/display.rst
View File

@@ -86,7 +86,7 @@ types are :ref:`Base object <lv_obj>` and :ref:`Image <lv_image>`
(to create a wallpaper). (to create a wallpaper).
To create a screen, use To create a screen, use
``lv_obj_t * scr = lv_<type>_create(NULL)``. `NULL` indicates no parent. :cpp:expr:`lv_obj_t * scr = lv_<type>_create(NULL)`. ``NULL`` indicates no parent.
To load a screen, use :cpp:expr:`lv_screen_load(scr)`. To get the active screen, To load a screen, use :cpp:expr:`lv_screen_load(scr)`. To get the active screen,
use :cpp:expr:`lv_screen_active()`. These functions work on the default display. If use :cpp:expr:`lv_screen_active()`. These functions work on the default display. If

17
docs/overview/event.rst
View File

@@ -33,7 +33,7 @@ In practice, it looks like this:
} }
In the example :cpp:enumerator:`LV_EVENT_CLICKED` means that only the click event will In the example :cpp:enumerator:`LV_EVENT_CLICKED` means that only the click event will
call ``my_event_cb``. See the `list of event codes <#event-codes>`__ for 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. 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 The last parameter of :cpp:func:`lv_obj_add_event` is a pointer to any custom
@@ -83,6 +83,7 @@ Remove event(s) from widgets
} }
} }
.. _events_codes:
Event codes Event codes
*********** ***********
@@ -114,11 +115,11 @@ Input device events
- :cpp:enumerator:`LV_EVENT_CLICKED`: Called on release if not scrolled (regardless to long press) - :cpp:enumerator:`LV_EVENT_CLICKED`: Called on release if not scrolled (regardless to 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 the object 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_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_THROW_BEGIN`:
- :cpp:enumerator:`LV_EVENT_SCROLL_END`: Scrolling ends - :cpp:enumerator:`LV_EVENT_SCROLL_END`: Scrolling ends
- :cpp:enumerator:`LV_EVENT_SCROLL`: Scrolling - :cpp:enumerator:`LV_EVENT_SCROLL`: Scrolling
- :cpp:enumerator:`LV_EVENT_GESTURE`: A gesture is detected. Get the gesture with `lv_indev_get_gesture_dir(lv_indev_active());` - :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 `lv_indev_get_key(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_FOCUSED`: The object is focused
- :cpp:enumerator:`LV_EVENT_DEFOCUSED`: The object is defocused - :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_LEAVE`: The object is defocused but still selected
@@ -128,8 +129,8 @@ Input device events
Drawing events Drawing events
-------------- --------------
- :cpp:enumerator:`LV_EVENT_COVER_CHECK`: Check if the object fully covers an area. The event parameter is `lv_cover_check_info_t *`. - :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 `int32_t *` to store the size. - :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_DRAW_MAIN_BEGIN`: Starting the main drawing phase - :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`: Perform the main drawing
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_END`: Finishing the main drawing phase - :cpp:enumerator:`LV_EVENT_DRAW_MAIN_END`: Finishing the main drawing phase
@@ -226,10 +227,12 @@ 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_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_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 `event bubbling <#event-bubbling>`__ is enabled) - :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 <events_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_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_event_send` - :cpp:expr:`lv_event_get_param(e)`: get the parameter passed as the last parameter of :cpp:func:`lv_event_send`
.. _events_bubbling:
Event bubbling Event bubbling
************** **************

4
docs/overview/font.rst
View File

@@ -75,7 +75,7 @@ bullet symbol (U+2022) and the built-in symbols (see below).
Special fonts Special fonts
------------- -------------
- :c:macro:`LV_FONT_MONTSERRAT_28_COMPRESSED`: Same as normal 28 px font but stored as a `compressed font <#compress-fonts>`__ with 3 bpp - :c:macro:`LV_FONT_MONTSERRAT_28_COMPRESSED`: Same as normal 28 px font but stored as a :ref:`fonts_compressed` with 3 bpp
- :c:macro:`LV_FONT_DEJAVU_16_PERSIAN_HEBREW`: 16 px font with normal range + Hebrew, Arabic, Persian letters and all their forms - :c:macro:`LV_FONT_DEJAVU_16_PERSIAN_HEBREW`: 16 px font with normal range + Hebrew, Arabic, Persian letters and all their forms
- :c:macro:`LV_FONT_SIMSUN_16_CJK`: 16 px font with normal range plus 1000 of the most common CJK radicals - :c:macro:`LV_FONT_SIMSUN_16_CJK`: 16 px font with normal range plus 1000 of the most common CJK radicals
- :c:macro:`LV_FONT_UNSCII_8`: 8 px pixel perfect font with only ASCII characters - :c:macro:`LV_FONT_UNSCII_8`: 8 px pixel perfect font with only ASCII characters
@@ -199,6 +199,8 @@ match with the library settings. By default, LVGL assumes ``RGB`` order,
however this can be swapped by setting :c:macro:`LV_SUBPX_BGR` ``1`` in however this can be swapped by setting :c:macro:`LV_SUBPX_BGR` ``1`` in
*lv_conf.h*. *lv_conf.h*.
.. _fonts_compressed:
Compressed fonts Compressed fonts
---------------- ----------------

14
docs/overview/image.rst
View File

@@ -15,6 +15,8 @@ You can store images in two places
- as a variable in internal memory (RAM or ROM) - as a variable in internal memory (RAM or ROM)
- as a file - as a file
.. _overview_image_variables:
Variables Variables
--------- ---------
@@ -23,7 +25,7 @@ Images stored internally in a variable are composed mainly of an
- **header**: - **header**:
- *cf*: Color format. See `below <#color-format>`__ - *cf*: Color format. See :ref:`below <overview_image_color_formats>`
- *w*: width in pixels (<= 2048) - *w*: width in pixels (<= 2048)
- *h*: height in pixels (<= 2048) - *h*: height in pixels (<= 2048)
- *always zero*: 3 bits which need to be always zero - *always zero*: 3 bits which need to be always zero
@@ -34,6 +36,8 @@ Images stored internally in a variable are composed mainly of an
These are usually stored within a project as C files. They are linked These are usually stored within a project as C files. They are linked
into the resulting executable like any other constant data. into the resulting executable like any other constant data.
.. _overview_image_files:
Files Files
----- -----
@@ -107,9 +111,9 @@ Adding an image to LVGL via the online converter is easy.
1. You need to select a *BMP*, *PNG* or *JPG* image first. 1. You need to select a *BMP*, *PNG* or *JPG* image first.
2. Give the image a name that will be used within LVGL. 2. Give the image a name that will be used within LVGL.
3. Select the `Color format <#color-formats>`__. 3. Select the :ref:`Color format <overview_image_color_formats>`.
4. Select the type of image you want. Choosing a binary will generate a 4. Select the type of image you want. Choosing a binary will generate a
``.bin`` file that must be stored separately and read using the `file support <#files>`__. ``.bin`` file that must be stored separately and read using the :ref:`file support <overview_image_files>`.
Choosing a variable will generate a standard C file that can be linked into your project. Choosing a variable will generate a standard C file that can be linked into your project.
5. Hit the *Convert* button. Once the conversion is finished, your 5. Hit the *Convert* button. Once the conversion is finished, your
browser will automatically download the resulting file. browser will automatically download the resulting file.
@@ -174,7 +178,7 @@ you want to use it.
Image decoder Image decoder
************* *************
As you can see in the `Color formats <#color-formats>`__ section, LVGL As you can see in the :ref:`overview_image_color_formats` section, LVGL
supports several built-in image formats. In many cases, these will be supports several built-in image formats. In many cases, these will be
all you need. LVGL doesn't directly support, however, generic image all you need. LVGL doesn't directly support, however, generic image
formats like PNG or JPG. formats like PNG or JPG.
@@ -223,7 +227,7 @@ a fully opaque image, using an alpha channel.
After decoding, the *raw* formats are considered *True color* by the After decoding, the *raw* formats are considered *True color* by the
library. In other words, the image decoder must decode the *Raw* images library. In other words, the image decoder must decode the *Raw* images
to *True color* according to the format described in the `Color formats <#color-formats>`__ section. to *True color* according to the format described in the :ref:`overview_image_color_formats` section.
Register an image decoder Register an image decoder

16
docs/overview/indev.rst
View File

@@ -134,15 +134,15 @@ There are some predefined keys which have special meaning:
- :cpp:enumerator:`LV_KEY_HOME`: Go to the beginning/top (E.g. in a :ref:`Text area <lv_textarea>`) - :cpp:enumerator:`LV_KEY_HOME`: Go to the beginning/top (E.g. in a :ref:`Text area <lv_textarea>`)
- :cpp:enumerator:`LV_KEY_END`: Go to the end (E.g. in a :ref:`Text area <lv_textarea>`) - :cpp:enumerator:`LV_KEY_END`: Go to the end (E.g. in a :ref:`Text area <lv_textarea>`)
The most important special keys In your ``read_cb`` function The most important special keys in your :cpp:func:`read_cb` function are:
- :cpp:enumerator:`LV_KEY_NEXT` - :cpp:enumerator:`LV_KEY_NEXT`
- :cpp:enumerator:`LV_KEY_PREV` - :cpp:enumerator:`LV_KEY_PREV`
- :cpp:enumerator:`LV_KEY_ENTER`, - :cpp:enumerator:`LV_KEY_ENTER`
- :cpp:enumerator:`LV_KEY_UP`, - :cpp:enumerator:`LV_KEY_UP`
- :cpp:enumerator:`LV_KEY_DOWN`, - :cpp:enumerator:`LV_KEY_DOWN`
- :cpp:enumerator:`LV_KEY_LEFT` - :cpp:enumerator:`LV_KEY_LEFT`
- :cpp:enumerator:`LV_KEY_RIGHT` - :cpp:enumerator:`LV_KEY_RIGHT`
You should translate some of your keys to these special keys to support navigation You should translate some of your keys to these special keys to support navigation
in a group and interact with selected objects. in a group and interact with selected objects.

4
docs/overview/style-props.rst
View File

@@ -1849,7 +1849,7 @@ bg_grad
~~~~~~~ ~~~~~~~
Set the gradient definition. The pointed instance must exist while the Set the gradient definition. The pointed instance must exist while the
object is alive. NULL to disable. It wraps :cpp:enumerator:`BG_GRAD_COLOR`, object is alive. ``NULL`` to disable. It wraps :cpp:enumerator:`BG_GRAD_COLOR`,
:cpp:enumerator:`BG_GRAD_DIR`, :cpp:enumerator:`BG_MAIN_STOP` and :cpp:enumerator:`BG_GRAD_STOP` into one :cpp:enumerator:`BG_GRAD_DIR`, :cpp:enumerator:`BG_MAIN_STOP` and :cpp:enumerator:`BG_GRAD_STOP` into one
descriptor and allows creating gradients with more colors too. descriptor and allows creating gradients with more colors too.
@@ -2746,7 +2746,7 @@ Properties to describe the shadow drawn under the rectangles.
shadow_width shadow_width
~~~~~~~~~~~~ ~~~~~~~~~~~~
Set the width of the shadow in pixels. The value should be >= 0. Set the width of the shadow in pixels. The value should be ``>= 0``.
.. raw:: html .. raw:: html

2
docs/porting/draw.rst
View File

@@ -1,3 +1,5 @@
.. _porting_draw:
========== ==========
Custom GPU Custom GPU
========== ==========

2
docs/widgets/animimg.rst
View File

@@ -64,5 +64,3 @@ Example
API API
*** ***
:ref:`lv_animimg`

4
docs/widgets/arc.rst
View File

@@ -157,7 +157,7 @@ Events
- ``draw_area``: the area of the knob - ``draw_area``: the area of the knob
- ``rect_dsc``: - ``rect_dsc``:
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.
@@ -182,5 +182,3 @@ Example
API API
*** ***
:ref:`lv_arc`

4
docs/widgets/bar.rst
View File

@@ -63,7 +63,7 @@ The bar can be one of the following modes:
Events Events
****** ******
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.
@@ -87,5 +87,3 @@ Example
API API
*** ***
:ref:`lv_bar`

2
docs/widgets/button.rst
View File

@@ -7,7 +7,7 @@ Button (lv_button)
Overview Overview
******** ********
Buttons have no new features compared to the :ref:`Base object <lv_obj>`__. They are useful for semantic purposes and have Buttons have no new features compared to the :ref:`Base object <lv_obj>`. They are useful for semantic purposes and have
slightly different default settings. slightly different default settings.
Buttons, by default, differ from Base object in the following ways: - Buttons, by default, differ from Base object in the following ways: -

19
docs/widgets/buttonmatrix.rst
View File

@@ -40,7 +40,7 @@ Button's text
There is a text on each button. To specify them a descriptor string There is a text on each button. To specify them a descriptor string
array, called *map*, needs to be used. The map can be set with array, called *map*, needs to be used. The map can be set with
:cpp:expr:`lv_buttonmatrix_set_map(buttonm, my_map)`. The declaration of a map should :cpp:expr:`lv_buttonmatrix_set_map(buttonm, my_map)`. The declaration of a map should
look like ``const char * map[] = {"button1", "button2", "button3", NULL}``. Note look like :cpp:expr:`const char * map[] = {"button1", "button2", "button3", NULL}`. Note
that the last element has to be either ``NULL`` or an empty string that the last element has to be either ``NULL`` or an empty string
(``""``)! (``""``)!
@@ -58,7 +58,7 @@ row with :cpp:expr:`lv_buttonmatrix_set_button_width(buttonm, button_id, width)`
line with two buttons: *buttonA, width = 1* and *buttonB, width = 2*, *buttonA* line with two buttons: *buttonA, width = 1* and *buttonB, width = 2*, *buttonA*
will have 33 % width and *buttonB* will have 66 % width. It's similar to will have 33 % width and *buttonB* will have 66 % width. It's similar to
how the how the
```flex-grow`` <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow>`__ `"flex-grow" <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow>`__
property works in CSS. The width must be in the [1..15] range and the property works in CSS. The width must be in the [1..15] range and the
default width is 1. default width is 1.
@@ -72,25 +72,24 @@ following parameters:
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CHECKED`: Make the button checked. It will use the :cpp:enumerator:`LV_STATE_CHECHKED` styles. - :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CHECKED`: Make the button checked. It will use the :cpp:enumerator:`LV_STATE_CHECHKED` styles.
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CLICK_TRIG`: Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send :cpp:enumerator:`LV_EVENT_VALUE_CHANGE` on PRESS - :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CLICK_TRIG`: Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send :cpp:enumerator:`LV_EVENT_VALUE_CHANGE` on PRESS
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER`: Show the button label in a popover when pressing this key - :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER`: Show the button label in a popover when pressing this key
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_RECOLOR`: Enable recoloring of button texts with ``#``. E.g. ``"It's #ff0000 red#"``
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CUSTOM_1`: Custom free to use flag - :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CUSTOM_1`: Custom free to use flag
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CUSTOM_2`: Custom free to use flag - :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CUSTOM_2`: Custom free to use flag
By default, all flags are disabled. By default, all flags are disabled.
To set or clear a button's control attribute, use To set or clear a button's control attribute, use
``lv_buttonmatrix_set_button_ctrl(buttonm, button_id, LV_BUTTONMATRIX_CTRL_...)`` and :cpp:expr:`lv_buttonmatrix_set_button_ctrl(buttonm, button_id, LV_BUTTONMATRIX_CTRL_...)` and
``lv_buttonmatrix_clear_button_ctrl(buttonm, button_id, LV_BUTTONMATRIX_CTRL_...)`` :cpp:expr:`lv_buttonmatrix_clear_button_ctrl(buttonm, button_id, LV_BUTTONMATRIX_CTRL_...)`
respectively. More ``LV_BUTTONMATRIX_CTRL_...`` values can be OR-ed respectively. More ``LV_BUTTONMATRIX_CTRL_...`` values can be OR-ed
To set/clear the same control attribute for all buttons of a button To set/clear the same control attribute for all buttons of a button
matrix, use ``lv_buttonmatrix_set_button_ctrl_all(buttonm, LV_BUTTONMATRIX_CTRL_...)`` matrix, use :cpp:expr:`lv_buttonmatrix_set_button_ctrl_all(buttonm, LV_BUTTONMATRIX_CTRL_...)`
and ``lv_buttonmatrix_clear_button_ctrl_all(buttonm, LV_BUTTONMATRIX_CTRL_...)``. and :cpp:expr:`lv_buttonmatrix_clear_button_ctrl_all(buttonm, LV_BUTTONMATRIX_CTRL_...)`.
The set a control map for a button matrix (similarly to the map for the The set a control map for a button matrix (similarly to the map for the
text), use ``lv_buttonmatrix_set_ctrl_map(buttonm, ctrl_map)``. An element of text), use :cpp:expr:`lv_buttonmatrix_set_ctrl_map(buttonm, ctrl_map)`. An element of
``ctrl_map`` should look like ``ctrl_map`` should look like
``ctrl_map[0] = width | LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_CHECHKABLE``. :cpp:expr:`ctrl_map[0] = width | LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_CHECHKABLE`.
The number of elements should be equal to the number of buttons The number of elements should be equal to the number of buttons
(excluding newlines characters). (excluding newlines characters).
@@ -110,7 +109,7 @@ Events
repeated after long press. The event parameter is set to the ID of repeated after long press. The event parameter is set to the ID of
the pressed/released button. the pressed/released button.
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
:cpp:expr:`lv_buttonmatrix_get_selected_button(buttonm)` returns the index of the most :cpp:expr:`lv_buttonmatrix_get_selected_button(buttonm)` returns the index of the most
recently released or focused button or :cpp:enumerator:`LV_BUTTONMATRIX_BUTTON_NONE` if no recently released or focused button or :cpp:enumerator:`LV_BUTTONMATRIX_BUTTON_NONE` if no

2
docs/widgets/canvas.rst
View File

@@ -16,7 +16,7 @@ lvgl's drawing engine.
Parts and Styles Parts and Styles
**************** ****************
:cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle style properties and image - :cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle style properties and image
style properties. style properties.
.. _lv_canvas_usage: .. _lv_canvas_usage:

16
docs/widgets/chart.rst
View File

@@ -25,7 +25,7 @@ Parts and Styles
charts ``pad_column`` sets the space between the columns of the charts ``pad_column`` sets the space between the columns of the
adjacent indices. adjacent indices.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar used if the chart is zoomed. See - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar used if the chart is zoomed. See
the `Base object </widgets/obj>`__\ 's documentation for details. the :ref:`Base object <lv_obj>`\ 's documentation for details.
- :cpp:enumerator:`LV_PART_ITEMS` Refers to the line or bar series. - :cpp:enumerator:`LV_PART_ITEMS` Refers to the line or bar series.
- Line chart: The *line* properties are used by the lines. - Line chart: The *line* properties are used by the lines.
@@ -51,8 +51,8 @@ Chart type
The following data display types exist: The following data display types exist:
- :cpp:enumerator:`LV_CHART_TYPE_NONE`: Do not display any data. Can be used to hide the series. - :cpp:enumerator:`LV_CHART_TYPE_NONE`: Do not display any data. Can be used to hide the series.
- :cpp:enumerator:`LV_CHART_TYPE_LINE`: Draw lines between the data points and/or points (rectangles or circles) on the data points. - :cpp:enumerator:`LV_CHART_TYPE_LINE`: Draw lines between the data points and/or points (rectangles or circles) on the data points.
- :cpp:enumerator:`LV_CHART_TYPE_BAR`: Draw bars. - :cpp:enumerator:`LV_CHART_TYPE_BAR`: Draw bars.
- :cpp:enumerator:`LV_CHART_TYPE_SCATTER`: X/Y chart drawing point's and lines between the points. . - :cpp:enumerator:`LV_CHART_TYPE_SCATTER`: X/Y chart drawing point's and lines between the points. .
@@ -67,10 +67,10 @@ You can add any number of series to the charts by
:cpp:struct:`lv_chart_series_t` structure which contains the chosen ``color`` and :cpp:struct:`lv_chart_series_t` structure which contains the chosen ``color`` and
an array for the data points. ``axis`` can have the following values: an array for the data points. ``axis`` can have the following values:
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_Y` Left axis - :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_Y`: Left axis
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_Y` Right axis - :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_Y`: Right axis
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_X` Bottom axis - :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_X`: Bottom axis
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_X` Top axis - :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_X`: Top axis
``axis`` tells which axis's range should be used to scale the values. ``axis`` tells which axis's range should be used to scale the values.
@@ -211,7 +211,7 @@ Events
:cpp:expr:`lv_chart_get_pressed_point(chart)` returns the zero-based index of :cpp:expr:`lv_chart_get_pressed_point(chart)` returns the zero-based index of
the pressed point. the pressed point.
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

2
docs/widgets/checkbox.rst
View File

@@ -63,7 +63,7 @@ Events
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled. - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled.
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

2
docs/widgets/dropdown.rst
View File

@@ -143,7 +143,7 @@ the drop-down list:
- :cpp:enumerator:`LV_EVENT_CANCEL` Sent when the list is closed - :cpp:enumerator:`LV_EVENT_CANCEL` Sent when the list is closed
- :cpp:enumerator:`LV_EVENT_READY` Sent when the list is opened - :cpp:enumerator:`LV_EVENT_READY` Sent when the list is opened
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

44
docs/widgets/image.rst
View File

@@ -41,7 +41,7 @@ To set the source of an image, use :cpp:expr:`lv_image_set_src(img, src)`.
To generate a pixel array from a PNG, JPG or BMP image, use the `Online image converter tool <https://lvgl.io/tools/imageconverter>`__ To generate a pixel array from a PNG, JPG or BMP image, use the `Online image converter tool <https://lvgl.io/tools/imageconverter>`__
and set the converted image with its pointer :cpp:expr:`lv_image_set_src(img1, &converted_img_var)` and set the converted image with its pointer :cpp:expr:`lv_image_set_src(img1, &converted_img_var)`
To make the variable visible in the C file, you need to declare it with To make the variable visible in the C file, you need to declare it with
:cpp:expr:`LV_IMAGE_DECLARE(converted_img_var)`. :cpp:macro:`LV_IMAGE_DECLARE(converted_img_var)`.
To use external files, you also need to convert the image files using To use external files, you also need to convert the image files using
the online converter tool but now you should select the binary output the online converter tool but now you should select the binary output
@@ -71,7 +71,7 @@ Transparency
The internal (variable) and external images support 2 transparency The internal (variable) and external images support 2 transparency
handling methods: handling methods:
- **Alpha byte** - An alpha byte is added to every pixel that contains - **Alpha byte**: An alpha byte is added to every pixel that contains
the pixel's opacity the pixel's opacity
Palette and Alpha index Palette and Alpha index
@@ -135,11 +135,11 @@ the transformations are higher quality but slower.
The transformations require the whole image to be available. Therefore The transformations require the whole image to be available. Therefore
indexed images (``LV_COLOR_FORMAT_I1/2/4/8_...``), alpha only images cannot be transformed. indexed images (``LV_COLOR_FORMAT_I1/2/4/8_...``), alpha only images cannot be transformed.
In other words transformations work only on normal (A)RGB or A8 images stored as In other words transformations work only on normal (A)RGB or A8 images stored as
C array, or if a custom :ref:`Image decoder <overview_image_decoder>` C array, or if a custom :ref:`overview_image_decoder`
returns the whole image. returns the whole image.
Note that the real coordinates of image objects won't change during Note that the real coordinates of image objects won't change during
transformation. That is ``lv_obj_get_width/height/x/y()`` will return transformation. That is :cpp:expr:`lv_obj_get_width/height/x/y()` will return
the original, non-zoomed coordinates. the original, non-zoomed coordinates.
**IMPORTANT** The transformation of the image is independent of the **IMPORTANT** The transformation of the image is independent of the
@@ -153,31 +153,35 @@ differences are that pure image widget transformation
Align Align
----- -----
By default the image widget's width and height is :cpp:expr:`LV_SIZE_CONTENT`. By default the image widget's width and height is :cpp:enumerator:`LV_SIZE_CONTENT`.
It means the the widget will be sized automatically according to the image source. It means the the widget will be sized automatically according to the image source.
If the widget's width or height is set the smaller value the ``align`` property tells If the widget's width or height is set the smaller value the ``align`` property tells
how to align the image source inside the widget. The alignment set any of these: how to align the image source inside the widget.
- :cpp:expr:`LV_IMAGE_ALIGN_DEFAULT` Meaning top left The alignment set any of these:
- :cpp:expr:`LV_IMAGE_ALIGN_TOP_LEFT`
- :cpp:expr:`LV_IMAGE_ALIGN_TOP_MID`
- :cpp:expr:`LV_IMAGE_ALIGN_TOP_RIGHT`
- :cpp:expr:`LV_IMAGE_ALIGN_BOTTOM_LEFT`
- :cpp:expr:`LV_IMAGE_ALIGN_BOTTOM_MID`
- :cpp:expr:`LV_IMAGE_ALIGN_BOTTOM_RIGHT`
- :cpp:expr:`LV_IMAGE_ALIGN_LEFT_MID`
- :cpp:expr:`LV_IMAGE_ALIGN_RIGHT_MID`
- :cpp:expr:`LV_IMAGE_ALIGN_CENTER`
The ``offset`` value is applied after the image source is aligned. For example setting an ``y=-10`` and :cpp:expr:`LV_IMAGE_ALIGN_CENTER` - :cpp:enumerator:`LV_IMAGE_ALIGN_DEFAULT`: Meaning top left
- :cpp:enumerator:`LV_IMAGE_ALIGN_TOP_LEFT`
- :cpp:enumerator:`LV_IMAGE_ALIGN_TOP_MID`
- :cpp:enumerator:`LV_IMAGE_ALIGN_TOP_RIGHT`
- :cpp:enumerator:`LV_IMAGE_ALIGN_BOTTOM_LEFT`
- :cpp:enumerator:`LV_IMAGE_ALIGN_BOTTOM_MID`
- :cpp:enumerator:`LV_IMAGE_ALIGN_BOTTOM_RIGHT`
- :cpp:enumerator:`LV_IMAGE_ALIGN_LEFT_MID`
- :cpp:enumerator:`LV_IMAGE_ALIGN_RIGHT_MID`
- :cpp:enumerator:`LV_IMAGE_ALIGN_CENTER`
- :cpp:enumerator:`LV_IMAGE_ALIGN_STRETCH`
- :cpp:enumerator:`LV_IMAGE_ALIGN_TILE`
The ``offset`` value is applied after the image source is aligned. For example setting an ``y=-10`` and :cpp:enumerator:`LV_IMAGE_ALIGN_CENTER`
will move the image source up a little bit from the center of the widget. will move the image source up a little bit from the center of the widget.
Or to automatically scale or tile the image Or to automatically scale or tile the image
- :cpp:expr:`LV_IMAGE_ALIGN_STRETCH` Set X and Y scale to fill the widget's area - :cpp:enumerator:`LV_IMAGE_ALIGN_STRETCH` Set X and Y scale to fill the widget's area
- :cpp:expr:`LV_IMAGE_ALIGN_TILE` Tile the image to will the widget area. Offset is applied to shift the tiling. - :cpp:enumerator:`LV_IMAGE_ALIGN_TILE` Tile the image to will the widget area. Offset is applied to shift the tiling.
The alignment can be set by :cpp:func:`lv_image_set_align(image, align)` The alignment can be set by :cpp:func:`lv_image_set_align`
.. _lv_image_events: .. _lv_image_events:

2
docs/widgets/imagebutton.rst
View File

@@ -53,7 +53,7 @@ they will be used in pressed state instead of the released images.
States States
------ ------
Instead of the regular :cpp:func:`lv_obj_add_state`and :cpp:func:`lv_obj_remove_state` functions, Instead of the regular :cpp:func:`lv_obj_add_state` and :cpp:func:`lv_obj_remove_state` functions,
the :cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` function should be the :cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` function should be
used to manually set a state. used to manually set a state.

8
docs/widgets/keyboard.rst
View File

@@ -78,15 +78,15 @@ creating new maps and ctrls.
Keep in mind that using following keywords will have the same effect as Keep in mind that using following keywords will have the same effect as
with the original map: with the original map:
- :c:macro:`LV_SYMBOL_OK` Send ``LV_EVENT_READY`` to the assigned Text area. - :c:macro:`LV_SYMBOL_OK` Send :cpp:enumerator:`LV_EVENT_READY` to the assigned Text area.
- :c:macro:`LV_SYMBOL_CLOSE` or :c:macro:`LV_SYMBOL_KEYBOARD` Send :cpp:enumerator:`LV_EVENT_CANCEL` to the assigned Text area. - :c:macro:`LV_SYMBOL_CLOSE` or :c:macro:`LV_SYMBOL_KEYBOARD` Send :cpp:enumerator:`LV_EVENT_CANCEL` to the assigned Text area.
- :c:macro:`LV_SYMBOL_BACKSPACE` Delete on the left. - :c:macro:`LV_SYMBOL_BACKSPACE` Delete on the left.
- :c:macro:`LV_SYMBOL_LEFT` Move the cursor left. - :c:macro:`LV_SYMBOL_LEFT` Move the cursor left.
- :c:macro:`LV_SYMBOL_RIGHT` Move the cursor right. - :c:macro:`LV_SYMBOL_RIGHT` Move the cursor right.
- :c:macro:`LV_SYMBOL_NEW_LINE` New line. - :c:macro:`LV_SYMBOL_NEW_LINE` New line.
- *"ABC"* Load the uppercase map. - ``"ABC"`` Load the uppercase map.
- *"abc"* Load the lower case map. - ``"abc"`` Load the lower case map.
- *"1#"* Load the lower case map. - ``"1#"`` Load the lower case map.
.. _lv_keyboard_events: .. _lv_keyboard_events:

8
docs/widgets/label.rst
View File

@@ -14,13 +14,13 @@ A label is the basic object type that is used to display text.
Parts and Styles Parts and Styles
**************** ****************
- :cpp:enumerator:`LV_PART_MAIN` Uses all the typical background properties and the - :cpp:enumerator:`LV_PART_MAIN` Uses all the typical background properties and the
text properties. The padding values can be used to add space between text properties. The padding values can be used to add space between
the text and the background. the text and the background.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
larger than the widget's size. larger than the widget's size.
- :cpp:enumerator:`LV_PART_SELECTED` Tells the style of the `selected - :cpp:enumerator:`LV_PART_SELECTED` Tells the style of the
text <#text-selection>`__. Only ``text_color`` and ``bg_color`` style :ref:`selected text <lv_label_text_selection>`. Only ``text_color`` and ``bg_color`` style
properties can be used. properties can be used.
.. _lv_label_usage: .. _lv_label_usage:

2
docs/widgets/led.rst
View File

@@ -47,7 +47,7 @@ the ON and OFF state.
Events Events
****** ******
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

2
docs/widgets/line.rst
View File

@@ -58,7 +58,7 @@ Events
Only the `Generic events <../overview/event.html#generic-events>`__ are Only the `Generic events <../overview/event.html#generic-events>`__ are
sent by the object type. sent by the object type.
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

10
docs/widgets/menu.rst
View File

@@ -20,12 +20,12 @@ The menu widget is built from the following objects:
- Main container: :cpp:type:`lv_menu_main_cont` - Main container: :cpp:type:`lv_menu_main_cont`
- Main header: :cpp:type:`lv_menu_main_header_cont` - Main header: :cpp:type:`lv_menu_main_header_cont`
- Back button: :ref:`lv_button` - Back button: :ref:`lv_button`
- Back button icon: :ref:`lv_img` - Back button icon: :ref:`lv_image`
- Main page: :cpp:type:`lv_menu_page` - Main page: :cpp:type:`lv_menu_page`
- Sidebar container: :cpp:type:`lv_menu_sidebar_cont` - Sidebar container: :cpp:type:`lv_menu_sidebar_cont`
- Sidebar header: :cpp:type:`lv_menu_sidebar_header_cont` - Sidebar header: :cpp:type:`lv_menu_sidebar_header_cont`
- Back button: :ref:`lv_button` - Back button: :ref:`lv_button`
- Back button icon: :ref:`lv_img` - Back button icon: :ref:`lv_image`
- Sidebar page: :cpp:type:`lv_menu_page` - Sidebar page: :cpp:type:`lv_menu_page`
.. _lv_menu_usage: .. _lv_menu_usage:
@@ -70,14 +70,14 @@ Set a menu page in the main area
-------------------------------- --------------------------------
Once a menu page has been created, you can set it to the main area with Once a menu page has been created, you can set it to the main area with
:cpp:expr:`lv_menu_set_page(menu, page)`. NULL to clear main and clear menu :cpp:expr:`lv_menu_set_page(menu, page)`. ``NULL`` to clear main and clear menu
history. history.
Set a menu page in the sidebar Set a menu page in the sidebar
------------------------------ ------------------------------
Once a menu page has been created, you can set it to the sidebar with Once a menu page has been created, you can set it to the sidebar with
:cpp:expr:`lv_menu_set_sidebar_page(menu, page)`. NULL to clear sidebar. :cpp:expr:`lv_menu_set_sidebar_page(menu, page)`. ``NULL`` to clear sidebar.
Linking between menu pages Linking between menu pages
-------------------------- --------------------------
@@ -115,7 +115,7 @@ Events
- :cpp:expr:`lv_menu_back_button_is_root(menu, button)` to check if button is root - :cpp:expr:`lv_menu_back_button_is_root(menu, button)` to check if button is root
back button back button
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

7
docs/widgets/msgbox.rst
View File

@@ -43,9 +43,10 @@ creates a message box.
If ``parent`` is ``NULL`` the message box will be modal. ``title`` and If ``parent`` is ``NULL`` the message box will be modal. ``title`` and
``txt`` are strings for the title and the text. ``btn_txts[]`` is an ``txt`` are strings for the title and the text. ``btn_txts[]`` is an
array with the buttons' text. E.g. array with the buttons' text.
``const char * btn_txts[] = {"Ok", "Cancel", NULL}``. ``add_close_btn``
can be ``true`` or ``false`` to add/don't add a close button. E.g. :cpp:expr:`const char * btn_txts[] = {"Ok", "Cancel", NULL}`.
``add_close_btn`` can be ``true`` or ``false`` to add/don't add a close button.
Get the parts Get the parts
------------- -------------

2
docs/widgets/roller.rst
View File

@@ -66,7 +66,7 @@ Events
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new option is selected. - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new option is selected.
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

31
docs/widgets/scale.rst
View File

@@ -18,7 +18,8 @@ The scale widget is divided in the following three parts:
- :cpp:enumerator:`LV_PART_MAIN` Main line. See blue line in the example image. - :cpp:enumerator:`LV_PART_MAIN` Main line. See blue line in the example image.
- :cpp:enumerator:`LV_PART_ITEMS` Minor ticks. See red minor ticks in the example image. - :cpp:enumerator:`LV_PART_ITEMS` Minor ticks. See red minor ticks in the example image.
- :cpp:enumerator:`LV_PART_INDICATOR` Major ticks and its labels (if enabled). See pink labels and green major ticks in the example image. - :cpp:enumerator:`LV_PART_INDICATOR` Major ticks and its labels (if enabled).
See pink labels and green major ticks in the example image.
.. image:: /misc/scale.png .. image:: /misc/scale.png
@@ -35,24 +36,38 @@ The minor and major range (values of each tick) are configured with :cpp:expr:`l
Configure ticks Configure ticks
--------------- ---------------
Set the number of total ticks with :cpp:expr:`lv_scale_set_total_tick_count(scale, total_tick_count)` and then configure the major tick being every Nth ticks with :cpp:expr:`lv_scale_set_major_tick_every(scale, nth_tick)`. Set the number of total ticks with :cpp:expr:`lv_scale_set_total_tick_count(scale, total_tick_count)`
and then configure the major tick being every Nth ticks with :cpp:expr:`lv_scale_set_major_tick_every(scale, nth_tick)`.
Labels on major ticks can be configured with :cpp:expr:`lv_scale_set_label_show(scale, show_label)`, set `show_label` to true if labels should be drawn, :cpp:expr:`false` to hide them. If instead of a numerical value in the major ticks a text is required they can be set with :cpp:expr:`lv_scale_set_text_src(scale, custom_labels)` using NULL as the last element, i.e. :cpp:expr:`static char * custom_labels[3] = {"One", "Two", NULL};`. Labels on major ticks can be configured with :cpp:expr:`lv_scale_set_label_show(scale, show_label)`,
set `show_label` to true if labels should be drawn, :cpp:expr:`false` to hide them.
If instead of a numerical value in the major ticks a text is required they can be set
with :cpp:expr:`lv_scale_set_text_src(scale, custom_labels)` using ``NULL`` as the last element,
i.e. :cpp:expr:`static char * custom_labels[3] = {"One", "Two", NULL};`.
The length of the ticks can be configured with the length style property on the :cpp:enumerator: `LV_PART_INDICATOR` for major ticks and :cpp:enumerator: `LV_PART_ITEMS` for minor ticks, for example with local style: :cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_INDICATOR);` for major ticks and :cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_ITEMS);` for minor ticks. The length of the ticks can be configured with the length style property on the :cpp:enumerator:`LV_PART_INDICATOR`
for major ticks and :cpp:enumerator:`LV_PART_ITEMS` for minor ticks, for example with local style:
:cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_INDICATOR);` for major ticks
and :cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_ITEMS);` for minor ticks.
Sections Sections
-------- --------
A section is the space between a minor and a major range. They can be created with :cpp:expr:`lv_scale_add_section(scale)` and it handles back an :cpp:expr:`lv_scale_section_t` pointer. A section is the space between a minor and a major range. They can be created with :cpp:expr:`lv_scale_add_section(scale)`
and it handles back an :cpp:type:`lv_scale_section_t` pointer.
The range of the section is configured with :cpp:expr:`lv_scale_section_set_range(section, minor_range, major_range)`. The style of each of the three parts of the scale section can be set with :cpp:expr:`lv_scale_section_set_style(section, PART, style_pointer)`, where `PART` can be :cpp:enumerator: `LV_PART_MAIN`, :cpp:enumerator: `LV_PART_ITEMS` or :cpp:enumerator: `LV_PART_INDICATOR`, :cpp:expr:`style_pointer` should point to a global or static :cpp:expr:`lv_style_t` variable. The range of the section is configured with :cpp:expr:`lv_scale_section_set_range(section, minor_range, major_range)`.
The style of each of the three parts of the scale section can be set with
:cpp:expr:`lv_scale_section_set_style(section, PART, style_pointer)`, where `PART` can be
:cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_ITEMS` or :cpp:enumerator:`LV_PART_INDICATOR`,
:cpp:expr:`style_pointer` should point to a global or static :cpp:type:`lv_style_t` variable.
For labels the following properties can be configured: For labels the following properties can be configured:
:cpp:expr:`lv_style_set_text_font`, :cpp:expr:`lv_style_set_text_color`, :cpp:expr:`lv_style_set_text_letter_space`, :cpp:expr:`lv_style_set_text_opa`. :cpp:func:`lv_style_set_text_font`, :cpp:func:`lv_style_set_text_color`,
:cpp:func:`lv_style_set_text_letter_space`, :cpp:func:`lv_style_set_text_opa`.
For lines (main line, major and minor ticks) the following properties can be configured: For lines (main line, major and minor ticks) the following properties can be configured:
:cpp:expr:`lv_style_set_line_color`, :cpp:expr:`lv_style_set_line_width`. :cpp:func:`lv_style_set_line_color`, :cpp:func:`lv_style_set_line_width`.
.. _lv_scale_events: .. _lv_scale_events:

30
docs/widgets/span.rst
View File

@@ -47,7 +47,7 @@ child span at index ``id``. In addition, ``id`` can be negative to index
from the end of the spangroup where ``-1`` is the youngest child, ``-2`` from the end of the spangroup where ``-1`` is the youngest child, ``-2``
is second youngest, etc. is second youngest, etc.
e.g. ``lv_span_t* span = lv_spangroup_get_child(spangroup, 0)`` will E.g. ``lv_span_t* span = lv_spangroup_get_child(spangroup, 0)`` will
return the first child of the spangroup. return the first child of the spangroup.
``lv_span_t* span = lv_spangroup_get_child(spangroup, -1)`` will return ``lv_span_t* span = lv_spangroup_get_child(spangroup, -1)`` will return
the last (or most recent) child. the last (or most recent) child.
@@ -58,19 +58,19 @@ Child Count
Use the function :cpp:expr:`lv_spangroup_get_span_count(spangroup)` to get back Use the function :cpp:expr:`lv_spangroup_get_span_count(spangroup)` to get back
the number of spans the group is maintaining. the number of spans the group is maintaining.
e.g. ``uint32_t size = lv_spangroup_get_span_count(spangroup)`` E.g. ``uint32_t size = lv_spangroup_get_span_count(spangroup)``
Text align Text align
---------- ----------
like label object, the spangroup can be set to one the following modes: Like label object, the spangroup can be set to one the following modes:
- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align text to left. - :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align to left.
- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Align text to center. - :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Align to center.
- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align text to right. - :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align to right.
- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align text auto. - :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align auto.
use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER)` Use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER)`
to set text align. to set text align.
Modes Modes
@@ -78,11 +78,11 @@ Modes
The spangroup can be set to one the following modes: The spangroup can be set to one the following modes:
- :cpp:enumerator:`LV_SPAN_MODE_FIXED` fixes the object size. - :cpp:enumerator:`LV_SPAN_MODE_FIXED` Fixes the object size.
- :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand the object size to the text size but stay on a single line. - :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand the object size to the text size but stay on a single line.
- :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width, break the too long lines and auto expand height. - :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width, break the too long lines and auto expand height.
Use :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set Use the function :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set
object mode. object mode.
Overflow Overflow
@@ -91,14 +91,14 @@ Overflow
The spangroup can be set to one the following modes: The spangroup can be set to one the following modes:
- :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates the text at the limit of the area. - :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates the text at the limit of the area.
- :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` will display an ellipsis(``...``) when text overflows the area. - :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` will display an ellipsis (``...``) when text overflows the area.
Use :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set object overflow mode. Use function :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set object overflow mode.
First line indent First line indent
----------------- -----------------
Use :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the Use function :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the
first line. all modes support pixel units, in addition to :cpp:enumerator:`LV_SPAN_MODE_FIXED` first line. all modes support pixel units, in addition to :cpp:enumerator:`LV_SPAN_MODE_FIXED`
and :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode supports percentage units and :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode supports percentage units
too. too.
@@ -106,8 +106,8 @@ too.
Lines Lines
----- -----
Use :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum number Use function :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum number
of lines to be displayed in LV_SPAN_MODE_BREAK mode, negative values of lines to be displayed in :cpp:enumerator::`LV_SPAN_MODE_BREAK` mode, negative values
indicate no limit. indicate no limit.
.. _lv_span_events: .. _lv_span_events:

14
docs/widgets/spinbox.rst
View File

@@ -21,19 +21,15 @@ The parts of the Spinbox are identical to the :ref:`Text area <lv_textarea>`.
Value, range and step Value, range and step
--------------------- ---------------------
:cpp:expr:`lv_spinbox_set_value(spinbox, 1234)` sets a new value on the Spinbox. - :cpp:expr:`lv_spinbox_set_value(spinbox, 1234)` sets a new value on the Spinbox.
- :cpp:expr:`lv_spinbox_increment(spinbox)` and :cpp:expr:`lv_spinbox_decrement(spinbox)`
:cpp:expr:`lv_spinbox_increment(spinbox)` and :cpp:expr:`lv_spinbox_decrement(spinbox)`
increments/decrements the value of the Spinbox according to the currently selected digit. increments/decrements the value of the Spinbox according to the currently selected digit.
- :cpp:expr:`lv_spinbox_set_range(spinbox, -1000, 2500)` sets a range. If the
:cpp:expr:`lv_spinbox_set_range(spinbox, -1000, 2500)` sets a range. If the
value is changed by :cpp:func:`lv_spinbox_set_value`, by value is changed by :cpp:func:`lv_spinbox_set_value`, by
*Keys*,\ ``lv_spinbox_increment/decrement`` this range will be respected. *Keys*,\ ``lv_spinbox_increment/decrement`` this range will be respected.
- :cpp:expr:`lv_spinbox_set_step(spinbox, 100)` sets which digits to change on
:cpp:expr:`lv_spinbox_set_step(spinbox, 100)` sets which digits to change on
increment/decrement. Only multiples of ten can be set, and not for example 3. increment/decrement. Only multiples of ten can be set, and not for example 3.
- :cpp:expr:`lv_spinbox_set_cursor_pos(spinbox, 1)` sets the cursor to a specific
:cpp:expr:`lv_spinbox_set_cursor_pos(spinbox, 1)` sets the cursor to a specific
digit to change on increment/decrement. For example position '0' sets the cursor to the least significant digit. digit to change on increment/decrement. For example position '0' sets the cursor to the least significant digit.
If an encoder is used as input device, the selected digit is shifted to If an encoder is used as input device, the selected digit is shifted to

2
docs/widgets/switch.rst
View File

@@ -50,7 +50,7 @@ Events
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the switch changes state. - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the switch changes state.
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

2
docs/widgets/table.rst
View File

@@ -89,7 +89,7 @@ Events
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new cell is selected with - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new cell is selected with
keys. keys.
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.

11
docs/widgets/textarea.rst
View File

@@ -25,8 +25,8 @@ Parts and Styles
right or center. right or center.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
too long. too long.
- :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the `selected - :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the :ref:`selected
text </widgets/label.html#text-selection>`__. Only ``text_color`` and text <lv_label_text_selection>`. Only ``text_color`` and
``bg_color`` style properties can be used. ``bg_color`` should be set ``bg_color`` style properties can be used. ``bg_color`` should be set
directly on the label of the text area. directly on the label of the text area.
- :cpp:enumerator:`LV_PART_CURSOR` Marks the position where the characters are - :cpp:enumerator:`LV_PART_CURSOR` Marks the position where the characters are
@@ -68,8 +68,9 @@ Delete character
---------------- ----------------
To delete a character from the left of the current cursor position use To delete a character from the left of the current cursor position use
:cpp:expr:`lv_textarea_delete_char(textarea)`. To delete from the right use :cpp:expr:`lv_textarea_delete_char(textarea)`.
:cpp:expr:`lv_textarea_delete_char_forward(textarea)`
To delete from the right use :cpp:expr:`lv_textarea_delete_char_forward(textarea)`
Move the cursor Move the cursor
--------------- ---------------
@@ -167,7 +168,7 @@ Events
- :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`LV_KEY_ENTER` is pressed (or sent) to - :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`LV_KEY_ENTER` is pressed (or sent) to
a one line text area. a one line text area.
See the events of the `Base object </widgets/obj>`__ too. See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`. Learn more about :ref:`events`.