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
- 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
- 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
- `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>`__
- 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.

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.
- Please read and follow the Coding style guide.
.. _contributing_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``
repository to your GitHub account (``https://github.com/<YOUR_NAME>?tab=repositories``)
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.
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.
@@ -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.
They will automatically appear in the PR.
.. _contributing_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"
- don't capitalize the first letter
- no dot (.) at the end
- no dot (``.``) at the end
- max 90 characters
``<body>`` optional and can be used to describe the details of this
@@ -142,6 +146,8 @@ Some examples:
It's similar to HTML <span>
- docs(porting): fix typo
.. _contributing_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
contribute to LVGL.
.. _contributing_star:
Give LVGL a Star
~~~~~~~~~~~~~~~~
@@ -235,11 +243,13 @@ Star
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!
.. _contributing_achieved:
Tell what you have achieved
~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
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
@@ -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
message to us.
.. _contributing_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?
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
`lvgl/examples <https://github.com/lvgl/lvgl/tree/master/examples>`__
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
conventions:
@@ -296,6 +308,8 @@ conventions:
`lvgl/examples/widgets <https://github.com/lvgl/lvgl/tree/master/examples/widgets>`__
folder.
.. _contributing_improve_docs:
Improve the docs
~~~~~~~~~~~~~~~~
@@ -308,6 +322,8 @@ GitHub.
Note that the documentation is also formatted in
`Markdown <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet>`__.
.. _contributing_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
with other developers.
.. _contributing_send_fixes:
Send fixes
~~~~~~~~~~
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.
If you found and fixed a bug don't hesitate to send a `Pull
request <#pull-request>`__ with the fix.
If you found and fixed a bug don't hesitate to send a
:ref:`contributing_pull_request` with the fix.
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -352,6 +372,8 @@ hesitate to share your thoughts and suggestions.
Participating in the discussions is one of the best ways to become part
of the project and get to know like-minded people!
.. _contributing_add_features:
Add features
~~~~~~~~~~~~
@@ -365,7 +387,7 @@ folder. The
file describes the basics rules of contribution and also lists some
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
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>`__
- Update the `changelog <https://github.com/lvgl/lvgl/tree/master/docs/CHANGELOG.md>`__
.. _contributing_become_maintainer:
Become a maintainer
~~~~~~~~~~~~~~~~~~~

1
docs/ROADMAP.rst
View File

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

2
docs/conf.py
View File

@@ -66,7 +66,7 @@ master_doc = 'index'
# General information about the project.
project = 'LVGL'
copyright = '2023, LVGL Kft'
copyright = '2024, LVGL Kft'
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
*****
- tracks: the rows or columns
- main direction: row or column, the direction in which the items are
- **tracks**: the rows or columns
- **main direction**: row or column, the direction in which the items are
placed
- cross direction: perpendicular to the main direction
- 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
- **cross direction**: perpendicular to the main direction
- **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
the track. The available space will be distributed among items
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
****************
@@ -75,7 +75,7 @@ To manage the placement of the children use
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_CENTER`: simply center
- :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
can use them similarly to any other style property. The following flex
related style properties exist:
can use them similarly to any other style property.
The following flex related style properties exist:
- :cpp:enumerator:`FLEX_FLOW`
- :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
*****
- tracks: the rows or columns
- free unit (FR): if set on track's size is set in ``FR`` it will grow
- **tracks**: the rows or columns
- **free unit (FR)**: if set on track's size is set in ``FR`` it will grow
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
****************
@@ -74,13 +74,13 @@ To do this call
``column_align`` and ``row_align`` determine how to align the children
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_CENTER`: simply center ``column_pos`` and ``row_pos``
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
involve from the start cell. Must be >= 1.
involve from the start cell. Must be ``>= 1``.
.. _grid_align:
@@ -131,8 +131,9 @@ Style interface
***************
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
related style properties exist:
can use them similarly to any other style properties.
The following Grid related style properties exist:
- :cpp:enumerator:`GRID_COLUMN_DSC_ARRAY`
- :cpp:enumerator:`GRID_ROW_DSC_ARRAY`

8
docs/libs/bmp.rst
View File

@@ -4,9 +4,11 @@
BMP decoder
===========
This extension allows the use of BMP images in LVGL. This implementation
uses `bmp-decoder <https://github.com/caj-johnson/bmp-decoder>`__
library. The pixels are read on demand (not the whole image is loaded)
This extension allows the use of BMP images in LVGL.
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.
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.
Detailed introduction: `FFmpeg <https://www.ffmpeg.org/>`__
Detailed introduction: https://www.ffmpeg.org
Install FFmpeg
--------------
- Download FFmpeg from `here <https://www.ffmpeg.org/download.html>`__
- ``./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``
Download first FFmpeg from `here <https://www.ffmpeg.org/download.html>`__, then install it:
.. code:: shell
./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
--------------------------
@@ -30,7 +33,7 @@ Enable :c:macro:`LV_USE_FFMPEG` in ``lv_conf.h``.
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
system or platform.

7
docs/libs/freetype.rst
View File

@@ -4,8 +4,9 @@
FreeType support
================
Interface to `FreeType <https://www.freetype.org/>`__ to generate font
bitmaps run time.
Interface to FreeType library to generate font bitmaps run time.
Detailed introduction: https://www.freetype.org
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.
- Enter the FreeType source code directory.
- Enter the FreeType source code directory
- ``make``
- ``sudo make install``
- 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:
- `FATFS <http://elm-chan.org/fsw/ff/00index_e.html>`__
- STDIO (Linux and Windows using C standard function .e.g fopen, fread)
- POSIX (Linux and Windows using POSIX function .e.g open, read)
- WIN32 (Windows using Win32 API function .e.g CreateFileA, ReadFile)
- STDIO (Linux and Windows using C standard function .e.g ``fopen``, ``fread``)
- POSIX (Linux and Windows using POSIX function .e.g ``open``, ``read``)
- WIN32 (Windows using Win32 API function .e.g ``CreateFileA``, ``ReadFile``)
- MEMFS (read a file from a memory buffer)
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.
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`
: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 <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.
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:
@@ -18,7 +20,7 @@ Install
sudo apt install libjpeg-turbo8-dev
Add libjpge-turbo to your project
Add libjpeg-turbo to your project
---------------------------------
.. code:: cmake
@@ -32,11 +34,11 @@ Add libjpge-turbo to your project
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.
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:

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.
Detailed introduction: `libpng <http://www.libpng.org/pub/png/libpng.html>`__
Detailed introduction: http://www.libpng.org/pub/png/libpng.html
Install
-------

11
docs/libs/lodepng.rst
View File

@@ -6,13 +6,13 @@ LodePNG decoder
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
image decoder automatically so PNG files can be directly used as any
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
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
to compress images.
There is a very good and free online PNG compressor site, in which the number
of colors can be reduced, and in the same time preview the result.
A batch of PNG files can be uploaded also.
Compress PNG site: https://compresspng.com/
One option is to use a free online PNG compressor site,
for example Compress PNG: https://compresspng.com/
.. _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
-------------------------------------
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

9
docs/libs/rlottie.rst
View File

@@ -13,11 +13,12 @@ be built separately.
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.
To build on desktop you can follow the instructions from Rlottie's
`README <https://github.com/Samsung/rlottie/blob/master/README.md>`__.
In the most basic case it looks like this:
.. 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
following reasons:
- avoid escaping ``"`` in the JSON file
- avoid escaping ``"`` character in the JSON file
- some compilers don't support very long strings
``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
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.
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
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
-----
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`
: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)
================================
TJpgDec - Tiny JPEG Decompressor.
Allow the use of JPG (JPEG) images in LVGL.
Allow the use of JPEG (JPG) images in LVGL.
Detailed introduction: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__
@@ -14,10 +13,10 @@ Detailed introduction: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__
Overview
--------
- JPG is decoded in 8x8 tiles.
- Only baseline JPG files are supported (no progressive JPG support).
- JPEG is decoded in 8x8 tiles.
- Only baseline JPEG files are supported (no progressive JPEG support).
- 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.
.. _tjpgd_usage:
@@ -26,21 +25,23 @@ Usage
-----
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
as image sources. For example:
image decoder automatically so JPEG files can be used directly
as image sources.
For example:
.. code:: c
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
files. Read more about it :ref:`overview_file_system` or just
enable one in ``lv_conf.h`` with ``LV_USE_FS_...``
:Note: a file system driver needs to be registered to open images from
files. Read more about :ref:`overview_file_system` or just
enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` config.
Converter
---------
Converting JPG to C array
Converting JPEG to C array
~~~~~~~~~~~~~~~~~~~~~~~~~
- 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
: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_KIND`
@@ -73,9 +75,9 @@ default sorting to :cpp:enumerator:`LV_EXPLORER_SORT_NONE`. The default is
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.
- :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.
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
and y coordinates are considered. This means that gridnav works with
manually positioned children, as well as `Flex </layouts/flex>`__ and
`Grid </layouts/grid>`__ layouts.
manually positioned children, as well as :ref:`flex` and
:ref:`grid` layouts.
Gridnav also works if the children are arranged into a single row or
column. That makes it useful, for example, to simplify navigation on a
`List widget </widgets/list>`__.
:ref:`List widget <lv_list>`.
Gridnav assumes that the object to which gridnav is added is part of a
`group </overview/indev.html#groups>`__. This way, if the object with
:ref:`group <indev_groups>`. This way, if the object with
gridnav is focused, the arrow key presses are automatically forwarded to
the object so that gridnav can process the arrow keys.

10
docs/others/imgfont.rst
View File

@@ -1,13 +1,13 @@
.. _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.
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:

5
docs/others/obj_id.rst
View File

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

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>`__.
It consists of
It consists of:
- **subjects**: each containing a value
- **observers**: attached to subjects to be notified on value change
@@ -78,7 +78,7 @@ Subject
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)`.
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.
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.
An optional format string can be added with 1 format specifier (e.g. ``"%d °C"``)
If the format string is ``NULL`` the value will be used directly. In this case on string and pointer type subjects can be used.
.. code:: c

2
docs/overview/coord.rst
View File

@@ -88,7 +88,7 @@ the screen of ``obj``.
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,
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``

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 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,
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
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.
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
***********
@@ -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_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_THROW_BEGIN,
- :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 `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_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
@@ -128,8 +129,8 @@ Input device 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_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_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_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
@@ -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_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_param(e)`: get the parameter passed as the last parameter of :cpp:func:`lv_event_send`
.. _events_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
-------------
- :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_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
@@ -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
*lv_conf.h*.
.. _fonts_compressed:
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 file
.. _overview_image_variables:
Variables
---------
@@ -23,7 +25,7 @@ Images stored internally in a variable are composed mainly of an
- **header**:
- *cf*: Color format. See `below <#color-format>`__
- *cf*: Color format. See :ref:`below <overview_image_color_formats>`
- *w*: width in pixels (<= 2048)
- *h*: height in pixels (<= 2048)
- *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
into the resulting executable like any other constant data.
.. _overview_image_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.
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
``.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.
5. Hit the *Convert* button. Once the conversion is finished, your
browser will automatically download the resulting file.
@@ -174,7 +178,7 @@ you want to use it.
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
all you need. LVGL doesn't directly support, however, generic image
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
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

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_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_PREV`
- :cpp:enumerator:`LV_KEY_ENTER`,
- :cpp:enumerator:`LV_KEY_UP`,
- :cpp:enumerator:`LV_KEY_DOWN`,
- :cpp:enumerator:`LV_KEY_LEFT`
- :cpp:enumerator:`LV_KEY_RIGHT`
- :cpp:enumerator:`LV_KEY_NEXT`
- :cpp:enumerator:`LV_KEY_PREV`
- :cpp:enumerator:`LV_KEY_ENTER`
- :cpp:enumerator:`LV_KEY_UP`
- :cpp:enumerator:`LV_KEY_DOWN`
- :cpp:enumerator:`LV_KEY_LEFT`
- :cpp:enumerator:`LV_KEY_RIGHT`
You should translate some of your keys to these special keys to support navigation
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
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
descriptor and allows creating gradients with more colors too.
@@ -2746,7 +2746,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 the width of the shadow in pixels. The value should be ``>= 0``.
.. raw:: html

2
docs/porting/draw.rst
View File

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

2
docs/widgets/animimg.rst
View File

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

4
docs/widgets/arc.rst
View File

@@ -157,7 +157,7 @@ Events
- ``draw_area``: the area of the knob
- ``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`.
@@ -182,5 +182,3 @@ Example
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
******
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`.
@@ -87,5 +87,3 @@ Example
API
***
:ref:`lv_bar`

2
docs/widgets/button.rst
View File

@@ -7,7 +7,7 @@ Button (lv_button)
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.
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
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
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
(``""``)!
@@ -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*
will have 33 % width and *buttonB* will have 66 % width. It's similar to
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
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_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_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_2`: Custom free to use flag
By default, all flags are disabled.
To set or clear a button's control attribute, use
``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_set_button_ctrl(buttonm, button_id, LV_BUTTONMATRIX_CTRL_...)` and
:cpp:expr:`lv_buttonmatrix_clear_button_ctrl(buttonm, button_id, LV_BUTTONMATRIX_CTRL_...)`
respectively. More ``LV_BUTTONMATRIX_CTRL_...`` values can be OR-ed
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_...)``
and ``lv_buttonmatrix_clear_button_ctrl_all(buttonm, LV_BUTTONMATRIX_CTRL_...)``.
matrix, use :cpp:expr:`lv_buttonmatrix_set_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
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[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
(excluding newlines characters).
@@ -110,7 +109,7 @@ Events
repeated after long press. The event parameter is set to the ID of
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
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
****************
: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.
.. _lv_canvas_usage:

12
docs/widgets/chart.rst
View File

@@ -25,7 +25,7 @@ Parts and Styles
charts ``pad_column`` sets the space between the columns of the
adjacent indices.
- :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.
- Line chart: The *line* properties are used by the lines.
@@ -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
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_SECONDARY_Y` Right axis
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_X` Bottom axis
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_X` Top axis
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_Y`: Left axis
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_Y`: Right axis
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_X`: Bottom axis
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_X`: Top axis
``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
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`.

2
docs/widgets/checkbox.rst
View File

@@ -63,7 +63,7 @@ Events
- :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`.

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_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`.

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>`__
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
: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
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
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
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
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
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.
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.
**IMPORTANT** The transformation of the image is independent of the
@@ -153,31 +153,35 @@ differences are that pure image widget transformation
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.
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
- :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 alignment set any of these:
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.
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: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_STRETCH` Set X and Y scale to fill the widget's area
- :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:

2
docs/widgets/imagebutton.rst
View File

@@ -53,7 +53,7 @@ they will be used in pressed state instead of the released images.
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
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
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_BACKSPACE` Delete on the left.
- :c:macro:`LV_SYMBOL_LEFT` Move the cursor left.
- :c:macro:`LV_SYMBOL_RIGHT` Move the cursor right.
- :c:macro:`LV_SYMBOL_NEW_LINE` New line.
- *"ABC"* Load the uppercase map.
- *"abc"* Load the lower case map.
- *"1#"* Load the lower case map.
- ``"ABC"`` Load the uppercase map.
- ``"abc"`` Load the lower case map.
- ``"1#"`` Load the lower case map.
.. _lv_keyboard_events:

4
docs/widgets/label.rst
View File

@@ -19,8 +19,8 @@ Parts and Styles
the text and the background.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
larger than the widget's size.
- :cpp:enumerator:`LV_PART_SELECTED` Tells the style of the `selected
text <#text-selection>`__. Only ``text_color`` and ``bg_color`` style
- :cpp:enumerator:`LV_PART_SELECTED` Tells the style of the
:ref:`selected text <lv_label_text_selection>`. Only ``text_color`` and ``bg_color`` style
properties can be used.
.. _lv_label_usage:

2
docs/widgets/led.rst
View File

@@ -47,7 +47,7 @@ the ON and OFF state.
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`.

2
docs/widgets/line.rst
View File

@@ -58,7 +58,7 @@ Events
Only the `Generic events <../overview/event.html#generic-events>`__ are
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`.

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 header: :cpp:type:`lv_menu_main_header_cont`
- Back button: :ref:`lv_button`
- Back button icon: :ref:`lv_img`
- Back button icon: :ref:`lv_image`
- Main page: :cpp:type:`lv_menu_page`
- Sidebar container: :cpp:type:`lv_menu_sidebar_cont`
- Sidebar header: :cpp:type:`lv_menu_sidebar_header_cont`
- Back button: :ref:`lv_button`
- Back button icon: :ref:`lv_img`
- Back button icon: :ref:`lv_image`
- Sidebar page: :cpp:type:`lv_menu_page`
.. _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
: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.
Set a menu page in the sidebar
------------------------------
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
--------------------------
@@ -115,7 +115,7 @@ Events
- :cpp:expr:`lv_menu_back_button_is_root(menu, button)` to check if button is root
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`.

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
``txt`` are strings for the title and the text. ``btn_txts[]`` is an
array with the buttons' text. E.g.
``const char * btn_txts[] = {"Ok", "Cancel", NULL}``. ``add_close_btn``
can be ``true`` or ``false`` to add/don't add a close button.
array with the buttons' text.
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
-------------

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.
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`.

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_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
@@ -35,24 +36,38 @@ The minor and major range (values of each tick) are configured with :cpp:expr:`l
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
--------
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:
: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:
: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:

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``
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.
``lv_span_t* span = lv_spangroup_get_child(spangroup, -1)`` will return
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
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
----------
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_CENTER` Align text to center.
- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align text to right.
- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align text auto.
- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align to left.
- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Align to center.
- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align to right.
- :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.
Modes
@@ -78,11 +78,11 @@ 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_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.
Overflow
@@ -91,14 +91,14 @@ Overflow
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_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
-----------------
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`
and :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode supports percentage units
too.
@@ -106,8 +106,8 @@ too.
Lines
-----
Use :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
Use function :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum number
of lines to be displayed in :cpp:enumerator::`LV_SPAN_MODE_BREAK` mode, negative values
indicate no limit.
.. _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
---------------------
: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_set_value(spinbox, 1234)` sets a new value on the 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.
: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
*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.
: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.
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.
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`.

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
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`.

11
docs/widgets/textarea.rst
View File

@@ -25,8 +25,8 @@ Parts and Styles
right or center.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
too long.
- :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the `selected
text </widgets/label.html#text-selection>`__. Only ``text_color`` and
- :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the :ref:`selected
text <lv_label_text_selection>`. Only ``text_color`` and
``bg_color`` style properties can be used. ``bg_color`` should be set
directly on the label of the text area.
- :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
:cpp:expr:`lv_textarea_delete_char(textarea)`. To delete from the right use
:cpp:expr:`lv_textarea_delete_char_forward(textarea)`
:cpp:expr:`lv_textarea_delete_char(textarea)`.
To delete from the right use :cpp:expr:`lv_textarea_delete_char_forward(textarea)`
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
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`.