Embedded/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2025-01-28 07:03:00 +08:00
Code Issues Projects Releases Wiki Activity

docs: fix links, add references, rename files (#5138)

Browse Source
This commit is contained in:
PGNetHun 2024-01-04 07:25:13 +01:00 committed by GitHub
parent 6136bd6cd0
commit 2a129562d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
94 changed files with 1441 additions and 837 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/CHANGELOG.rst
View File

@ -39,7 +39,7 @@ Main new features
- `lv_observer </others/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>`__
- `lv_image </widgets/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.
General API changes
-------------------

2
docs/ROADMAP.rst
View File

@ -155,7 +155,7 @@ Others
- |uncheck| Scene support. See `this comment <https://github.com/lvgl/lvgl/issues/2790#issuecomment-965100911>`__
- |uncheck| Circle layout. #2871
- |uncheck| Consider `stagger animations <https://greensock.com/docs/v3/Staggers>`__.
- |uncheck| Add custom indev type. See [here](https://github.com/lvgl/lvgl/issues/3298#issuecomment-1616706654).
- |uncheck| Add custom indev type. See `here <https://github.com/lvgl/lvgl/issues/3298#issuecomment-1616706654>`__.
- |uncheck| Automatically recalculate the layout if a coordinate is obtained using `lv_obj_get_width/height/x/y/etc`
Ideas

2
docs/get-started/index.rst
View File

@ -1,3 +1,5 @@
.. _get_started:
===========
Get started
===========

20
docs/get-started/quick-overview.rst
View File

@ -108,6 +108,8 @@ section.
Learn the basics
----------------
.. _quick-overview_widgets:
Widgets
~~~~~~~
@ -160,6 +162,8 @@ To see the full API visit the documentation of the widgets or the
related header file
(e.g. `lvgl/src/widgets/slider/lv_slider.h <https://github.com/lvgl/lvgl/blob/master/src/widgets/slider/lv_slider.h>`__).
.. _quick-overview_events:
Events
~~~~~~
@ -197,12 +201,14 @@ The object that triggered the event can be retrieved with:
To learn all features of the events go to the :ref:`events` section.
.. _quick-overview_parts:
Parts
~~~~~
Widgets might be built from one or more *parts*. For example, a button
has only one part called :cpp:enumerator:`LV_PART_MAIN`. However, a
:ref:`slider` has :cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_INDICATOR`
:ref:`lv_slider` has :cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_INDICATOR`
and :cpp:enumerator:`LV_PART_KNOB`.
By using parts you can apply different styles to sub-elements of a
@ -210,6 +216,8 @@ widget. (See below)
Read the widgets' documentation to learn which parts each uses.
.. _quick-overview_states:
States
~~~~~~
@ -241,6 +249,8 @@ To manually add or remove states use:
lv_obj_add_state(obj, LV_STATE_...);
lv_obj_remove_state(obj, LV_STATE_...);
.. _quick-overview_styles:
Styles
~~~~~~
@ -260,7 +270,7 @@ configure the style. For example:
lv_style_set_bg_color(&style1, lv_color_hex(0xa03080))
lv_style_set_border_width(&style1, 2))
See the full list of properties here :ref:`style_properties`.
See the full list of properties here :ref:`styles_properties`.
Styles are assigned using the ORed combination of an object's part and
state. For example to use this style on the slider's indicator when the
@ -316,6 +326,8 @@ style which resides inside the object and is used only by the object:
To learn all the features of styles see the :ref:`styles` section.
.. _quick-overview_themes:
Themes
~~~~~~
@ -325,11 +337,15 @@ applied automatically when objects are created.
The theme for your application is a compile time configuration set in
``lv_conf.h``.
.. _quick-overview_examples:
Examples
--------
.. include:: ../examples/get_started/index.rst
.. _quick-overview_micropython:
Micropython
-----------

4
docs/intro/index.rst
View File

@ -41,7 +41,7 @@ Basically, every modern controller which is able to drive a display is suitable
* Static RAM usage: ~2 kB depending on the used features and object types
* stack: > 2kB (> 8 kB is recommended)
* Dynamic data (heap): > 2 KB (> 48 kB is recommended if using several objects).
Set by :c:macro:`LV_MEM_SIZE` in `lv_conf.h`.
Set by :c:macro:`LV_MEM_SIZE` in ``lv_conf.h``.
* Display buffer: > *"Horizontal resolution"* pixels (> 10 *"Horizontal resolution"* is recommended)
* One frame buffer in the MCU or in an external display controller
* C99 or newer compiler
@ -196,7 +196,7 @@ LVGL doesn't start, randomly crashes or nothing is drawn on the display. What ca
* Be sure :cpp:type:`lv_disp_t`, :cpp:type:`lv_indev_t` and :cpp:type:`lv_fs_drv_t` are global or `static`.
* Be sure your display works without LVGL. E.g. paint it to red on start up.
* Enable :ref:`logging`
* Enable asserts in `lv_conf.h` (`LV_USE_ASSERT_...`)
* Enable asserts in ``lv_conf.h`` (`LV_USE_ASSERT_...`)
* If you use an RTOS
* increase the stack size of the task which calls :cpp:func:`lv_timer_handler`
* Be sure you used a mutex as described here: :ref:`os_interrupt`

83
docs/layouts/flex.rst
View File

@ -1,3 +1,5 @@
.. _flex:
====
Flex
====
@ -13,7 +15,7 @@ the item(s) fill the remaining space with respect to min/max width and
height.
To make an object flex container call
:c:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`.
:cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`.
Note that the flex layout feature of LVGL needs to be globally enabled
with :c:macro:`LV_USE_FLEX` in ``lv_conf.h``.
@ -36,30 +38,34 @@ Simple interface
With the following functions you can set a Flex layout on any parent.
.. _flex_flow:
Flex flow
---------
:c:expr:`lv_obj_set_flex_flow(obj, flex_flow)`
:cpp:expr:`lv_obj_set_flex_flow(obj, flex_flow)`
The possible values for ``flex_flow`` are:
- :c:enumerator:`LV_FLEX_FLOW_ROW`: Place the children in a row without wrapping
- :c:enumerator:`LV_FLEX_FLOW_COLUMN`: Place the children in a column without wrapping
- :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP`: Place the children in a row with wrapping
- :c:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP`: Place the children in a column with wrapping
- :c:enumerator:`LV_FLEX_FLOW_ROW_REVERSE`: Place the children in a row without wrapping but in reversed order
- :c:enumerator:`LV_FLEX_FLOW_COLUMN_REVERSE`: Place the children in a column without wrapping but in reversed order
- :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP_REVERSE`: Place the children in a row with wrapping but in reversed order
- :c:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP_REVERSE`: Place the children in a column with wrapping but in reversed order
- :cpp:enumerator:`LV_FLEX_FLOW_ROW`: Place the children in a row without wrapping
- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN`: Place the children in a column without wrapping
- :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP`: Place the children in a row with wrapping
- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP`: Place the children in a column with wrapping
- :cpp:enumerator:`LV_FLEX_FLOW_ROW_REVERSE`: Place the children in a row without wrapping but in reversed order
- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_REVERSE`: Place the children in a column without wrapping but in reversed order
- :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP_REVERSE`: Place the children in a row with wrapping but in reversed order
- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP_REVERSE`: Place the children in a column with wrapping but in reversed order
.. _flex_align:
Flex align
----------
To manage the placement of the children use
:c:expr:`lv_obj_set_flex_align(obj, main_place, cross_place, track_cross_place)`
:cpp:expr:`lv_obj_set_flex_align(obj, main_place, cross_place, track_cross_place)`
- ``main_place`` determines how to distribute the items in their track
on the main axis. E.g. flush the items to the right on :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP`. (It's called
on the main axis. E.g. flush the items to the right on :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP`. (It's called
``justify-content`` in CSS)
- ``cross_place`` determines how to distribute the items in their track
on the cross axis. E.g. if the items have different height place them
@ -69,37 +75,44 @@ To manage the placement of the children use
The possible values are:
- :c:enumerator:`LV_FLEX_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :c:enumerator:`LV_FLEX_ALIGN_END`: means right on a horizontally and bottom vertically
- :c:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center
- :c:enumerator:`LV_FLEX_ALIGN_SPACE_EVENLY`: items are distributed so
- :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
that the spacing between any two items (and the space to the edges) is
equal. Does not apply to ``track_cross_place``.
- :c:enumerator:`LV_FLEX_ALIGN_SPACE_AROUND`: items are evenly
- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_AROUND`: items are evenly
distributed in the track with equal space around them. Note that
visually the spaces aren't equal, since all the items have equal space
on both sides. The first item will have one unit of space against the
container edge, but two units of space between the next item because
that next item has its own spacing that applies. Not applies to
``track_cross_place``.
- :c:enumerator:`LV_FLEX_ALIGN_SPACE_BETWEEN`: items are evenly distributed in
- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_BETWEEN`: items are evenly distributed in
the track: first item is on the start line, last item on the end line. Not applies to ``track_cross_place``.
.. _flex_grow:
Flex grow
---------
Flex grow can be used to make one or more children fill the available
space on the track. When more children have grow parameters, the
available space will be distributed proportionally to the grow values.
For example, there is 400 px remaining space and 4 objects with grow: -
``A`` with grow = 1 - ``B`` with grow = 1 - ``C`` with grow = 2
For example, there is 400 px remaining space and 4 objects with grow:
- ``A`` with grow = 1
- ``B`` with grow = 1
- ``C`` with grow = 2
``A`` and ``B`` will have 100 px size, and ``C`` will have 200 px size.
Flex grow can be set on a child with
:c:expr:`lv_obj_set_flex_grow(child, value)`. ``value`` needs to be >
:cpp:expr:`lv_obj_set_flex_grow(child, value)`. ``value`` needs to be >
1 or 0 to disable grow on the child.
.. _flex_style:
Style interface
***************
@ -107,11 +120,13 @@ 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:
- :c:enumerator:`FLEX_FLOW`
- :c:enumerator:`FLEX_MAIN_PLACE`
- :c:enumerator:`FLEX_CROSS_PLACE`
- :c:enumerator:`FLEX_TRACK_PLACE`
- :c:enumerator:`FLEX_GROW`
- :cpp:enumerator:`FLEX_FLOW`
- :cpp:enumerator:`FLEX_MAIN_PLACE`
- :cpp:enumerator:`FLEX_CROSS_PLACE`
- :cpp:enumerator:`FLEX_TRACK_PLACE`
- :cpp:enumerator:`FLEX_GROW`
.. _flex_padding:
Internal padding
----------------
@ -124,7 +139,9 @@ following properties can be set on the flex container style:
- ``pad_column`` Sets the padding between the columns.
These can for example be used if you don't want any padding between your
objects: :c:expr:`lv_style_set_pad_column(&row_container_style,0)`
objects: :cpp:expr:`lv_style_set_pad_column(&row_container_style,0)`
.. _flex_other:
Other features
**************
@ -133,9 +150,9 @@ RTL
---
If the base direction of the container is set the
:c:enumerator:`LV_BASE_DIR_RTL` the meaning of
:c:enumerator:`LV_FLEX_ALIGN_START` and
:c:enumerator:`LV_FLEX_ALIGN_END` is swapped on ``ROW`` layouts. I.e.
:cpp:enumerator:`LV_BASE_DIR_RTL` the meaning of
:cpp:enumerator:`LV_FLEX_ALIGN_START` and
:cpp:enumerator:`LV_FLEX_ALIGN_END` is swapped on ``ROW`` layouts. I.e.
``START`` will mean right.
The items on ``ROW`` layouts, and tracks of ``COLUMN`` layouts will be
@ -145,12 +162,16 @@ New track
---------
You can force Flex to put an item into a new line with
:c:expr:`lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`.
:cpp:expr:`lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`.
.. _flex_example:
Example
*******
.. include:: ../examples/layouts/flex/index.rst
.. _flex_api:
API
***

70
docs/layouts/grid.rst
View File

@ -1,3 +1,5 @@
.. _grid:
====
Grid
====
@ -13,7 +15,7 @@ track's size can be set in pixel, to the largest item
(:c:macro:`LV_GRID_CONTENT`) or in "Free unit" (FR) to distribute the free
space proportionally.
To make an object a grid container call :c:expr:`lv_obj_set_layout(obj, LV_LAYOUT_GRID)`.
To make an object a grid container call :cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_GRID)`.
Note that the grid layout feature of LVGL needs to be globally enabled
with :c:macro:`LV_USE_GRID` in ``lv_conf.h``.
@ -32,6 +34,8 @@ Simple interface
With the following functions you can easily set a Grid layout on any
parent.
.. _grid_descriptors:
Grid descriptors
----------------
@ -47,15 +51,17 @@ For example:
static int32_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; /*3 100 px tall rows*/
To set the descriptors on a parent use
:c:expr:`lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`.
:cpp:expr:`lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`.
Besides simple settings the size in pixel you can use two special
values:
- :c:macro:`LV_GRID_CONTENT` set the size to fit the largest child on this track
- :c:expr:`LV_GRID_FR(X)` tell what portion of the remaining space
- :cpp:expr:`LV_GRID_FR(X)` tell what portion of the remaining space
should be used by this track. Larger value means larger space.
.. _grid_items:
Grid items
----------
@ -63,42 +69,45 @@ By default, the children are not added to the grid. They need to be
added manually to a cell.
To do this call
:c:expr:`lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span)`.
:cpp:expr:`lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span)`.
``column_align`` and ``row_align`` determine how to align the children
in its cell. The possible values are:
- :c:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :c:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically
- :c:enumerator:`LV_GRID_ALIGN_CENTER`: simply center ``column_pos`` and ``row_pos``
- :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.
.. _grid_align:
Grid align
----------
If there are some empty space the track can be aligned several ways:
- :c:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :c:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically
- :c:enumerator:`LV_GRID_ALIGN_CENTER`: simply center
- :c:enumerator:`LV_GRID_ALIGN_SPACE_EVENLY`: items are distributed so that the spacing
- :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
- :cpp:enumerator:`LV_GRID_ALIGN_SPACE_EVENLY`: items are distributed so that the spacing
between any two items (and the space to the edges) is equal. Not applies to ``track_cross_place``.
- :c:enumerator:`LV_GRID_ALIGN_SPACE_AROUND`: items are
- :cpp:enumerator:`LV_GRID_ALIGN_SPACE_AROUND`: items are
evenly distributed in the track with equal space around them. Note that
visually the spaces aren't equal, since all the items have equal space
on both sides. The first item will have one unit of space against the
container edge, but two units of space between the next item because
that next item has its own spacing that applies. Not applies to ``track_cross_place``.
- :c:enumerator:`LV_GRID_ALIGN_SPACE_BETWEEN`: items are
- :cpp:enumerator:`LV_GRID_ALIGN_SPACE_BETWEEN`: items are
evenly distributed in the track: first item is on the start line, last
item on the end line. Not applies to ``track_cross_place``.
To set the track's alignment use
:c:expr:`lv_obj_set_grid_align(obj, column_align, row_align)`.
:cpp:expr:`lv_obj_set_grid_align(obj, column_align, row_align)`.
.. _grid_subgrid:
Sub grid
--------
@ -116,6 +125,7 @@ Limitations:
The sub grid feature works the same as in CSS. For further reference see `this description <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Subgrid>`__.
.. _grid_style:
Style interface
***************
@ -124,16 +134,18 @@ 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:
- :c:enumerator:`GRID_COLUMN_DSC_ARRAY`
- :c:enumerator:`GRID_ROW_DSC_ARRAY`
- :c:enumerator:`GRID_COLUMN_ALIGN`
- :c:enumerator:`GRID_ROW_ALIGN`
- :c:enumerator:`GRID_CELL_X_ALIGN`
- :c:enumerator:`GRID_CELL_COLUMN_POS`
- :c:enumerator:`GRID_CELL_COLUMN_SPAN`
- :c:enumerator:`GRID_CELL_Y_ALIGN`
- :c:enumerator:`GRID_CELL_ROW_POS`
- :c:enumerator:`GRID_CELL_ROW_SPAN`
- :cpp:enumerator:`GRID_COLUMN_DSC_ARRAY`
- :cpp:enumerator:`GRID_ROW_DSC_ARRAY`
- :cpp:enumerator:`GRID_COLUMN_ALIGN`
- :cpp:enumerator:`GRID_ROW_ALIGN`
- :cpp:enumerator:`GRID_CELL_X_ALIGN`
- :cpp:enumerator:`GRID_CELL_COLUMN_POS`
- :cpp:enumerator:`GRID_CELL_COLUMN_SPAN`
- :cpp:enumerator:`GRID_CELL_Y_ALIGN`
- :cpp:enumerator:`GRID_CELL_ROW_POS`
- :cpp:enumerator:`GRID_CELL_ROW_SPAN`
.. _grid_padding:
Internal padding
----------------
@ -144,22 +156,28 @@ properties can be set on the Grid container style:
- ``pad_row`` Sets the padding between the rows.
- ``pad_column`` Sets the padding between the columns.
.. _grid_other:
Other features
**************
RTL
---
If the base direction of the container is set to :c:enumerator:`LV_BASE_DIR_RTL`,
the meaning of :c:enumerator:`LV_GRID_ALIGN_START` and :c:enumerator:`LV_GRID_ALIGN_END` is
If the base direction of the container is set to :cpp:enumerator:`LV_BASE_DIR_RTL`,
the meaning of :cpp:enumerator:`LV_GRID_ALIGN_START` and :cpp:enumerator:`LV_GRID_ALIGN_END` is
swapped. I.e. ``START`` will mean right-most.
The columns will be placed from right to left.
.. _grid_examples:
Example
*******
.. include:: ../examples/layouts/grid/index.rst
.. _grid_api:
API
***

2
docs/layouts/index.rst
View File

@ -1,3 +1,5 @@
.. _layouts:
=======
Layouts
=======

23
docs/libs/barcode.rst
View File

@ -1,3 +1,5 @@
.. _barcode:
=======
Barcode
=======
@ -6,17 +8,20 @@ Barcode generation with LVGL. Uses
`code128 <https://github.com/fhunleth/code128>`__ by
`fhunleth <https://github.com/fhunleth>`__.
.. _barcode_usage:
Usage
-----
Enable :c:macro:`LV_USE_BARCODE` in ``lv_conf.h``.
Use :c:expr:`lv_barcode_create()` to create a barcode object, and use
:c:expr:`lv_barcode_update()` to generate a barcode.
Use :cpp:func:`lv_barcode_create` to create a barcode object, and use
:cpp:func:`lv_barcode_update` to generate a barcode.
Call :c:expr:`lv_barcode_set_scale()` or :c:expr:`lv_barcode_set_dark/light_color()`
to adjust scaling and color, call :c:expr:`lv_barcode_set_direction()` will set
direction to display, and call :c:expr:`lv_barcode_update()` again to regenerate
Call :cpp:func:`lv_barcode_set_scale` to adjust scaling,
call :cpp:func:`lv_barcode_set_dark_color` and :cpp:func:`lv_barcode_set_light_color`
adjust color, call :cpp:func:`lv_barcode_set_direction` will set
direction to display, and call :cpp:func:`lv_barcode_update` again to regenerate
the barcode.
Notes
@ -26,14 +31,18 @@ Notes
the width of the object is lower than the width of the barcode, the
display will be incomplete due to truncation.
- The scale adjustment can only be an integer multiple, for example,
:c:expr:`lv_barcode_set_scale(barcode, 2)` means 2x scaling.
- The direction adjustment can be `LV_DIR_HOR` or `LV_DIR_VER`
:cpp:expr:`lv_barcode_set_scale(barcode, 2)` means 2x scaling.
- The direction adjustment can be :cpp:enumerator:`LV_DIR_HOR` or :cpp:enumerator:`LV_DIR_VER`
.. _barcode_example:
Example
-------
.. include:: ../examples/libs/barcode/index.rst
.. _barcode_api:
API
---

10
docs/libs/bmp.rst
View File

@ -1,3 +1,5 @@
.. _bmp:
===========
BMP decoder
===========
@ -16,9 +18,11 @@ sources. For example:
lv_image_set_src(my_img, "S:path/to/picture.bmp");
Note that, a file system driver needs to registered to open images from
files. Read more about it :ref:`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_...``
.. _bmp_limitations:
Limitations
-----------
@ -34,11 +38,15 @@ Limitations
- Palette is not supported.
- Because not the whole image is read in can not be zoomed or rotated.
.. _bmp_example:
Example
-------
.. include:: ../examples/libs/bmp/index.rst
.. _bmp_api:
API
---

13
docs/libs/ffmpeg.rst
View File

@ -1,9 +1,12 @@
.. _ffmpeg:
==============
FFmpeg support
==============
`FFmpeg <https://www.ffmpeg.org/>`__ 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/>`__
Install FFmpeg
--------------
@ -18,6 +21,8 @@ Add FFmpeg to your project
- Add library: ``FFmpeg`` (for GCC: ``-lavformat -lavcodec -lavutil -lswscale -lm -lz -lpthread``)
.. _ffmpeg_usage:
Usage
-----
@ -29,11 +34,15 @@ Note that, the 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.
.. _ffmpeg_example:
Example
-------
.. include:: ../examples/libs/ffmpeg/index.rst
.. _ffmpeg_api:
API
---

21
docs/libs/freetype.rst
View File

@ -1,3 +1,5 @@
.. _freetype:
================
FreeType support
================
@ -16,6 +18,7 @@ For UNIX
~~~~~~~~
For UNIX systems, it is recommended to use the way of compiling and installing libraries.
- Enter the FreeType source code directory.
- ``make``
- ``sudo make install``
@ -56,6 +59,8 @@ FLASH space.
FT_CSRCS += freetype/src/truetype/truetype.c
CSRCS += $(FT_CSRCS)
.. _freetype_usage:
Usage
-----
@ -79,17 +84,19 @@ interface, you can enable :c:macro:`LV_FREETYPE_USE_LVGL_PORT` in
The font style supports *Italic* and **Bold** fonts processed by
software, and can be set with reference to the following values:
- :c:enumerator:`LV_FREETYPE_FONT_STYLE_NORMAL`: Default style.
- :c:enumerator:`LV_FREETYPE_FONT_STYLE_ITALIC`: Italic style.
- :c:enumerator:`LV_FREETYPE_FONT_STYLE_BOLD`: Bold style.
- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_NORMAL`: Default style.
- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_ITALIC`: Italic style.
- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_BOLD`: Bold style.
They can be combined.eg:
:c:expr:`LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC`.
:cpp:expr:`LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC`.
Use the :c:expr:`lv_freetype_font_create()` function to create a font. To
delete a font, use :c:expr:`lv_freetype_font_delete()`. For more detailed usage,
Use the :cpp:func:`lv_freetype_font_create` function to create a font. To
delete a font, use :cpp:func:`lv_freetype_font_delete`. For more detailed usage,
please refer to example code.
.. _freetype_example:
Example
-------
@ -101,6 +108,8 @@ Learn more
- FreeType`tutorial <https://www.freetype.org/freetype2/docs/tutorial/step1.html>`__
- LVGL's :ref:`add_font`
.. _freetype_api:
API
---

12
docs/libs/fs.rst
View File

@ -1,8 +1,10 @@
.. _libs_filesystem:
======================
File System Interfaces
======================
LVGL has a :ref:`file-system` module
LVGL has a :ref:`overview_file_system` module
to provide an abstraction layer for various file system drivers.
LVG has built in support for:
@ -16,6 +18,8 @@ LVG has built in support for:
You still need to provide the drivers and libraries, this extension
provides only the bridge between FATFS, STDIO, POSIX, WIN32 and LVGL.
.. _libs_filesystem_usage:
Usage
*****
@ -28,11 +32,11 @@ The work directory can be set with ``LV_FS_..._PATH``. E.g.
appended to it.
Cached reading is also supported if ``LV_FS_..._CACHE_SIZE`` is set to
not ``0`` value. :c:func:`lv_fs_read` caches this size of data to lower the
not ``0`` value. :cpp:func:`lv_fs_read` caches this size of data to lower the
number of actual reads from the storage.
To use the memory-mapped file emulation an ``lv_fs_path_ex_t`` object must be
created and initialized. This object can be passed to :c:func:`lv_fs_open()` as
created and initialized. This object can be passed to :cpp:func:`lv_fs_open` as
the file name:
.. code:: c
@ -48,6 +52,8 @@ the file name:
lv_fs_make_path_from_buffer(&mempath, LV_FS_MEMFS_LETTER, (void*)buffer, size);
lv_fs_res_t res = lv_fs_open(&file, (const char *)&mempath, LV_FS_MODE_RD);
.. _libs_filesystem_api:
API
***

17
docs/libs/gif.rst
View File

@ -1,14 +1,17 @@
.. _gif:
===========
GIF decoder
===========
Allow using GIF images in LVGL. Based on
https://github.com/lecram/gifdec
Allow using GIF images in LVGL.
Detailed introduction: `GIFdec <https://github.com/lecram/gifdec>`__
When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_GIF`
:c: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.
:c:expr:`lv_gif_set_src(obj, src)` works very similarly to :c:func:`lv_image_set_src`.
:cpp:expr:`lv_gif_set_src(obj, src)` works very similarly to :cpp:func:`lv_image_set_src`.
As source, it also accepts images as variables (:c:struct:`lv_image_dsc_t`) or
files.
@ -29,7 +32,7 @@ For example:
lv_gif_set_src(obj, "S:path/to/example.gif");
Note that, a file system driver needs to be registered to open images
from files. Read more about it :ref:`file-system` or just
from files. Read more about it :ref:`overview_file_system` or just
enable one in ``lv_conf.h`` with ``LV_USE_FS_...``
Memory requirements
@ -42,11 +45,15 @@ required:
- :c:macro:`LV_COLOR_DEPTH` ``16``: 4 x image width x image height
- :c:macro:`LV_COLOR_DEPTH` ``32``: 5 x image width x image height
.. _gif_example:
Example
-------
.. include:: ../examples/libs/gif/index.rst
.. _gif_api:
API
---

2
docs/libs/index.rst
View File

@ -1,3 +1,5 @@
.. _3rd_party_libraries:
===================
3rd party libraries
===================

19
docs/libs/libjpeg_turbo.rst
View File

@ -1,10 +1,15 @@
.. _libjpeg:
=====================
libjpge-turbo decoder
libjpeg-turbo decoder
=====================
libjpeg-turbo is a JPEG image codec that uses SIMD instructions to accelerate baseline JPEG compression and decompression on x86,
`libjpeg-turbo <https://libjpeg-turbo.org/>`__ 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: `libjpeg-turbo <https://github.com/libjpeg-turbo/libjpeg-turbo>`__
.. _libjpeg_install:
Install
-------
@ -22,6 +27,8 @@ Add libjpge-turbo to your project
include_directories(${JPEG_INCLUDE_DIR})
target_link_libraries(${PROJECT_NAME} PRIVATE ${JPEG_LIBRARIES})
.. _libjpeg_usage:
Usage
-----
@ -29,13 +36,17 @@ Enable :c:macro:`LV_USE_LIBJEPG_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:`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:
Example
-------
.. include:: ../examples/libs/libjpeg_turbo/index.rst
.. _libjpeg_api:
API
---

16
docs/libs/libpng.rst
View File

@ -1,9 +1,12 @@
.. _libpng:
==============
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: `libpng <http://www.libpng.org/pub/png/libpng.html>`__
Install
-------
@ -21,20 +24,27 @@ Add libpng to your project
include_directories(${PNG_INCLUDE_DIR})
target_link_libraries(${PROJECT_NAME} PRIVATE ${PNG_LIBRARIES})
.. _libpng_usage:
Usage
-----
Enable :c:macro:`LV_USE_LIBPNG` 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 4`` bytes of RAM,
and it needs to be combined with the ref:`image-caching` feature to ensure that the memory usage is within a reasonable range.
It should be noted that each image of this decoder needs to consume ``width x height x 4`` 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.
The decoded image is stored in RGBA pixel format.
.. _libpng_example:
Example
-------
.. include:: ../examples/libs/libpng/index.rst
.. _libpng_api:
API
---

39
docs/libs/lodepng.rst
View File

@ -1,28 +1,51 @@
.. _lodepng:
===============
LODEPNG decoder
LodePNG decoder
===============
Allow the use of PNG images in LVGL. This implementation uses
`lodepng <https://github.com/lvandeve/lodepng>`__ library.
Allow the use of PNG images in LVGL.
Detailed introduction: `lodepng <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 registered to open images from
files. Read more about it :ref:`file-system` or just
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_...``
The whole PNG image is decoded so during decoding RAM equals to
``image width x image height x 4`` bytes are required.
The whole PNG image is decoded, so ``width x height x 4`` bytes free RAM space is required.
The decoded image is stored in RGBA pixel format.
As it might take significant time to decode PNG images LVGL's :ref:`image-caching` feature can be useful.
As it might take significant time to decode PNG images LVGL's :ref:`overview_image_caching` feature can be useful.
Compress PNG files
------------------
PNG file format supports True color (24/32 bit), and 8-bit palette colors.
Usually cliparts, drawings, icons and simple graphics are stored in PNG format,
that do not use the whole color space, so it is possible to compress further
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/
.. _lodepng_example:
Example
-------
.. include:: ../examples/libs/lodepng/index.rst
.. _lodepng_api:
API
---

17
docs/libs/qrcode.rst
View File

@ -1,3 +1,5 @@
.. _qrcode:
=======
QR code
=======
@ -6,17 +8,20 @@ QR code generation with LVGL. Uses
`QR-Code-generator <https://github.com/nayuki/QR-Code-generator>`__ by
`nayuki <https://github.com/nayuki>`__.
.. _qrcode_usage:
Usage
-----
Enable :c:macro:`LV_USE_QRCODE` in ``lv_conf.h``.
Use :c:expr:`lv_qrcode_create()` to create a qrcode object, and use
:c:expr:`lv_qrcode_update()` to generate a QR code.
Use :cpp:func:`lv_qrcode_create` to create a qrcode object, and use
:cpp:func:`lv_qrcode_update` to generate a QR code.
If you need to re-modify the size and color, use
:c:expr:`lv_qrcode_set_size()` and :c:expr:`lv_qrcode_set_dark/light_color()`, and
call :c:expr:`lv_qrcode_update()` again to regenerate the QR code.
:cpp:func:`lv_qrcode_set_size` and :cpp:func:`lv_qrcode_set_dark_color` or
:cpp:func:`lv_qrcode_set_light_color`, and
call :cpp:func:`lv_qrcode_update` again to regenerate the QR code.
Notes
-----
@ -24,11 +29,15 @@ Notes
- QR codes with less data are smaller, but they scaled by an integer
number to best fit to the given size.
.. _qrcode_example:
Example
-------
.. include:: ../examples/libs/qrcode/index.rst
.. _qrcode_api:
API
---

10
docs/libs/rle.rst
View File

@ -1,5 +1,8 @@
.. _rle:
============
RLE Compress
===========
============
LVGL provides a custom RLE compression method. It can be used to reduce binary
image size. The RLE compression is a lossless compression method.
@ -29,7 +32,7 @@ the for many pixels, the color is the same. The algorithm simply counts how many
repeated data are there and store the count value and the color value.
If the coming pixels are not repeated, it stores the non-repeat count value and
original color value. For more details, the script used to compress the image
can be found from `lvgl/script/LVGLImage.py`.
can be found from ``lvgl/script/LVGLImage.py``.
.. code:: python
@ -60,11 +63,12 @@ can be found from `lvgl/script/LVGLImage.py`.
return b"".join(compressed_data)
.. _rle_usage:
Usage
-----
To use the RLE Decoder, ensure that `LV_USE_RLE` is defined and set to `1`.
To use the RLE Decoder, enable it in ``lv_conf.h`` configuration file by setting :c:macro:`LV_USE_RLE` to `1`.
The RLE image can be used same as other images.
.. code:: c

54
docs/libs/rlottie.rst
View File

@ -1,8 +1,10 @@
.. _rlottie:
=============
Lottie player
=============
Allows to use Lottie animations in LVGL. Taken from this `base repository <https://github.com/ValentiWorkLearning/lv_rlottie>`__
Allows playing Lottie animations in LVGL. Taken from `lv_rlottie <https://github.com/ValentiWorkLearning/lv_rlottie>`__.
LVGL provides the interface to `Samsung/rlottie <https://github.com/Samsung/rlottie>`__ library's C
API. That is the actual Lottie player is not part of LVGL, it needs to
@ -37,6 +39,8 @@ given build system.
ESP-IDF example at bottom
~~~~~~~~~~~~~~~~~~~~~~~~~
.. _rlottie_usage:
Usage
-----
@ -62,9 +66,11 @@ Use Rlottie from raw string data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lv_example_rlottie_approve.c`` contains an example animation in raw
format. Instead storing the JSON string a hex array is stored for the
following reasons: - avoid escaping ``"`` in the JSON file - some
compilers don't support very long strings
format. Instead storing the JSON string, a hex array is stored for the
following reasons:
- avoid escaping ``"`` 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
array. E.g.:
@ -93,7 +99,7 @@ Controlling animations
----------------------
LVGL provides two functions to control the animation mode:
:c:func:`lv_rlottie_set_play_mode` and :c:func:`lv_rlottie_set_current_frame`.
:cpp:func:`lv_rlottie_set_play_mode` and :cpp:func:`lv_rlottie_set_current_frame`.
You'll combine your intentions when calling the first method, like in
these examples:
@ -113,7 +119,7 @@ these examples:
The default animation mode is **play forward with loop**.
If you don't enable looping, a :c:enumerator:`LV_EVENT_READY` is sent when the
If you don't enable looping, a :cpp:enumerator:`LV_EVENT_READY` is sent when the
animation can not make more progress without looping.
To get the number of frames in an animation or the current frame index,
@ -129,9 +135,11 @@ Background
Rlottie can be expensive to render on embedded hardware. Lottie
animations tend to use a large amount of CPU time and can use large
portions of RAM. This will vary from lottie to lottie but in general for
best performance: \* Limit total # of frames in the animation \* Where
possible, try to avoid bezier type animations \* Limit animation render
size
best performance:
- Limit total # of frames in the animation
- Where possible, try to avoid bezier type animations
- Limit animation render size
If your ESP32 chip does not have SPIRAM you will face severe limitations
in render size.
@ -163,13 +171,14 @@ wonderful utility to LVGL on embedded LCDs and can look really good when
done properly.
When picking/designing a lottie animation consider the following
limitations: - Build the lottie animation to be sized for the intended
size - it can scale/resize, but performance will be best when the base
lottie size is as intended - Limit total number of frames, the longer
the lottie animation is, the more memory it will consume for rendering
(rlottie consumes IRAM for rendering) - Build the lottie animation for
the intended frame rate - default lottie is 60fps, embedded LCDs likely
won't go above 30fps
limitations:
- Build the lottie animation to be sized for the intended size
- it can scale/resize, but performance will be best when the base lottie size is as intended
- Limit total number of frames, the longer the lottie animation is,
the more memory it will consume for rendering (rlottie consumes IRAM for rendering)
- Build the lottie animation for the intended frame rate
- default lottie is 60fps, embedded LCDs likely won't go above 30fps
IDF Setup
~~~~~~~~~
@ -243,13 +252,13 @@ The Esp-box devkit meets this spec and
https://github.com/espressif/esp-box is a great starting point to adding
lottie animations.
you'll need to enable:c:macro:`LV_USE_RLOTTIE` through idf.py menuconfig under
You will need to enable :c:macro:`LV_USE_RLOTTIE` through **idf.py** menuconfig under
LVGL component settings.
Additional changes to make use of SPIRAM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
lv_alloc/realloc do not make use of SPIRAM. Given the high memory usage
:cpp:expr:`lv_alloc/realloc` do not make use of SPIRAM. Given the high memory usage
of lottie animations, it is recommended to shift as much out of internal
DRAM into SPIRAM as possible. In order to do so, SPIRAM will need to be
enabled in the menuconfig options for your given espressif chip.
@ -257,19 +266,22 @@ enabled in the menuconfig options for your given espressif chip.
There may be a better solution for this, but for the moment the
recommendation is to make local modifications to the lvgl component in
your espressif project. This is as simple as swapping
lv_alloc/lv_realloc calls in lv_rlottie.c with heap_caps_malloc (for
IDF) with the appropriate :c:expr:`MALLOC_CAP` call - for SPIRAM usage this is
:c:expr:`MALLOC_CAP_SPIRAM`.
:cpp:expr:`lv_alloc/lv_realloc` calls in `lv_rlottie.c`` with :cpp:expr:`heap_caps_malloc` (for
IDF) with the appropriate :cpp:expr:`MALLOC_CAP` call - for SPIRAM usage this is
:cpp:expr:`MALLOC_CAP_SPIRAM`.
.. code:: c
rlottie->allocated_buf = heap_caps_malloc(allocated_buf_size+1, MALLOC_CAP_SPIRAM);
.. _rlottie_example:
Example
-------
.. include:: ../examples/libs/rlottie/index.rst
.. _rlottie_api:
API
---

23
docs/libs/tiny_ttf.rst
View File

@ -1,15 +1,20 @@
.. _tiny_ttf:
====================
Tiny TTF font engine
====================
.. _tiny_ttf_usage:
Usage
-----
Allow using TrueType fonts LVGL. Based on
https://github.com/nothings/stb
Allow using TrueType fonts LVGL.
Detailed introduction: `stb <https://github.com/nothings/stb>`__
When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_TINY_TTF`
:c: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
create a TTF font instance at the specified line height. You can then
use that font anywhere :c:struct:`lv_font_t` is accepted.
@ -17,24 +22,28 @@ By default, the TTF or OTF file must be embedded as an array, either in
a header, or loaded into RAM in order to function.
However, if :c:macro:`LV_TINY_TTF_FILE_SUPPORT` is enabled,
:c:expr:`lv_tiny_ttf_create_file(path, font_size)` will also be available,
:cpp:expr:`lv_tiny_ttf_create_file(path, font_size)` will also be available,
allowing tiny_ttf to stream from a file. The file must remain open the
entire time the font is being used.
After a font is created, you can change the font size in pixels by using
:c:expr:`lv_tiny_ttf_set_size(font, font_size)`.
:cpp:expr:`lv_tiny_ttf_set_size(font, font_size)`.
By default, a font will use up to 4KB of cache to speed up rendering
glyphs. This maximum can be changed by using
:c:expr:`lv_tiny_ttf_create_data_ex(data, data_size, font_size, cache_size)`
or :c:expr:`lv_tiny_ttf_create_file_ex(path, font_size, cache_size)` (when
:cpp:expr:`lv_tiny_ttf_create_data_ex(data, data_size, font_size, cache_size)`
or :cpp:expr:`lv_tiny_ttf_create_file_ex(path, font_size, cache_size)` (when
available). The cache size is indicated in bytes.
.. _tiny_ttf_example:
Example
-------
.. include:: ../examples/libs/tiny_ttf/index.rst
.. _tiny_ttf_api:
API
---

21
docs/libs/tjpgd.rst
View File

@ -1,17 +1,27 @@
=============
TJPGD decoder
=============
.. _tjpgd:
================================
Tiny JPEG Decompressor (TJpgDec)
================================
TJpgDec - Tiny JPEG Decompressor.
Allow the use of JPG (JPEG) images in LVGL.
Detailed introduction: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__
.. _tjpgd_overview:
Overview
--------
- JPG is decoded in 8x8 tiles.
- Only baseline JPG files are supported (no progressive JPG support).
- Read from file and C array are implemented.
- Only the required portions of the JPG images are decoded,
therefore they can't be zoomed or rotated.
.. _tjpgd_usage:
Usage
-----
@ -24,7 +34,7 @@ as image sources. For example:
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:`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_...``
Converter
@ -36,11 +46,14 @@ Converting JPG to C array
- Use lvgl online tool https://lvgl.io/tools/imageconverter
- Color format = RAW, output format = C Array
.. _tjpgd_example:
Example
-------
.. include:: ../examples/libs/tjpgd/index.rst
.. _tjpgd_api:
API
---

249
docs/others/file_explorer.rst
View File

@ -1,3 +1,5 @@
.. _file_explorer:
=============
File Explorer
=============
@ -11,86 +13,22 @@ currently clicked file. The file operation function needs to be
implemented by the user.
The file list in ``lv_file_explorer`` is based on
`lv_table </widgets/table>`__, and the quick access bar is based on
`lv_list </widgets/list>`__. Therefore, care should be taken to ensure
that `lv_table </widgets/table>`__ and `lv_list </widgets/list>`__ are
:ref:`lv_table`, and the quick access bar is based on
:ref:`lv_list`. Therefore, care should be taken to ensure
that :ref:`lv_table` and :ref:`lv_list` are
enabled.
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
``lv_file_explorer``
提供API让我们可以浏览文件系统中的内容。\ ``lv_file_explorer``
只提供了文件浏览功能，并不提供实际的文件操作功能，也就是说，不能像PC那样点击一个图片文件就可以打开查看该图片。\ ``lv_file_explorer``
会告诉您当前点击的文件的完整路径和名称，文件操作功能需要用户自己实现。
``lv_file_explorer`` 中的文件列表基于 `lv_table </widgets/table>`__
实现，快速访问栏基于 `lv_list </widgets/list>`__
实现。因此，要注意确保使能了 ``lv_table`` 和 ``lv_list``\ 。
.. raw:: html
</p>
.. raw:: html
</details>
.. _file_explorer_usage:
Usage
-----
Enable :c:macro:`LV_USE_FILE_EXPLORER` in ``lv_conf.h``.
First use :c:expr:`lv_file_explorer_create(lv_screen_active())` to create a file
First use :cpp:expr:`lv_file_explorer_create(lv_screen_active())` to create a file
explorer, The default size is the screen size. After that, you can
customize the style like widget.
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
在 ``lv_conf.h`` 中打开 :c:macro:`LV_USE_FILE_EXPLORER`\ 。
首先，使用 :c:expr:`lv_file_explorer_create(lv_screen_active())`
函数创建一个文件浏览器，默认大小为屏幕大小，之后可以像组件那样自定义样式。
.. raw:: html
</p>
.. raw:: html
</details>
Quick access
~~~~~~~~~~~~
@ -102,121 +40,46 @@ button at the top left corner of the browsing area, which is very useful
for small screen devices.
You can use
:c:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")`
:cpp:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")`
to set the path of the quick access bar. The items of the quick access
bar are fixed. Currently, there are the following items:
- :c:enumerator:`LV_FILE_EXPLORER_QA_HOME`
- :c:enumerator:`LV_FILE_EXPLORER_QA_MUSIC`
- :c:enumerator:`LV_FILE_EXPLORER_QA_PICTURES`
- :c:enumerator:`LV_FILE_EXPLORER_QA_VIDEO`
- :c:enumerator:`LV_FILE_EXPLORER_QA_DOCS`
- :c:enumerator:`LV_FILE_EXPLORER_QA_MNT`
- :c:enumerator:`LV_FILE_EXPLORER_QA_FS`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_HOME`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_MUSIC`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_PICTURES`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_VIDEO`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_DOCS`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_MNT`
- :cpp:enumerator:`LV_FILE_EXPLORER_QA_FS`
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
快速访问栏是可选的，您可以在 ``lv_conf.h`` 中关闭
:c:macro:`LV_FILE_EXPLORER_QUICK_ACCESS`\ ，这样快速访问栏就不会被创建出来，这能节省一些内存，但并不是很多。快速访问栏被创建出来之后，可以通过点击浏览区域顶部左上角的按钮隐藏起来，这对于小屏幕设备非常有用。
可以通过
:c:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")`
设置快速访问栏的路径，快速访问栏的项目是固定的，目前有以下项目：
- :c:enumerator:`LV_FILE_EXPLORER_QA_HOME`
- :c:enumerator:`LV_FILE_EXPLORER_QA_MUSIC`
- :c:enumerator:`LV_FILE_EXPLORER_QA_PICTURES`
- :c:enumerator:`LV_FILE_EXPLORER_QA_VIDEO`
- :c:enumerator:`LV_FILE_EXPLORER_QA_DOCS`
- :c:enumerator:`LV_FILE_EXPLORER_QA_MNT`
- :c:enumerator:`LV_FILE_EXPLORER_QA_FS`
.. raw:: html
</p>
.. raw:: html
</details>
.. _file_explorer_sort:
Sort
~~~~
You can use
:c: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:
- :c:enumerator:`LV_EXPLORER_SORT_NONE`
- :c:enumerator:`LV_EXPLORER_SORT_KIND`
- :cpp:enumerator:`LV_EXPLORER_SORT_NONE`
- :cpp:enumerator:`LV_EXPLORER_SORT_KIND`
You can customize the sorting. Before custom sort, please set the
default sorting to :c:enumerator:`LV_EXPLORER_SORT_NONE`. The default is
:c:enumerator:`LV_EXPLORER_SORT_NONE`.
default sorting to :cpp:enumerator:`LV_EXPLORER_SORT_NONE`. The default is
:cpp:enumerator:`LV_EXPLORER_SORT_NONE`.
.. raw:: html
.. _file_explorer_events:
<details>
Events
------
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
可以通过
:c:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)`
设置排序方式，有以下排序方式：
- :c:enumerator:`LV_EXPLORER_SORT_NONE`
- :c:enumerator:`LV_EXPLORER_SORT_KIND`
您可以自定义排序规则，在这之前请先将排序规则设置为
:c:enumerator:`LV_EXPLORER_SORT_NONE` 然后在 :c:enumerator:`LV_EVENT_READY`
事件中处理。默认的排序规则是 :c:enumerator:`LV_EXPLORER_SORT_NONE`
.. raw:: html
</p>
.. raw:: html
</details>
Event
-----
- :c: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.
- :c: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 :c:func:`lv_file_explorer_get_cur_path` to get the current path
and :c:func:`lv_file_explorer_get_sel_fn` to get the name of the currently
You can use :cpp:func:`lv_file_explorer_get_cur_path` to get the current path
and :cpp:func:`lv_file_explorer_get_sel_fn` to get the name of the currently
selected file in the event processing function. For example:
.. code:: c
@ -234,65 +97,17 @@ selected file in the event processing function. For example:
}
You can also save the obtained **path** and **file** name into an array
through functions such as *strcpy* and *strcat* for later use.
through functions such as :cpp:func:`strcpy` and :cpp:func:`strcat` for later use.
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
- 当打开一个目录后会发送 :c:enumerator:`LV_EVENT_READY`
事件。您可以在这里自定义排序规则。
- 当文件列表中的项目（文件）被点击时会发送 :c:enumerator:`LV_EVENT_VALUE_CHANGED`
事件。
可以在事件处理函数中通过 :c:func:`lv_file_explorer_get_cur_path`
获取当前所在的路径，通过 :c:func:`lv_file_explorer_get_sel_fn`
获取当前选中的文件的名称。比如：
.. code:: c
static void file_explorer_event_handler(lv_event_t * e)
{
lv_event_code_t code = lv_event_get_code(e);
lv_obj_t * obj = lv_event_get_target(e);
if(code == LV_EVENT_VALUE_CHANGED) {
char * cur_path = lv_file_explorer_get_cur_path(obj);
char * sel_fn = lv_file_explorer_get_sel_fn(obj);
LV_LOG_USER("%s%s", cur_path, sel_fn);
}
}
您还可以将获取到的 **路径** 和 **文件名称** 通过例如 strcpy 和 strcat
函数保存到一个数组中，方便后续使用。
.. raw:: html
</p>
.. raw:: html
</details>
.. _file_explorer_example:
Example
-------
.. include:: ../examples/others/file_explorer/index.rst
.. _file_explorer_api:
API
---

8
docs/others/fragment.rst
View File

@ -1,3 +1,5 @@
.. _fragment:
========
Fragment
========
@ -20,6 +22,8 @@ to it, and has an internal stack to achieve navigation. You can use
fragment manager to build navigation stack, or multi pane application
easily.
.. _fragment_usage:
Usage
-----
@ -69,11 +73,15 @@ Fragment Based Navigation
/* Remove the top most fragment from the stack, and bring back previous one. */
lv_fragment_manager_pop(manager);
.. _fragment_example:
Example
-------
.. include:: ../examples/others/fragment/index.rst
.. _fragment_api:
API
---

26
docs/others/gridnav.rst
View File

@ -1,3 +1,5 @@
.. _gridnav:
===============
Grid navigation
===============
@ -24,43 +26,51 @@ gridnav is focused, the arrow key presses are automatically forwarded to
the object so that gridnav can process the arrow keys.
To move the focus to the next widget of the group use
:c:expr:`LV_KEY_NEXT/PREV` or :c:expr:`lv_group_focus_next/prev()` or the ``TAB``
:cpp:enumerator:`LV_KEY_NEXT` or :cpp:enumerator:`LV_KEY_PREV`.
Optionally you can also use :cpp:func:`lv_group_focus_next`
or :cpp:func:`lv_group_focus_prev` or the ``TAB``
key on keyboard as usual.
If the container is scrollable and the focused child is out of the view,
gridnav will automatically scroll the child into view.
.. _gridnav_usage:
Usage
-----
To add the gridnav feature to an object use
:c:expr:`lv_gridnav_add(cont, flags)`.
:cpp:expr:`lv_gridnav_add(cont, flags)`.
``flags`` control the behavior of gridnav:
- :c:enumerator:`LV_GRIDNAV_CTRL_NONE`: Default settings
- :c:enumerator:`LV_GRIDNAV_CTRL_ROLLOVER`: If there is no next/previous object in a
- :cpp:enumerator:`LV_GRIDNAV_CTRL_NONE`: Default settings
- :cpp:enumerator:`LV_GRIDNAV_CTRL_ROLLOVER`: If there is no next/previous object in a
direction, the focus goes to the object in the next/previous row (on
left/right keys) or first/last row (on up/down keys)
- :c:enumerator:`LV_GRIDNAV_CTRL_SCROLL_FIRST`: If an arrow is pressed and the focused
- :cpp:enumerator:`LV_GRIDNAV_CTRL_SCROLL_FIRST`: If an arrow is pressed and the focused
object can be scrolled in that direction then it will be scrolled instead of
going to the next/previous object. If there is no more room for scrolling the
next/previous object will be focused normally
:c:expr:`lv_gridnav_remove(cont)` Removes gridnav from an object.
:cpp:expr:`lv_gridnav_remove(cont)` Removes gridnav from an object.
Focusable objects
-----------------
An object needs to be clickable or click focusable
(:c:enumerator:`LV_OBJ_FLAG_CLICKABLE` or :c:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE`) and not
hidden (:c:enumerator:`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav.
(:cpp:enumerator:`LV_OBJ_FLAG_CLICKABLE` or :cpp:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE`) and not
hidden (:cpp:enumerator:`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav.
.. _gridnav_example:
Example
-------
.. include:: ../examples/others/gridnav/index.rst
.. _gridnav_api:
API
---

231
docs/others/ime_pinyin.rst
View File

@ -1,3 +1,5 @@
.. _ime_pinyin:
==========
Pinyin IME
==========
@ -7,52 +9,22 @@ input) for keyboard object, which supports 26 key and 9 key input modes.
You can think of ``lv_ime_pinyin`` as a Pinyin input method plug-in for
keyboard objects.
Normally, an environment where `lv_keyboard </widgets/keyboard>`__ can
Normally, an environment where :ref:`lv_keyboard` can
run can also run ``lv_ime_pinyin``. There are two main influencing
factors: the size of the font file and the size of the dictionary.
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
``lv_ime_pinyin``\ 为\ `键盘 </widgets/keyboard>`__\ 组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)，支持26键和9键输入模式。您可以将
``lv_ime_pinyin`` 看成是键盘组件的汉语拼音输入法插件。
一般情况下，只要是\ `键盘 </widgets/keyboard>`__\ 组件能运行的环境
``lv_ime_pinyin`` 也能运行。有两个影响因素：字库的大小和词库的大小。
.. raw:: html
</p>
.. raw:: html
</details>
.. _ime_pinyin_example:
Usage
-----
Enable :c:macro:`LV_USE_IME_PINYIN` in ``lv_conf.h``.
First use :c:expr:`lv_ime_pinyin_create(lv_screen_active())` to create a Pinyin
First use :cpp:expr:`lv_ime_pinyin_create(lv_screen_active())` to create a Pinyin
input method plug-in, then use
:c:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the ``keyboard``
:cpp:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the ``keyboard``
you created to the Pinyin input method plug-in. You can use
:c:expr:`lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` to use a custom
:cpp:expr:`lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` to use a custom
dictionary (if you don't want to use the built-in dictionary at first,
you can disable :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` in ``lv_conf.h``,
which can save a lot of memory space).
@ -65,48 +37,6 @@ custom fonts and thesaurus.
In the process of using the Pinyin input method plug-in, you can change
the keyboard and dictionary at any time.
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
在 ``lv_conf.h`` 中打开 :c:macro:`LV_USE_IME_PINYIN`\ 。
首先，使用 :c:expr:`lv_ime_pinyin_create(lv_screen_active())`
函数创建一个拼音输入法插件， 然后使用
:c:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)`
函数将您创建的键盘组件添加到插件中。
内置的词库是基于 LVGL 的 **LV_FONT_SIMSUN_16_CJK**
字库定制，这个字库目前只有 ``1000`` 多个最常见的 CJK
部首，所以建议使用自定义字库和词库。
您可以使用 :c:expr:`lv_ime_pinyin_set_dict(pinyin_ime, your_dict)`
函数来设置使用自定义的词库，如果您一开始就不打算使用内置的词库，建议您在
``lv_conf.h`` 中将 :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT`
关闭，这可以节省一些内存空间。
.. raw:: html
</p>
.. raw:: html
</details>
Custom dictionary
-----------------
@ -120,37 +50,6 @@ First, set :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` to ``0`` in ``lv_conf.h``
Then, write a dictionary in the following format.
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
如果您不想使用内置的词库，可以通过下面的方法自定义词库。
自定义词典非常简单。 首先，在 ``lv_conf.h`` 将
:c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` 设置为 0。
然后按照下面的格式编写词库。
.. raw:: html
</p>
.. raw:: html
</details>
Dictionary format
~~~~~~~~~~~~~~~~~
@ -163,36 +62,6 @@ to learn about the Hanyu Pinyin syllables and the syllable table.
Then, write your own dictionary according to the following format:
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
**注意**\ ，各个拼音音节的排列顺序非常重要，您需要按照汉语拼音音节表定制自己的词库，可以阅读\ `这里 <https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981>`__\ 了解\ `汉语拼音音节 <https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981>`__\ 以及\ `音节表 <https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981#1>`__\ 。
然后，根据下面的格式编写自己的词库：
.. raw:: html
</p>
.. raw:: html
</details>
.. code:: c
lv_100ask_pinyin_dict_t your_pinyin_dict[] = {
@ -207,107 +76,47 @@ Then, write your own dictionary according to the following format:
{ "zuo", "昨左佐做作坐座撮琢柞"},
{NULL, NULL}
**The last item** must end with ``{null, null}`` , or it will not work
**The last item** must end with ``{null, null}``, or it will not work
properly.
.. _ime_pinyin_apply_new_dictionary:
Apply new dictionary
~~~~~~~~~~~~~~~~~~~~
After writing a dictionary according to the above dictionary format, you
only need to call this function to set up and use your dictionary:
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
按照上面的词库格式编写好自己的词库之后，参考下面的用法，调用
:c:expr:`lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict)`
函数即可设置和使用新词库：
.. raw:: html
</p>
.. raw:: html
</details>
.. code:: c
lv_obj_t * pinyin_ime = lv_100ask_pinyin_ime_create(lv_screen_active());
lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict);
.. _ime_pinyin_modes:
Modes
-----
The lv_ime_pinyin have the following modes:
- :c:enumerator:`LV_IME_PINYIN_MODE_K26`: Pinyin 26 key input mode
- :c:enumerator:`LV_IME_PINYIN_MODE_K9`: Pinyin 9 key input mode
- :c:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: Numeric keypad mode
- :cpp:enumerator:`LV_IME_PINYIN_MODE_K26`: Pinyin 26 key input mode
- :cpp:enumerator:`LV_IME_PINYIN_MODE_K9`: Pinyin 9 key input mode
- :cpp:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: Numeric keypad mode
The ``TEXT`` modes' layout contains buttons to change mode.
To set the mode manually, use
:c:expr:`lv_ime_pinyin_set_mode(pinyin_ime, mode)` . The default mode is
:c:enumerator:`LV_IME_PINYIN_MODE_K26` .
To set the mode manually, use :cpp:expr:`lv_ime_pinyin_set_mode(pinyin_ime, mode)`.
The default mode is :cpp:enumerator:`LV_IME_PINYIN_MODE_K26`.
.. raw:: html
<details>
.. raw:: html
<summary>
中文
.. raw:: html
</summary>
.. raw:: html
<p>
lv_ime_pinyin 有以下模式：
- :c:enumerator:`LV_IME_PINYIN_MODE_K26`: 拼音26键
- :c:enumerator:`LV_IME_PINYIN_MODE_K9`: 拼音9键(九宫格)
- :c:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: 九宫格布局的数字键盘
每个模式的布局中都包含有更改到其他模式的按钮。
您可以通过 :c:expr:`lv_keyboard_set_mode(kb, mode)`
函数手动设置模式。默认的模式是 :c:enumerator:`LV_IME_PINYIN_MODE_K26` 。
.. raw:: html
</p>
.. raw:: html
</details>
.. _ime_pinyin_example:
Example
-------
.. include:: ../examples/others/ime/index.rst
.. _ime_pinyin_api:
API
---

35
docs/others/imgfont.rst
View File

@ -1,28 +1,41 @@
====================
Image font (imgfont)
====================
.. _lv_imgfont:
Draw image in label or span obj with imgfont. This is often used to
display Unicode emoji icons in text. Supported image formats: determined
by LVGL image decoder.
=======================
Image font (lv_imgfont)
=======================
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.
.. _lv_imgfont_usage:
Usage
-----
Enable :c:macro:`LV_USE_IMGFONT` in ``lv_conf.h``.
To create a new imgfont use :c:expr:`lv_imgfont_create(height, path_cb)`.
To create a new *imgfont* use :cpp:expr:`lv_imgfont_create(height, path_cb, user_data)`.
``height`` used to indicate the size of a imgfont. ``path_cb`` Used to
get the image path of the specified unicode.
- ``height`` Font size.
- ``path_cb`` A function to get the image path of a character.
Return ``NULL`` if no image should be shown, but the character itself.
- ``user_data`` Pointer to user data.
Use :c:expr:`lv_imgfont_destroy(imgfont)` to destroy a imgfont that is no
longer used.
To use the *imgfont* in a label, reference it:
:cpp:expr:`lv_obj_set_style_text_font(label, imgfont, LV_PART_MAIN)`
To destroy the *imgfont* that is no longer used, use :cpp:expr:`lv_imgfont_destroy(imgfont)`.
.. _lv_imgfont_example:
Example
-------
.. include:: ../examples/others/imgfont/index.rst
.. _lv_imgfont_api:
API
---

2
docs/others/index.rst
View File

@ -1,3 +1,5 @@
.. _others:
======
Others
======

28
docs/others/monkey.rst
View File

@ -1,9 +1,13 @@
.. _monkey:
======
Monkey
======
A simple monkey test. Use random input to stress test the application.
.. _monkey_usage:
Usage
-----
@ -13,27 +17,31 @@ First configure monkey, use :c:struct:`lv_monkey_config_t` to define the
configuration structure, set the ``type`` (check `input devices </overview/indev>`__ for the supported types), and then set the
range of ``period_range`` and ``input_range``, the monkey will output
random operations at random times within this range. Call
:c:func:`lv_monkey_create` to create monkey. Finally call
:c:expr:`lv_monkey_set_enable(monkey, true)` to enable monkey.
:cpp:func:`lv_monkey_create` to create monkey. Finally call
:cpp:expr:`lv_monkey_set_enable(monkey, true)` to enable monkey.
If you want to pause the monkey, call
:c:expr:`lv_monkey_set_enable(monkey, false)`. To delete the monkey, call
:c:expr:`lv_monkey_delete(monkey)`.
:cpp:expr:`lv_monkey_set_enable(monkey, false)`. To delete the monkey, call
:cpp:expr:`lv_monkey_delete(monkey)`.
Note that ``input_range`` has different meanings in different ``type``:
- :c:enumerator:`LV_INDEV_TYPE_POINTER`: No effect, click randomly within the pixels of the screen resolution.
- :c:enumerator:`LV_INDEV_TYPE_ENCODER`: The minimum and maximum values of ``enc_diff``.
- :c:enumerator:`LV_INDEV_TYPE_BUTTON`: The minimum and maximum values of ``btn_id``.
Use :c:expr:`lv_monkey_get_indev()` to get the input device, and use
:c:expr:`lv_indev_set_button_points()` to map the key ID to the coordinates.
- :c:enumerator:`LV_INDEV_TYPE_KEYPAD`: No effect, Send random :ref:`indev_keys`.
- :cpp:enumerator:`LV_INDEV_TYPE_POINTER`: No effect, click randomly within the pixels of the screen resolution.
- :cpp:enumerator:`LV_INDEV_TYPE_ENCODER`: The minimum and maximum values of ``enc_diff``.
- :cpp:enumerator:`LV_INDEV_TYPE_BUTTON`: The minimum and maximum values of ``btn_id``.
Use :cpp:func:`lv_monkey_get_indev` to get the input device, and use
:cpp:func:`lv_indev_set_button_points` to map the key ID to the coordinates.
- :cpp:enumerator:`LV_INDEV_TYPE_KEYPAD`: No effect, Send random :ref:`indev_keys`.
.. _monkey_example:
Example
-------
.. include:: ../examples/others/monkey/index.rst
.. _monkey_api:
API
---

30
docs/others/obj_id.rst
View File

@ -1,28 +1,32 @@
.. _obj_id:
======
OBJ ID
======
LVGL provides an optional field in `lv_obj_t` to store the object ID.
LVGL provides an optional field in :cpp:type:`lv_obj_t` to store the object ID.
Object ID can be used in many cases, for example, to identify the object.
Or we can store a program backtrace to where the object is created.
.. _obj_id_usage:
Usage
-----
Enable this feature by setting ``LV_USE_OBJ_ID`` to 1 in `lv_conf.h`.
Use the builtin obj ID generator by setting ``LV_USE_OBJ_ID_BUILTIN`` to 1.
Enable this feature by setting :c:macro:`LV_USE_OBJ_ID` to `1` in ``lv_conf.h``.
Use the builtin obj ID generator by setting :c:macro:`LV_USE_OBJ_ID_BUILTIN` to `1`.
Otherwise provide your own custom implementation.
The ID is automatically generated and assigned to `obj->id` during obj's
construction by calling API `lv_obj_assign_id(obj)` from ``lv_obj_constructor``.
The ID is automatically generated and assigned to :cpp:expr:`obj->id` during obj's
construction by calling API :cpp:expr:`lv_obj_assign_id(obj)` from :cpp:func:`lv_obj_constructor`.
You can directly access the ID by `obj->id` or use API ``lv_obj_stringify_id(obj, buf, len)``
You can directly access the ID by :cpp:expr:`obj->id` or use API :cpp:expr:`lv_obj_stringify_id(obj, buf, len)`
to get a string representation of the ID.
Use custom ID generator
~~~~~~~~~~~~~~~~~~~~~~~
Set `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``. Below APIs needed to be implemented and
linked to lvgl.
.. code:: c
@ -32,21 +36,21 @@ linked to lvgl.
const char * lv_obj_stringify_id(lv_obj_t * obj, char * buf, uint32_t len);
:c:func:``lv_obj_assign_id`` is called when an object is created. The object final class is passed from
parameter ``class_p``. Note it may be different than ``obj->class_p`` which is the class
:cpp:func:`lv_obj_assign_id` is called when an object is created. The object final class is passed from
parameter ``class_p``. Note it may be different than :cpp:expr:`obj->class_p` which is the class
currently being constructed.
:c:func:``lv_obj_free_id`` is called when object is deconstructed. Free any resource allocated in ``lv_obj_assign_id``.
:cpp:func:`lv_obj_free_id` is called when object is deconstructed. Free any resource allocated in :cpp:func:`lv_obj_assign_id`.
:c:func:``lv_obj_stringify_id`` converts id to a string representation. The string is stored in ``buf``.
:cpp:func:`lv_obj_stringify_id` converts id to a string representation. The string is stored in ``buf``.
Dump obj tree
~~~~~~~~~~~~~
Use API ``lv_obj_dump_tree(lv_obj_t * obj, int depth)`` to dump the object tree.
Use API :cpp:expr:`lv_obj_dump_tree(lv_obj_t * obj, int depth)` to dump the object tree.
It will walk through all children and print the object ID together with object address.
This is useful to debug UI crash. From log we can rebuilt UI the moment before crash.
For example, if the obj is stored to a timer->user_data, but obj is deleted when timer expired.
For example, if the obj is stored to a :cpp:expr:`timer->user_data`, but obj is deleted when timer expired.
Timer callback will crash because of accessing wild pointer.
From the dump log we can clearly see that the obj does not exist.

17
docs/others/obj_property.rst
View File

@ -1,3 +1,5 @@
.. _obj_property:
===============
Widget Property
===============
@ -6,11 +8,13 @@ Widgets have many properties that can decide what they look like and how they be
For example, the size, position, color, font, etc. are properties of a widget.
Specially, widget local style is also a property of a widget.
.. _obj_property_usage:
Usage
-----
Two APIs are provided to get/set widget properties. It can be enabled by setting
``LV_USE_OBJ_PROPERTY`` to 1 in `lv_conf.h`.
:c:macro:`LV_USE_OBJ_PROPERTY` to `1` in ``lv_conf.h``.
.. code:: c
@ -27,20 +31,23 @@ Two APIs are provided to get/set widget properties. It can be enabled by setting
lv_result_t lv_obj_set_property(lv_obj_t * obj, const lv_property_t * value);
lv_property_t lv_obj_get_property(lv_obj_t * obj, lv_prop_id_t id);
.. _obj_property_id:
Property ID
~~~~~~~~~~~
``lv_prop_id_t`` identifies which property to get/set. ``lv_property_t`` is an enum value
defined in `lv_obj_property.h` that are grouped by widget class. You can add your own
widget property ID following same rule and using helper macro ``LV_PROPERTY_ID``.
:cpp:type:`lv_prop_id_t` identifies which property to get/set. :cpp:type:`lv_property_t` is an enum value
defined in ``lv_obj_property.h`` that are grouped by widget class. You can add your own
widget property ID following same rule and using helper macro :c:macro:`LV_PROPERTY_ID`.
Do make sure the ID is unique across all widgets.
Property ID is a 32-bit value. The higher 4bits indicates the property value type.
The lower 28bits is the property ID.
Note that ``lv_style_prop_t`` is also valid property ID.
Note that :cpp:type:`lv_style_prop_t` is also valid property ID.
.. _obj_property_value:
Property Value
~~~~~~~~~~~~~~

56
docs/others/observer.rst
View File

@ -1,15 +1,20 @@
.. _observer:
========
Observer
========
.. _observer_overview:
Overview
********
The ``lv_observer`` module implements a standard `Observer pattern <https://en.wikipedia.org/wiki/Observer_pattern>`__.
It consists of
- subjects: each containing a value
- observers: attached to subjects to be notified on value change
- **subjects**: each containing a value
- **observers**: attached to subjects to be notified on value change
A typical use case looks like this:
@ -65,6 +70,7 @@ A typical use case looks like this:
}
.. _observer_subject:
Subject
*******
@ -72,16 +78,16 @@ Subject
Subject initialization
----------------------
Subjects have to be static or global :c:expr:`lv_subject_t` type variables.
Subjects have to be static or global :cpp:expr:`lv_subject_t` type variables.
To initialize a subject use :c: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:
- **Integer** :c:expr:`void lv_subject_init_int(lv_subject_t * subject, int32_t value)`
- **String** :c:expr:`void lv_subject_init_string(lv_subject_t * subject, char * buf, char * prev_buf, size_t size, const char * value)`
- **Pointer** :c:expr:`void lv_subject_init_pointer(lv_subject_t * subject, void * value)`
- **Color** :c:expr:`void lv_subject_init_color(lv_subject_t * subject, lv_color_t color)`
- **Group** :c:expr:`void lv_subject_init_group(lv_subject_t * subject, lv_subject_t * list[], uint32_t list_len)`
- **Integer** :cpp:expr:`void lv_subject_init_int(lv_subject_t * subject, int32_t value)`
- **String** :cpp:expr:`void lv_subject_init_string(lv_subject_t * subject, char * buf, char * prev_buf, size_t size, const char * value)`
- **Pointer** :cpp:expr:`void lv_subject_init_pointer(lv_subject_t * subject, void * value)`
- **Color** :cpp:expr:`void lv_subject_init_color(lv_subject_t * subject, lv_color_t color)`
- **Group** :cpp:expr:`void lv_subject_init_group(lv_subject_t * subject, lv_subject_t * list[], uint32_t list_len)`
Set subject value
@ -89,10 +95,10 @@ Set subject value
The following functions can be used to set a subject's value:
- **Integer** :c:expr:`void lv_subject_set_int(lv_subject_t * subject, int32_t value)`
- **String** :c:expr:`void lv_subject_copy_string(lv_subject_t * subject, char * buf)`
- **Pointer** :c:expr:`void lv_subject_set_pointer(lv_subject_t * subject, void * ptr)`
- **Color** :c:expr:`void lv_subject_set_color(lv_subject_t * subject, lv_color_t color)`
- **Integer** :cpp:expr:`void lv_subject_set_int(lv_subject_t * subject, int32_t value)`
- **String** :cpp:expr:`void lv_subject_copy_string(lv_subject_t * subject, char * buf)`
- **Pointer** :cpp:expr:`void lv_subject_set_pointer(lv_subject_t * subject, void * ptr)`
- **Color** :cpp:expr:`void lv_subject_set_color(lv_subject_t * subject, lv_color_t color)`
Get subject's value
-------------------
@ -100,10 +106,10 @@ Get subject's value
The following functions can be used to get a subject's value:
- **Integer** :c:expr:`int32_t lv_subject_get_int(lv_subject_t * subject)`
- **String** :c:expr:`const char * lv_subject_get_string(lv_subject_t * subject)`
- **Pointer** :c:expr:`const void * lv_subject_get_pointer(lv_subject_t * subject)`
- **Color** :c:expr:`lv_color_t lv_subject_get_color(lv_subject_t * subject)`
- **Integer** :cpp:expr:`int32_t lv_subject_get_int(lv_subject_t * subject)`
- **String** :cpp:expr:`const char * lv_subject_get_string(lv_subject_t * subject)`
- **Pointer** :cpp:expr:`const void * lv_subject_get_pointer(lv_subject_t * subject)`
- **Color** :cpp:expr:`lv_color_t lv_subject_get_color(lv_subject_t * subject)`
Get subject's previous value
@ -112,11 +118,12 @@ Get subject's previous value
The following functions can be used to get a subject's previous value:
- **Integer** :c:expr:`int32_t lv_subject_get_previous_int(lv_subject_t * subject)`
- **String** :c:expr:`const char * lv_subject_get_previous_string(lv_subject_t * subject)`
- **Pointer** :c:expr:`const void * lv_subject_get_previous_pointer(lv_subject_t * subject)`
- **Color** :c:expr:`lv_color_t lv_subject_get_previous_color(lv_subject_t * subject)`
- **Integer** :cpp:expr:`int32_t lv_subject_get_previous_int(lv_subject_t * subject)`
- **String** :cpp:expr:`const char * lv_subject_get_previous_string(lv_subject_t * subject)`
- **Pointer** :cpp:expr:`const void * lv_subject_get_previous_pointer(lv_subject_t * subject)`
- **Color** :cpp:expr:`lv_color_t lv_subject_get_previous_color(lv_subject_t * subject)`
.. _observer_observer:
Observer
********
@ -144,7 +151,7 @@ Where the observer callback should look like this:
It's also possible to save a target widget when subscribing to a subject.
In this case when widget is deleted, it will automatically unsubscribe from the subject.
In the observer callback ``lv_observer_get_target(observer)`` can be used to get the saved widget.
In the observer callback :cpp:expr:`lv_observer_get_target(observer)` can be used to get the saved widget.
.. code:: c
@ -172,6 +179,7 @@ To unsubscribe from a subject with all widgets you can use:
lv_subject_remove_obj(subject, obj)
.. _observer_subject_groups:
Subject groups
**************
@ -232,6 +240,7 @@ The above Voltage/Current measurement example looks like this in the practice:
lv_label_set_text_fmt(label, "%s: %d %s", mode ? "Current" : "Voltage", value, unit);
}
.. _observer_widget_binding:
Widget binding
**************
@ -320,11 +329,14 @@ Bind an integer subject to a drop-down's value
observer = lv_dropdown_bind_value(obj, &subject);
.. _observer_example:
Example
*******
.. include:: ../examples/others/observer/index.rst
.. _observer_api:
API
***

29
docs/others/snapshot.rst
View File

@ -1,3 +1,5 @@
.. _snapshot:
========
Snapshot
========
@ -5,29 +7,32 @@ Snapshot
Snapshot provides API to take snapshot image for LVGL object together
with its children. The image will look exactly like the object on display.
.. _snapshot_usage:
Usage
-----
Simply call API :c:func:`lv_snapshot_take` to generate the image descriptor
which can be set as image object src using :c:func:`lv_image_set_src`.
Simply call API :cpp:func:`lv_snapshot_take` to generate the image descriptor
which can be set as image object src using :cpp:func:`lv_image_set_src`.
Note, only following color formats are supported for now:
- LV_COLOR_FORMAT_RGB565
- LV_COLOR_FORMAT_RGB888
- LV_COLOR_FORMAT_XRGB8888
- LV_COLOR_FORMAT_ARGB8888
- :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`
- :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`
- :cpp:enumerator:`LV_COLOR_FORMAT_XRGB8888`
- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`
Free the Image
~~~~~~~~~~~~~~
The memory :c:func:`lv_snapshot_take` uses are dynamically allocated using
:c:func:`lv_malloc`. Use API :c:func:`lv_snapshot_free` to free the memory it
The memory :cpp:func:`lv_snapshot_take` uses are dynamically allocated using
:cpp:func:`lv_malloc`. Use API :cpp:func:`lv_snapshot_free` to free the memory it
takes. This will firstly free memory the image data takes, then the
image descriptor.
Take caution to free the snapshot but not delete the image object.
Before free the memory, be sure to firstly unlink it from image object,
using :c:expr:`lv_image_set_src(NULL)` and :c:expr:`lv_cache_invalidate(lv_cache_find(src, LV_CACHE_SRC_TYPE_PTR, 0, 0));`.
using :cpp:expr:`lv_image_set_src(NULL)` and :cpp:expr:`lv_cache_invalidate(lv_cache_find(src, LV_CACHE_SRC_TYPE_PTR, 0, 0));`.
Below code snippet explains usage of this API.
@ -55,14 +60,18 @@ and image data will be stored to provided ``buf``.
Note that snapshot may fail if provided buffer is not enough, which may
happen when object size changes. It's recommended to use API
:c:func:`lv_snapshot_buf_size_needed` to check the needed buffer size in byte
:cpp:func:`lv_snapshot_buf_size_needed` to check the needed buffer size in byte
firstly and resize the buffer accordingly.
.. _snapshot_example:
Example
-------
.. include:: ../examples/others/snapshot/index.rst
.. _snapshot_api:
API
---

16
docs/overview/anim.rst → docs/overview/animations.rst
View File

@ -1,3 +1,5 @@
.. _animations:
==========
Animations
==========
@ -16,6 +18,8 @@ This prototype is compatible with the majority of the property *set*
functions in LVGL. For example :cpp:expr:`lv_obj_set_x(obj, value)` or
:cpp:expr:`lv_obj_set_width(obj, value)`
.. _animations_create:
Create an animation
*******************
@ -89,6 +93,8 @@ same time. For example, animate the x and y coordinates with
exist with a given variable and function pair and :cpp:func:`lv_anim_start`
will remove any existing animations for such a pair.
.. _animations_path:
Animation path
**************
@ -107,6 +113,8 @@ the following built-in path functions:
- :cpp:func:`lv_anim_path_bounce`: bounce back a little from the end value (like
hitting a wall)
.. _animations_speed_vs_time:
Speed vs time
*************
@ -120,12 +128,16 @@ For example, :cpp:expr:`lv_anim_speed_to_time(20, 0, 100)` will yield 5000
milliseconds. For example, in the case of :cpp:func:`lv_obj_set_x` *unit* is
pixels so *20* means *20 px/sec* speed.
.. _animations_delete:
Delete animations
*****************
You can delete an animation with :cpp:expr:`lv_anim_delete(var, func)` if you
provide the animated variable and its animator function.
.. _animations_timeline:
Timeline
********
@ -168,10 +180,14 @@ anim timeline before deleting the object. Otherwise, the program may crash or be
.. image:: /misc/anim-timeline.png
.. _animations_example:
Examples
********
.. include:: ../examples/anim/index.rst
.. _animations_api:
API
***

17
docs/overview/color.rst
View File

@ -1,3 +1,5 @@
.. _color:
======
Colors
======
@ -7,8 +9,9 @@ depth, creating colors from hex code, converting between color depths,
mixing colors, etc.
The type :cpp:type:`lv_color_t` is used to store a color in RGB888 format.
This type and format is used in almost all APIs regardless to
:cpp:expr`LV_COLOR_DEPTH`.
This type and format is used in almost all APIs regardless to :cpp:expr:`LV_COLOR_DEPTH`.
.. _color_create:
Creating colors
***************
@ -50,6 +53,8 @@ Create colors from Hue, Saturation and Value values:
//From lv_color_t variable
lv_color_hsv_t c_hsv = lv_color_to_hsv(color);
.. _color_palette:
Palette
-------
@ -88,6 +93,8 @@ For the lighter variants of a palette color use
``lv_color_t c = lv_palette_darken(LV_PALETTE_..., v)``. ``v`` can be
1..4.
.. _color_modify_and_mix:
Modify and mix colors
---------------------
@ -108,12 +115,16 @@ The following functions can modify a color:
// Mix two colors with a given ratio 0: full c2, 255: full c1, 128: half c1 and half c2
lv_color_t c = lv_color_mix(c1, c2, ratio);
.. _color_builtin:
Built-in colors
---------------
:cpp:func:`lv_color_white` and :cpp:func:`lv_color_black` return ``0xFFFFFF`` and
``0x000000`` respectively.
.. _color_opacity:
Opacity
*******
@ -131,7 +142,7 @@ Some special purpose defines are also introduced:
You can also use the ``LV_OPA_*`` defines in :cpp:func:`lv_color_mix` as a
mixing *ratio*.
.. _color_api:
API
***

32
docs/overview/coord.rst
View File

@ -1,3 +1,5 @@
.. _coord:
=============================
Positions, sizes, and layouts
=============================
@ -19,6 +21,8 @@ In short this means: - Explicitly set coordinates are stored in styles
- width/height means the full size, the "content area" is smaller with padding and border width - a subset
of flexbox and grid layouts are supported
.. _coord_unites:
Units
-----
@ -31,6 +35,8 @@ Units
object to involve all the children. It's similar to ``auto`` in CSS.
E.g. :cpp:expr:`lv_obj_set_width(btn, LV_SIZE_CONTENT)`.
.. _coord_boxing_model:
Boxing model
------------
@ -51,12 +57,16 @@ keeps a "padding margin" when placing an object's children.
The outline is drawn outside the bounding box.
.. _coord_notes:
Important notes
---------------
This section describes special cases in which LVGL's behavior might be
unexpected.
.. _coord_postponed_coordinate_calculation:
Postponed coordinate calculation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -73,6 +83,8 @@ The size and position might depend on the parent or layout. Therefore
:cpp:func:`lv_obj_update_layout` recalculates the coordinates of all objects on
the screen of ``obj``.
.. _coord_removing styles:
Removing styles
^^^^^^^^^^^^^^^
@ -111,6 +123,8 @@ For example:
lv_obj_remove_style_all(obj2);
lv_obj_set_size(obj2, 200, 100);
.. _coord_position:
Position
********
@ -213,6 +227,8 @@ Note that, unlike with :cpp:func:`lv_obj_align`, :cpp:func:`lv_obj_align_to` can
realign the object if its coordinates or the reference object's
coordinates change.
.. _coord_size:
Size
****
@ -262,6 +278,8 @@ the following functions:
int32_t content_w = lv_obj_get_content_width(obj);
int32_t content_h = lv_obj_get_content_height(obj);
.. _coord_using_styles:
Using styles
************
@ -291,7 +309,7 @@ Here are some examples to set an object's size using a style:
lv_style_init(&style);
lv_style_set_width(&style, 100);
lv_obj_t * btn = lv_btn_create(lv_screen_active());
lv_obj_t * btn = lv_button_create(lv_screen_active());
lv_obj_add_style(btn, &style, LV_PART_MAIN);
As you will see below there are some other great features of size and
@ -299,6 +317,8 @@ position setting. However, to keep the LVGL API lean, only the most
common coordinate setting features have a "simple" version and the more
complex features can be used via styles.
.. _coord_translation:
Translation
***********
@ -365,6 +385,8 @@ The translation actually moves the object. That means it makes the
scrollbars and :c:macro:`LV_SIZE_CONTENT` sized objects react to the position
change.
.. _coord_transformation:
Transformation
**************
@ -389,6 +411,8 @@ This code enlarges a button when it's pressed:
lv_obj_add_style(btn, &style_pressed, LV_STATE_PRESSED);
.. _coord_min_max_size:
Min and Max size
----------------
@ -419,6 +443,8 @@ the parent's content area.
lv_obj_set_height(obj, lv_pct(100));
lv_obj_add_style(obj, &style_max_height, LV_STATE_DEFAULT); //Limit the height to half parent height
.. _coord_layout:
Layout
******
@ -499,8 +525,12 @@ the update callback. For example:
lv_style_set_prop(style, LV_STYLE_MY_PROP, v);
}
.. _coord_example:
Examples
********
.. _coord_api:
API
***

28
docs/overview/disp.rst → docs/overview/display.rst
View File

@ -1,8 +1,12 @@
.. _display:
========
Displays
========
:important: The basic concept of a *display* in LVGL is explained in the [Porting](/porting/display) section. So before reading further, please read the [Porting](/porting/display) section first.
:important: The basic concept of a *display* in LVGL is explained in the :ref:`porting` section. So before reading further, please read that section first.
.. _display_multi_display_support:
Multiple display support
************************
@ -23,6 +27,8 @@ Why would you want multi-display support? Here are some examples:
- Have some smaller and simple displays in a large instrument or technology.
- Have two large TFT displays: one for a customer and one for the shop assistant.
.. _display_one_display:
Using only one display
----------------------
@ -36,7 +42,7 @@ hidden if you register only one display. By default, the last created
on the most recently created (default) display. If you pass ``NULL`` as
``disp`` parameter to display related functions the default display will
usually be used. E.g. :cpp:expr:`lv_display_trig_activity(NULL)` will trigger a
user activity on the default display. (See below in `Inactivity <#Inactivity>`__).
user activity on the default display. (See below in :ref:`Inactivity <display_inactivity>`).
Mirror display
--------------
@ -54,10 +60,12 @@ large display's resolution. 2. In ``flush_cb``, truncate and modify the
``area`` parameter for each display. 3. Send the buffer's content to
each real display with the truncated area.
.. _display_screens:
Screens
*******
Every display has its own set of `screens <overview/object#screen-the-most-basic-parent>`__ and the
Every display has its own set of :ref:`screens <objects_screens>` and the
objects on each screen.
Be sure not to confuse displays and screens:
@ -70,11 +78,11 @@ Be sure not to confuse displays and screens:
Screens can be considered the highest level containers which have no
parent. A screen's size is always equal to its display and their origin
is (0;0). Therefore, a screen's coordinates can't be changed,
i.e. :cpp:expr:`lv_obj_set_pos()`, :cpp:expr:`lv_obj_set_size()` or similar functions
i.e. :cpp:func:`lv_obj_set_pos`, :cpp:func:`lv_obj_set_size` or similar functions
can't be used on screens.
A screen can be created from any object type but the two most typical
types are `Base object </widgets/obj>`__ and `Image </widgets/img>`__
types are :ref:`Base object <lv_obj>` and :ref:`Image <lv_image>`
(to create a wallpaper).
To create a screen, use
@ -85,7 +93,7 @@ use :cpp:expr:`lv_screen_active()`. These functions work on the default display.
you want to specify which display to work on, use
:cpp:expr:`lv_display_get_screen_active(disp)` and :cpp:expr:`lv_display_load_scr(disp, scr)`. A
screen can be loaded with animations too. Read more
`here <object.html#load-screens>`__.
:ref:`here <objects_load_screens>`.
Screens can be deleted with :cpp:expr:`lv_obj_delete(scr)`, but ensure that you do
not delete the currently loaded screen.
@ -118,14 +126,18 @@ UIs:
- Set a color format with alpha channel. E.g.
:cpp:expr:`lv_display_set_color_format(disp, LV_COLOR_FORMAT_ARGB8888)`
.. _display_features:
Features of displays
********************
.. _display_inactivity:
Inactivity
----------
A user's inactivity time is measured on each display. Every use of an
`Input device </overview/indev>`__ (if `associated with the display </porting/indev#other-features>`__) counts as an activity. To
:ref:`Input device <indev>` (if :ref:`associated with the display <porting_indev_other_features>`) counts as an activity. To
get time elapsed since the last activity, use
:cpp:expr:`lv_display_get_inactive_time(disp)`. If ``NULL`` is passed, the lowest
inactivity time among all displays will be returned (**NULL isn't just
@ -157,5 +169,7 @@ The opacity of the background color or image can be adjusted with
The ``disp`` parameter of these functions can be ``NULL`` to select the
default display.
.. _display_api:
API
***

20
docs/overview/draw.rst
View File

@ -37,6 +37,8 @@ finished. The main difference is that with LVGL you don't have to store
two frame buffers (which usually requires external RAM) but only smaller
draw buffer(s) that can easily fit into internal RAM.
.. _drawing_screen_refresh:
Mechanism of screen refreshing
******************************
@ -80,6 +82,8 @@ is the following:
flushing should be done by DMA (or similar hardware) in the background.
3. **Double buffering** - ``flush_cb`` should only swap the addresses of the frame buffers.
.. _drawing_masking:
Masking
*******
@ -167,6 +171,8 @@ to be freed when not required anymore.
:cpp:func:`lv_draw_mask_add` saves only the pointer of the mask so the parameter
needs to be valid while in use.
.. _drawing_hooks:
Hook drawing
************
@ -177,7 +183,7 @@ that tell what LVGL is about to draw. Some fields of these parameters
can be modified to draw something else or any custom drawing operations
can be added manually.
A good use case for this is the `Button matrix </widgets/btnmatrix>`__
A good use case for this is the :ref:`Button matrix <lv_buttonmatrix>`
widget. By default, its buttons can be styled in different states, but
you can't style the buttons one by one. However, an event is sent for
every button and you can, for example, tell LVGL to use different colors
@ -185,6 +191,8 @@ on a specific button or to manually draw an image on some buttons.
Each of these events is described in detail below.
.. _drawing_hooks_main:
Main drawing
------------
@ -195,8 +203,6 @@ drawing of buttons, texts, etc. happens here.
and in that structure is the clip area. The clip area is required in draw functions to make them draw only
on a limited area.
LV_EVENT_DRAW_MAIN_BEGIN
^^^^^^^^^^^^^^^^^^^^^^^^
@ -219,6 +225,8 @@ Called when the main drawing is finished. You can draw anything here as
well and it's also a good place to remove any masks created in
:cpp:enumerator:`LV_EVENT_DRAW_MAIN_BEGIN`.
.. _drawing_hooks_post:
Post drawing
------------
@ -247,6 +255,8 @@ LV_EVENT_DRAW_POST_END
Called when post drawing has finished. If masks were not removed in
:cpp:enumerator:`LV_EVENT_DRAW_MAIN_END` they should be removed here.
.. _drawing_hooks_parts:
Part drawing
------------
@ -307,6 +317,8 @@ LV_EVENT_DRAW_PART_END
Finish the drawing of a part. This is a good place to draw extra content
on the part or remove masks added in :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN`.
.. _drawing_hooks_others:
Others
------
@ -359,5 +371,7 @@ required for the text.
You can simply set the required draw area with
:cpp:expr:`lv_event_set_ext_draw_size(e, size)`.
.. _drawing_api:
API
***

26
docs/overview/event.rst
View File

@ -94,7 +94,7 @@ All objects (such as Buttons/Labels/Sliders etc.) regardless their type
receive the *Input device*, *Drawing* and *Other* events.
However, the *Special events* are specific to a particular widget type.
See the `widgets' documentation </widgets/index>`__ to learn when they
See the :ref:`widgets' documentation <widgets>` to learn when they
are sent,
*Custom events* are added by the user and are never sent by LVGL.
@ -167,16 +167,16 @@ Other events
Display events
--------------
- :cpp:enumerator:`LV_EVENT_INVALIDATE_AREA,
- :cpp:enumerator:`LV_EVENT_RESOLUTION_CHANGED,
- :cpp:enumerator:`LV_EVENT_COLOR_FORMAT_CHANGED,
- :cpp:enumerator:`LV_EVENT_REFR_REQUEST,
- :cpp:enumerator:`LV_EVENT_REFR_START,
- :cpp:enumerator:`LV_EVENT_REFR_READY,
- :cpp:enumerator:`LV_EVENT_RENDER_START,
- :cpp:enumerator:`LV_EVENT_RENDER_READY,
- :cpp:enumerator:`LV_EVENT_FLUSH_START,
- :cpp:enumerator:`LV_EVENT_FLUSH_FINISH,
- :cpp:enumerator:`LV_EVENT_INVALIDATE_AREA`
- :cpp:enumerator:`LV_EVENT_RESOLUTION_CHANGED`
- :cpp:enumerator:`LV_EVENT_COLOR_FORMAT_CHANGED`
- :cpp:enumerator:`LV_EVENT_REFR_REQUEST`
- :cpp:enumerator:`LV_EVENT_REFR_START`
- :cpp:enumerator:`LV_EVENT_REFR_READY`
- :cpp:enumerator:`LV_EVENT_RENDER_START`
- :cpp:enumerator:`LV_EVENT_RENDER_READY`
- :cpp:enumerator:`LV_EVENT_FLUSH_START`
- :cpp:enumerator:`LV_EVENT_FLUSH_FINISH`
Custom events
@ -242,10 +242,14 @@ The *target* parameter of the event is always the current target object,
not the original object. To get the original target call
:cpp:expr:`lv_event_get_target_obj(e)` in the event handler.
.. _events_examples:
Examples
********
.. include:: ../examples/event/index.rst
.. _events_api:
API
***

20
docs/overview/font.rst
View File

@ -1,3 +1,5 @@
.. _fonts:
=====
Fonts
=====
@ -42,7 +44,11 @@ Built-in fonts
**************
There are several built-in fonts in different sizes, which can be
enabled in ``lv_conf.h`` with *LV_FONT\_…* defines. ### Normal fonts
enabled in ``lv_conf.h`` with *LV_FONT\_…* defines.
Normal fonts
------------
Containing all the ASCII characters, the degree symbol (U+00B0), the
bullet symbol (U+2022) and the built-in symbols (see below).
@ -86,6 +92,8 @@ In addition to the ASCII range, the following symbols are also added to
the built-in fonts from the `FontAwesome <https://fontawesome.com/>`__
font.
.. _fonts_symbols:
.. image:: /misc/symbols.png
The symbols can be used singly as:
@ -146,10 +154,10 @@ This list summarizes the effect of RTL base direction on objects:
- Create objects by default on the right
- ``lv_tabview``: Displays tabs from right to left
- ``lv_checkbox``: Shows the box on the right
- ``lv_btnmatrix``: Shows buttons from right to left
- ``lv_buttonmatrix``: Shows buttons from right to left
- ``lv_list``: Shows icons on the right
- ``lv_dropdown``: Aligns options to the right
- The texts in ``lv_table``, ``lv_btnmatrix``, ``lv_keyboard``, ``lv_tabview``, ``lv_dropdown``, ``lv_roller`` are "BiDi processed" to be displayed correctly
- The texts in ``lv_table``, ``lv_buttonmatrix``, ``lv_keyboard``, ``lv_tabview``, ``lv_dropdown``, ``lv_roller`` are "BiDi processed" to be displayed correctly
Arabic and Persian support
--------------------------
@ -285,7 +293,7 @@ to have a special binary format. (Not TTF or WOFF). Use
`lv_font_conv <https://github.com/lvgl/lv_font_conv/>`__ with the
``--format bin`` option to generate an LVGL compatible font file.
:note: To load a font `LVGL's filesystem </overview/file-system>`__
:note: To load a font :ref:`LVGL's filesystem <overview_file_system>`
needs to be enabled and a driver must be added.
Example
@ -308,7 +316,7 @@ Load a font from a memory buffer at run-time
This function may be useful to load a font from an external file system, which is not
supported by LVGL. The font needs to be in the same format as if it were loaded from a file.
:note: To load a font from a buffer `LVGL's filesystem </overview/file-system>`__
:note: To load a font from a buffer :ref:`LVGL's filesystem <overview_file_system>`
needs to be enabled and the MEMFS driver must be added.
Example
@ -408,5 +416,7 @@ font from ``fallback`` to handle.
/* So now we can display Roboto for supported characters while having wider characters set support */
roboto->fallback = droid_sans_fallback;
.. _fonts_api:
API
***

12
docs/overview/fs.rst
View File

@ -1,4 +1,4 @@
.. _file-system:
.. _overview_file_system:
===========
File system
@ -14,7 +14,7 @@ Ready to use drivers
LVGL contains prepared drivers for the API of POSIX, standard C,
Windows, and `FATFS <http://elm-chan.org/fsw/ff/00index_e.html>`__.
Learn more `here </libs/fsdrv>`__.
Learn more :ref:`here <libs_filesystem>`.
Adding a driver
***************
@ -109,8 +109,8 @@ The example below shows how to read from a file:
lv_fs_close(&f);
*The mode in :cpp:func:`lv_fs_open` can be :cpp:enumerator:`LV_FS_MODE_WR` to open for writes
only or :cpp:enumerator:`LV_FS_MODE_RD` ``|`` :cpp:enumerator:`LV_FS_MODE_WR` for both*
The mode in :cpp:func:`lv_fs_open` can be :cpp:enumerator:`LV_FS_MODE_WR` to open for writes
only or :cpp:enumerator:`LV_FS_MODE_RD` ``|`` :cpp:enumerator:`LV_FS_MODE_WR` for both
This example shows how to read a directory's content. It's up to the
driver how to mark directories in the result but it can be a good
@ -144,7 +144,7 @@ practice to insert a ``'/'`` in front of each directory name.
Use drives for images
*********************
`Image </widgets/img>`__ objects can be opened from files too (besides
:ref:`Image <lv_image>` objects can be opened from files too (besides
variables stored in the compiled program).
To use files in image widgets the following callbacks are required:
@ -155,5 +155,7 @@ To use files in image widgets the following callbacks are required:
- seek
- tell
.. _overview_file_system_api:
API
***

18
docs/overview/img.rst → docs/overview/image.rst
View File

@ -1,3 +1,5 @@
.. _overview_image:
======
Images
======
@ -41,13 +43,15 @@ registered in LVGL to make file operations. You can add an interface to
a standard file system (FAT32 on SD card) or you create your simple file
system to read data from an SPI Flash memory. In every case, a *Drive*
is just an abstraction to read and/or write data to memory. See the
`File system </overview/file-system>`__ section to learn more.
:ref:`File system <overview_file_system>` section to learn more.
Images stored as files are not linked into the resulting executable, and
must be read into RAM before being drawn. As a result, they are not as
resource-friendly as images linked at compile time. However, they are
easier to replace without needing to rebuild the main program.
.. _overview_image_color_formats:
Color formats
*************
@ -79,7 +83,7 @@ The bytes of :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE` images are stored in the f
- **Byte 2**: Alpha byte (only with :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_WITH_ALPHA`)
You can store images in a *Raw* format to indicate that it's not encoded
with one of the built-in color formats and an external `Image decoder <#image-decoder>`__
with one of the built-in color formats and an external :ref:`Image decoder <overview_image_decoder>`
needs to be used to decode the image.
- :cpp:enumerator:`LV_COLOR_FORMAT_RAW`: Indicates a basic raw image (e.g. a PNG or JPG image).
@ -143,13 +147,13 @@ variable to display it using LVGL. For example:
};
Another (possibly simpler) option to create and display an image at
run-time is to use the `Canvas </widgets/canvas>`__ object.
run-time is to use the :ref:`Canvas <lv_canvas>` object.
Use images
----------
The simplest way to use an image in LVGL is to display it with an
`lv_image </widgets/img>`__ object:
:ref:`lv_image` object:
.. code:: c
@ -165,6 +169,8 @@ If the image was converted with the online converter, you should use
:cpp:expr:`LV_IMAGE_DECLARE(my_icon_dsc)` to declare the image in the file where
you want to use it.
.. _overview_image_decoder:
Image decoder
*************
@ -436,7 +442,7 @@ See the detailed code below:
...
}
.. _image-caching:
.. _overview_image_caching:
Image caching
*************
@ -576,5 +582,7 @@ following code to replace the LVGL built-in cache manager:
lv_cache_unlock();
}
.. _overview_image_api:
API
***

30
docs/overview/indev.rst
View File

@ -1,3 +1,5 @@
.. _indev:
=============
Input devices
=============
@ -14,6 +16,8 @@ An input device usually means:
Pointers
********
.. _indev_cursor:
Cursor
------
@ -33,6 +37,8 @@ Note that the cursor object should have
:cpp:expr:`lv_obj_remove_flag(cursor_obj, LV_OBJ_FLAG_CLICKABLE)`. For images,
*clicking* is disabled by default.
.. _indev_gestures:
Gestures
--------
@ -76,6 +82,8 @@ If you did some action on a gesture you can call
:cpp:expr:`lv_indev_wait_release(lv_indev_active())` in the event handler to
prevent LVGL sending further input device related events.
.. _indev_keypad_and_encoder:
Keypad and encoder
******************
@ -83,15 +91,17 @@ You can fully control the user interface without a touchpad or mouse by
using a keypad or encoder(s). It works similar to the *TAB* key on the
PC to select an element in an application or a web page.
.. _indev_groups:
Groups
------
Objects you want to control with a keypad or encoder need to be added to
a *Group*. In every group there is exactly one focused object which
receives the pressed keys or the encoder actions. For example, if a
`Text area </widgets/textarea>`__ is focused and you press some letter
:ref:`Text area <lv_textarea>` is focused and you press some letter
on a keyboard, the keys will be sent and inserted into the text area.
Similarly, if a `Slider </widgets/slider>`__ is focused and you press
Similarly, if a :ref:`Slider <lv_slider>` is focused and you press
the left or right arrows, the slider's value will be changed.
You need to associate an input device with a group. An input device can
@ -118,11 +128,11 @@ There are some predefined keys which have special meaning:
- :cpp:enumerator:`LV_KEY_DOWN`: Decrease value or move downwards
- :cpp:enumerator:`LV_KEY_RIGHT`: Increase value or move to the right
- :cpp:enumerator:`LV_KEY_LEFT`: Decrease value or move to the left
- :cpp:enumerator:`LV_KEY_ESC`: Close or exit (E.g. close a `Drop down list </widgets/dropdown>`__)
- :cpp:enumerator:`LV_KEY_DEL`: Delete (E.g. a character on the right in a `Text area </widgets/textarea>`__)
- :cpp:enumerator:`LV_KEY_BACKSPACE`: Delete a character on the left (E.g. in a `Text area </widgets/textarea>`__)
- :cpp:enumerator:`LV_KEY_HOME`: Go to the beginning/top (E.g. in a `Text area </widgets/textarea>`__)
- :cpp:enumerator:`LV_KEY_END`: Go to the end (E.g. in a `Text area </widgets/textarea>`__)
- :cpp:enumerator:`LV_KEY_ESC`: Close or exit (E.g. close a :ref:`Drop down list <lv_dropdown>`)
- :cpp:enumerator:`LV_KEY_DEL`: Delete (E.g. a character on the right in a :ref:`Text area <lv_textarea>`)
- :cpp:enumerator:`LV_KEY_BACKSPACE`: Delete a character on the left (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>`)
The most important special keys In your ``read_cb`` function
@ -160,9 +170,9 @@ to *Edit* mode.
In *Edit* mode, :cpp:enumerator:`LV_KEY_NEXT` and :cpp:enumerator:`LV_KEY_PREV` is usually used to modify an
object. Depending on the object's type, a short or long press of
:cpp:enumerator:`LV_KEY_ENTER` changes back to *Navigate* mode. Usually, an object
which cannot be pressed (like a `Slider </widgets/slider>`__) leaves
which cannot be pressed (like a :ref:`Slider <lv_slider>`) leaves
*Edit* mode upon a short click. But with objects where a short click has
meaning (e.g. `Button </widgets/btn>`__), a long press is required.
meaning (e.g. :ref:`Button <lv_button>`), a long press is required.
Default group
^^^^^^^^^^^^^
@ -190,5 +200,7 @@ For a more detailed description read the
`Style <https://docs.lvgl.io/master/overview/style.html>`__ section.
.. _indev_api:
API
***

6
docs/overview/index.rst
View File

@ -16,12 +16,12 @@ Overview
layer
event
indev
disp
display
color
font
img
image
fs
anim
animations
timer
draw
profiler

33
docs/overview/layer.rst
View File

@ -1,7 +1,11 @@
.. _layers:
======
Layers
======
.. _layers_creation:
Order of creation
*****************
@ -21,23 +25,25 @@ its children.
lv_screen_load(scr); /*Load the screen*/
/*Create 2 buttons*/
lv_obj_t * btn1 = lv_btn_create(scr, NULL); /*Create a button on the screen*/
lv_btn_set_fit(btn1, true, true); /*Enable automatically setting the size according to content*/
lv_obj_set_pos(btn1, 60, 40); /*Set the position of the button*/
lv_obj_t * btn1 = lv_button_create(scr, NULL); /*Create a button on the screen*/
lv_button_set_fit(btn1, true, true); /*Enable automatically setting the size according to content*/
lv_obj_set_pos(btn1, 60, 40); /*Set the position of the button*/
lv_obj_t * btn2 = lv_btn_create(scr, btn1); /*Copy the first button*/
lv_obj_set_pos(btn2, 180, 80); /*Set the position of the button*/
lv_obj_t * btn2 = lv_button_create(scr, btn1); /*Copy the first button*/
lv_obj_set_pos(btn2, 180, 80); /*Set the position of the button*/
/*Add labels to the buttons*/
lv_obj_t * label1 = lv_label_create(btn1, NULL); /*Create a label on the first button*/
lv_label_set_text(label1, "Button 1"); /*Set the text of the label*/
lv_obj_t * label1 = lv_label_create(btn1, NULL); /*Create a label on the first button*/
lv_label_set_text(label1, "Button 1"); /*Set the text of the label*/
lv_obj_t * label2 = lv_label_create(btn2, NULL); /*Create a label on the second button*/
lv_label_set_text(label2, "Button 2"); /*Set the text of the label*/
lv_obj_t * label2 = lv_label_create(btn2, NULL); /*Create a label on the second button*/
lv_label_set_text(label2, "Button 2"); /*Set the text of the label*/
/*Delete the second label*/
lv_obj_delete(label2);
.. _layers_order:
Change order
************
@ -54,6 +60,8 @@ There are four explicit ways to bring an object to the foreground:
- Use :cpp:expr:`lv_obj_swap(obj1, obj2)` to swap the relative layer position of two objects.
- When :cpp:expr:`lv_obj_set_parent(obj, new_parent)` is used, ``obj`` will be on the foreground of the ``new_parent``.
.. _layers_top_and_sys:
Top and sys layers
******************
@ -63,7 +71,7 @@ however, shared among multiple physical displays.** The ``layer_top`` is
always on top of the default screen (:cpp:func:`lv_screen_active`), and
``layer_sys`` is on top of ``layer_top``.
The get these layers use :cpp:func:`lv_layer_top()` and :cpp:func:`lv_layer_sys()`.
The get these layers use :cpp:func:`lv_layer_top` and :cpp:func:`lv_layer_sys`.
These layers work like any other widget, meaning the can be styles, scrolled,
and any kind of widgets can be created on them.
@ -81,6 +89,7 @@ The ``layer_sys`` is also used for similar purposes in LVGL. For
example, it places the mouse cursor above all layers to be sure it's
always visible.
.. _layers_bottom:
Bottom layers
*************
@ -89,7 +98,9 @@ Similarly top and sys. layer bottom layer is also screen size but
it's located below the active screen. It's visible only if the active screen's
background opacity is < 255.
The get the bottom layer use :cpp:func:`lv_layer_bottom()`.
The get the bottom layer use :cpp:func:`lv_layer_bottom`.
.. _layers_api:
API
***

2
docs/overview/new_widget.rst
View File

@ -1,3 +1,5 @@
.. _new_widget:
==========
New widget
==========

46
docs/overview/obj.rst
View File

@ -1,19 +1,23 @@
.. _objects:
=======
Objects
=======
In LVGL the **basic building blocks** of a user interface are the
objects, also called *Widgets*. For example a
`Button </widgets/btn>`__, `Label </widgets/label>`__,
`Image </widgets/img>`__, `List </widgets/list>`__,
`Chart </widgets/chart>`__ or `Text area </widgets/textarea>`__.
:ref:`Button <lv_button>`, :ref:`Label <lv_label>`,
:ref:`Image <lv_image>`, :ref:`List <lv_list>`,
:ref:`Chart <lv_chart>` or :ref:`Text area <lv_textarea>`.
You can see all the `Object types </widgets/index>`__ here.
You can see all the :ref:`Object types <widgets>` here.
All objects are referenced using an :cpp:type:`lv_obj_t` pointer as a handle.
This pointer can later be used to set or get the attributes of the
object.
.. _objects_attributes:
Attributes
**********
@ -38,7 +42,7 @@ You can set/get these attributes with ``lv_obj_set_...`` and
lv_obj_set_size(btn1, 100, 50); /*Set a button's size*/
lv_obj_set_pos(btn1, 20,30); /*Set a button's position*/
To see all the available functions visit the `Base object's documentation </widgets/obj>`__.
To see all the available functions visit the :ref:`Base object's documentation <lv_obj>`.
Specific attributes
-------------------
@ -58,9 +62,11 @@ functions. For example for a slider:
lv_slider_set_value(slider1, 40, LV_ANIM_ON); /*Set the current value (position)*/
The API of the widgets is described in their
`Documentation </widgets/index>`__ but you can also check the respective
:ref:`Documentation <widgets>` but you can also check the respective
header files (e.g. *widgets/lv_slider.h*)
.. _objects_working_mechanisms:
Working mechanisms
******************
@ -161,6 +167,8 @@ using :cpp:expr:`lv_obj_clean(obj)`.
You can use :cpp:expr:`lv_obj_delete_delayed(obj, 1000)` to delete an object after
some time. The delay is expressed in milliseconds.
.. _objects_screens:
Screens
*******
@ -175,7 +183,7 @@ be created like:
lv_obj_t * scr1 = lv_obj_create(NULL);
Screens can be created with any object type. For example, a
`Base object </widgets/obj>`__ or an image to make a wallpaper.
:ref:`Base object <lv_obj>` or an image to make a wallpaper.
Get the active screen
---------------------
@ -185,6 +193,8 @@ library creates and loads a "Base object" as a screen for each display.
To get the currently active screen use the :cpp:func:`lv_screen_active` function.
.. _objects_load_screens:
Load screens
------------
@ -208,7 +218,7 @@ system-level things (e.g. mouse cursor will be placed there with
The :cpp:func:`lv_layer_top` and :cpp:func:`lv_layer_sys` functions return pointers
to the top and system layers respectively.
Read the `Layer overview </overview/layer>`__ section to learn more
Read the :ref:`Layer overview <layers>` section to learn more
about layers.
Load screen with animation
@ -242,14 +252,16 @@ display using :cpp:expr:`lv_disp_set_default(disp)`.
:cpp:func:`lv_screen_active`, :cpp:func:`lv_screen_load` and :cpp:func:`lv_screen_load_anim` operate
on the default display.
Visit `Multi-display support </overview/display>`__ to learn more.
Visit :ref:`display_multi_display_support` to learn more.
.. _objects_parts:
Parts
*****
The widgets are built from multiple parts. For example a
`Base object </widgets/obj>`__ uses the main and scrollbar parts but a
`Slider </widgets/slider>`__ uses the main, indicator and knob parts.
:ref:`Base object <lv_obj>` uses the main and scrollbar parts but a
:ref:`Slider <lv_slider>` uses the main, indicator and knob parts.
Parts are similar to *pseudo-elements* in CSS.
The following predefined parts exist in LVGL:
@ -265,7 +277,9 @@ The following predefined parts exist in LVGL:
The main purpose of parts is to allow styling the "components" of the
widgets. They are described in more detail in the
`Style overview </overview/style>`__ section.
:ref:`Style overview <styles>` section.
.. _objects_states:
States
******
@ -295,13 +309,17 @@ values can be used as well. E.g.
:cpp:expr:`lv_obj_add_state(obj, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED)`.
To learn more about the states read the related section of the
`Style overview </overview/style>`__.
:ref:`Style overview <styles>`.
.. _objects_snapshot:
Snapshot
********
A snapshot image can be generated for an object together with its
children. Check details in `Snapshot </others/snapshot>`__.
children. Check details in :ref:`snapshot`.
.. _objects_api:
API
***

8
docs/overview/profiler.rst
View File

@ -8,6 +8,8 @@ As the complexity of the application increases, performance issues such as low F
causing lag may arise. LVGL has internally set up some hooks for performance measurement to help developers
analyze and locate performance issues.
.. _profiler_introduction:
Introduction
************
@ -20,6 +22,8 @@ When the buffer is full, the trace system prints the log information through the
The output trace logs are formatted according to Android's `systrace <https://developer.android.com/topic/performance/tracing>`_
format and can be visualized using `Perfetto <https://ui.perfetto.dev>`_.
.. _profiler_usage:
Usage
*****
@ -162,6 +166,8 @@ Users can add their own measured functions:
LV_PROFILER_END_TAG("do_something_2");
}
.. _profiler_custom_implementation:
Custom profiler implementation
******************************
@ -184,6 +190,8 @@ Taking `NuttX <https://github.com/apache/nuttx>`_ RTOS as an example:
#define LV_PROFILER_BEGIN_TAG(str) sched_note_beginex(NOTE_TAG_ALWAYS, str)
#define LV_PROFILER_END_TAG(str) sched_note_endex(NOTE_TAG_ALWAYS, str)
.. _profiler_faq:
FAQ
***

19
docs/overview/scroll.rst
View File

@ -1,3 +1,5 @@
.. _scroll:
======
Scroll
======
@ -9,8 +11,8 @@ In LVGL scrolling works very intuitively: if an object is outside its
parent content area (the size without padding), the parent becomes
scrollable and scrollbar(s) will appear. That's it.
Any object can be scrollable including ``lv_obj_t``, ``lv_img``,
``lv_btn``, ``lv_meter``, etc
Any object can be scrollable including ``lv_obj``, ``lv_image``,
``lv_button``, ``lv_meter``, etc
The object can either be scrolled horizontally or vertically in one
stroke; diagonal scrolling is not possible.
@ -73,6 +75,8 @@ base direction.
``pad_left/right/top/bottom`` sets the spacing around the scrollbars and
``width`` sets the scrollbar's width.
.. _scroll_events:
Events
------
@ -103,9 +107,10 @@ It's possible to make an object non-scrollable with
Non-scrollable objects can still propagate the scrolling (chain) to
their parents.
The direction in which scrolling happens can be controlled by
``lv_obj_set_scroll_dir(obj, LV_DIR_...)``. The following values are
possible for the direction:
The direction in which scrolling happens can be controlled by ``lv_obj_set_scroll_dir(obj, LV_DIR_...)``.
The following values are possible for the direction:
- :cpp:enumerator:`LV_DIR_TOP`: only scroll up
- :cpp:enumerator:`LV_DIR_LEFT`: only scroll left
- :cpp:enumerator:`LV_DIR_BOTTOM`: only scroll down
@ -272,10 +277,14 @@ an object. Here is an example to see how to handle the event:
}
}
.. _scroll_example:
Examples
********
.. include:: ../examples/scroll/index.rst
.. _scroll_api:
API
***

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

@ -1,3 +1,5 @@
.. _style_properties:
================
Style properties
================

32
docs/overview/style.rst
View File

@ -29,6 +29,8 @@ border width, text color and so on. It's similar to a ``class`` in CSS.
in LVGL a property is assigned to a given state.
- Transitions can be applied when the object changes state.
.. _styles_states:
States
******
@ -107,6 +109,8 @@ Some practical notes:
Instead, for example, use the background color for pressed and checked
states and indicate the focused state with a different border color.
.. _styles_cascading:
Cascading styles
****************
@ -134,6 +138,8 @@ style (red). When the button is pressed the light-gray color is a better
match because it describes the current state perfectly, so the button
will be light-gray.
.. _styles_inheritance:
Inheritance
***********
@ -146,6 +152,8 @@ property. The parents will use their own state to determine the value.
So if a button is pressed, and the text color comes from here, the
pressed text color will be used.
.. _styles_parts:
Parts
*****
@ -162,7 +170,7 @@ The following predefined parts exist in LVGL:
- :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. text area's or chart's cursor
- :cpp:enumerator:`LV_PART_CUSTOM_FIRST`: Custom part identifiers can be added starting from here.
For example a `Slider </widgets/slider.html>`__ has three parts:
For example a :ref:`Slider <lv_slider>` has three parts:
- Background
- Indicator
@ -171,6 +179,8 @@ For example a `Slider </widgets/slider.html>`__ has three parts:
This means all three parts of the slider can have their own styles. See
later how to add styles to objects and parts.
.. _styles_initialize:
Initialize styles and set/get properties
****************************************
@ -241,6 +251,8 @@ Styles can be built as ``const`` too to save RAM:
Later ``const`` style can be used like any other style but (obviously)
new properties can not be added.
.. _styles_add_remove:
Add and remove styles to a widget
*********************************
@ -333,6 +345,8 @@ To get a final value of property
lv_color_t color = lv_obj_get_style_bg_color(btn, LV_PART_MAIN);
.. _styles_local:
Local styles
************
@ -355,13 +369,13 @@ To set a local property use functions like
lv_obj_set_style_bg_color(slider, lv_color_red(), LV_PART_INDICATOR | LV_STATE_FOCUSED);
.. _style_properties:
.. _styles_properties:
Properties
**********
For the full list of style properties click
`here </overview/style-props>`__.
:ref:`here <style_properties>`.
Typical background properties
-----------------------------
@ -378,6 +392,8 @@ background properties" are the ones related to:
- Width and height transformation
- X and Y translation
.. _styles_transitions:
Transitions
***********
@ -419,6 +435,8 @@ initialized and added to a style:
lv_style_set_transition(&style1, &trans1);
.. _styles_opacity_blend_modes_transformations:
Opacity, Blend modes and Transformations
****************************************
@ -452,11 +470,15 @@ if it has radius, ``bg_opa != 255``, has shadow, outline, etc.
The click area of the widget is also transformed accordingly.
.. _styles_color_filter:
Color filter
************
TODO
.. _styles_themes:
Themes
******
@ -502,10 +524,14 @@ E.g. default theme -> custom theme -> dark theme.
There is an example for it below.
.. _styles_example:
Examples
********
.. include:: ../examples/styles/index.rst
.. _styles_api:
API
***

6
docs/overview/timer.rst
View File

@ -1,3 +1,5 @@
.. _timer:
======
Timers
======
@ -35,7 +37,7 @@ For example:
/*Do something with LVGL*/
if(something_happened) {
something_happened = false;
lv_btn_create(lv_screen_active(), NULL);
lv_button_create(lv_screen_active(), NULL);
}
}
@ -138,5 +140,7 @@ If you just want to delete an object and don't need to clean anything up
in ``my_screen_cleanup`` you could just use :cpp:func:`lv_obj_delete_async` which
will delete the object on the next call to :cpp:func:`lv_timer_handler`.
.. _timer_api:
API
***

4
docs/porting/disp.rst → docs/porting/display.rst
View File

@ -260,9 +260,9 @@ Further reading
- `lv_port_disp_template.c <https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_disp_template.c>`__
for a template for your own driver.
- `Drawing </overview/drawing>`__ to learn more about how rendering
- :ref:`Drawing <drawing>` to learn more about how rendering
works in LVGL.
- `Display features </overview/display>`__ to learn more about higher
- :ref:`display_features` to learn more about higher
level display features.
API

8
docs/porting/indev.rst
View File

@ -1,3 +1,5 @@
.. _porting_indev:
======================
Input device interface
======================
@ -24,7 +26,7 @@ The ``type`` member can be:
``read_cb`` is a function pointer which will be called periodically to
report the current state of an input device.
Visit `Input devices </overview/indev>`__ to learn more about input
Visit :ref:`Input devices <indev>` to learn more about input
devices in general.
Touchpad, mouse or any pointer
@ -187,6 +189,8 @@ should look like ``const lv_point_t points_array[] = { {12,30},{60,90}, ...}``
When the ``button_read`` callback in the example above changes the ``data->btn_id`` to ``0``
a press/release action at the first index of the ``points_array`` will be performed (``{12,30}``).
.. _porting_indev_other_features:
Other features
**************
@ -258,7 +262,7 @@ Further reading
***************
- `lv_port_indev_template.c <https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_indev_template.c>`__ for a template for your own driver.
- `INdev features </overview/display>`__ to learn more about higher level input device features.
- `INdev features <indev>` to learn more about higher level input device features.
API
***

2
docs/porting/index.rst
View File

@ -9,7 +9,7 @@ Porting
:maxdepth: 2
project
disp
display
indev
tick
timer_handler

2
docs/porting/os.rst
View File

@ -8,7 +8,7 @@ LVGL is **not thread-safe** by default.
However, in the following conditions it's valid to call LVGL related
functions: - In *events*. Learn more in :ref:`events`. -
In *lv_timer*. Learn more in `Timers </overview/timer>`__.
In *lv_timer*. Learn more in :ref:`timer`.
Tasks and threads
-----------------

2
docs/porting/project.rst
View File

@ -127,7 +127,7 @@ Initialization
To use the graphics library you have to initialize it and setup required
components. The order of the initialization is:
1. Call :cpp:func:`lv_init()`.
1. Call :cpp:func:`lv_init`.
2. Initialize your drivers.
3. Register the display and input devices drivers in LVGL. Learn more
about `Display </porting/display>`__ and `Input

2
docs/porting/timer_handler.rst
View File

@ -52,7 +52,7 @@ In an OS environment, you can use it together with the **delay** or
os_delay_ms(time_till_next); /* delay to avoid unnecessary polling */
}
To learn more about timers visit the `Timer </overview/timer>`__
To learn more about timers visit the :ref:`timer`
section.
API

15
docs/widgets/animimg.rst
View File

@ -1,3 +1,6 @@
.. _lv_animimg:
============================
Animation Image (lv_animimg)
============================
@ -10,6 +13,8 @@ multiple source images.
You can specify a duration and repeat count.
.. _lv_animimg_parts_and_styles:
Parts and Styles
****************
@ -17,6 +22,8 @@ Parts and Styles
background style properties and the image itself using the image
style properties.
.. _lv_animimg_usage:
Usage
*****
@ -26,6 +33,8 @@ Image sources
To set the image in a state, use the
:cpp:expr:`lv_animimg_set_src(imagebutton, dsc[], num)`.
.. _lv_animimg_events:
Events
******
@ -35,6 +44,8 @@ See the events of the Base object too.
Learn more about :ref:`events`.
.. _lv_animimg_keys:
Keys
****
@ -42,11 +53,15 @@ No Keys are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_animimg_example:
Example
*******
.. include:: ../examples/widgets/animimg/index.rst
.. _lv_animimg_api:
API
***

15
docs/widgets/arc.rst
View File

@ -1,3 +1,6 @@
.. _lv_arc:
============
Arc (lv_arc)
============
@ -7,6 +10,8 @@ Overview
The Arc consists of a background and a foreground arc. The foreground
(indicator) can be touch-adjusted.
.. _lv_arc_parts_and_styles:
Parts and Styles
****************
@ -21,6 +26,8 @@ Parts and Styles
size is the same as the indicator's width. Larger padding makes it
larger, smaller padding makes it smaller.
.. _lv_arc_usage:
Usage
*****
@ -120,6 +127,8 @@ used to rotate the object to the current value of the arc.
It's a typical use case to call these functions in the ``VALUE_CHANGED``
event of the arc.
.. _lv_arc_events:
Events
******
@ -152,6 +161,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_arc_keys:
Keys
****
@ -160,11 +171,15 @@ Keys
Learn more about :ref:`indev_keys`.
.. _lv_arc_example:
Example
*******
.. include:: ../examples/widgets/arc/index.rst
.. _lv_arc_api:
API
***

15
docs/widgets/bar.rst
View File

@ -1,3 +1,6 @@
.. _lv_bar:
============
Bar (lv_bar)
============
@ -13,6 +16,8 @@ its height.
Not only the end, but also the start value of the bar can be set, which
changes the start position of the indicator.
.. _lv_bar_parts_and_styles:
Parts and Styles
****************
@ -23,6 +28,8 @@ Parts and Styles
- :cpp:enumerator:`LV_PART_INDICATOR` The indicator itself; also uses all the typical
background properties.
.. _lv_bar_usage:
Usage
*****
@ -52,12 +59,16 @@ The bar can be one of the following modes:
``lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)``. The start
value always has to be smaller than the end value.
.. _lv_bar_events:
Events
******
See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_bar_keys:
Keys
****
@ -65,11 +76,15 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_bar_example:
Example
*******
.. include:: ../examples/widgets/bar/index.rst
.. _lv_bar_api:
API
***

24
docs/widgets/button.rst
View File

@ -1,27 +1,35 @@
.. _lv_button:
==================
Button (lv_button)
===============
==================
Overview
********
Buttons have no new features compared to the `Base
object </widgets/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: -
Not scrollable - Added to the default group - Default height and width
set to :cpp:enumerator:`LV_SIZE_CONTENT`
.. _lv_button_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the button. Uses the typical
background style properties.
.. _lv_button_usage:
Usage
*****
There are no new features compared to `Base object </widgets/obj>`__.
There are no new features compared to :ref:`Base object <lv_obj>`.
.. _lv_button_events:
Events
******
@ -32,6 +40,8 @@ Events
Learn more about :ref:`events`.
.. _lv_button_keys:
Keys
****
@ -39,14 +49,18 @@ Note that the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to
:cpp:enumerator:`LV_EVENT_PRESSED`, :cpp:enumerator:`LV_EVENT_PRESSING`
and :cpp:enumerator:`LV_EVENT_RELEASED` etc.
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:`indev_keys`.
.. _lv_button_example:
Example
*******
.. include:: ../examples/widgets/button/index.rst
.. _lv_button_api:
API
***

17
docs/widgets/butttonmatrix.rst → docs/widgets/buttonmatrix.rst
View File

@ -1,5 +1,8 @@
.. _lv_buttonmatrix:
===============================
Button matrix (lv_buttonmatrix)
============================
===============================
Overview
********
@ -15,6 +18,8 @@ The Button matrix is added to the default group (if one is set). Besides
the Button matrix is an editable object to allow selecting and clicking
the buttons with encoder navigation too.
.. _lv_buttonmatrix_parts_and_styles:
Parts and Styles
****************
@ -24,6 +29,8 @@ Parts and Styles
- :cpp:enumerator:`LV_PART_ITEMS` The buttons all use the text and typical background
style properties except translations and transformations.
.. _lv_buttonmatrix_usage:
Usage
*****
@ -94,6 +101,8 @@ The "One check" feature can be enabled with
:cpp:expr:`lv_buttonmatrix_set_one_checked(buttonm, true)` to allow only one button to
be checked at a time.
.. _lv_buttonmatrix_events:
Events
******
@ -112,6 +121,8 @@ text of ``button_id``\ th button.
Learn more about :ref:`events`.
.. _lv_buttonmatrix_keys:
Keys
****
@ -129,10 +140,14 @@ won't be activated.
Learn more about :ref:`indev_keys`.
.. _lv_buttonmatrix_example:
Example
*******
.. include:: ../examples/widgets/buttonmatrix/index.rst
.. _lv_buttonmatrix_api:
API
***

21
docs/widgets/calendar.rst
View File

@ -1,3 +1,6 @@
.. _lv_calendar:
======================
Calendar (lv_calendar)
======================
@ -16,10 +19,12 @@ To make the Calendar flexible, by default it doesn't show the current
year or month. Instead, there are optional "headers" that can be
attached to the calendar.
.. _lv_calendar_parts_and_styles:
Parts and Styles
****************
The calendar object uses the `Button matrix </widgets/btnmatrix>`__
The calendar object uses the `Button matrix </widgets/buttonmatrix>`__
object under the hood to arrange the days into a matrix.
- :cpp:enumerator:`LV_PART_MAIN` The background of the calendar. Uses all the background related style properties.
@ -27,9 +32,11 @@ object under the hood to arrange the days into a matrix.
buttons and a custom drawer event is added modify the properties of the buttons as follows:
- day names have no border, no background and drawn with a gray color
- days of the previous and next month have :cpp:enumerator:`LV_BTNMATRIX_CTRL_DISABLED` flag
- days of the previous and next month have :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_DISABLED` flag
- today has a thicker border with the theme's primary color - highlighted days have some opacity with the theme's primary color.
.. _lv_calendar_usage:
Usage
*****
@ -67,6 +74,8 @@ looks like ``const char * day_names[7] = {"Su", "Mo", ...};`` Only the
pointer of the day names is saved so the elements should be static,
global or constant variables.
.. _lv_calendar_events:
Events
******
@ -77,6 +86,8 @@ Events
Learn more about :ref:`events`.
.. _lv_calendar_keys:
Keys
****
@ -85,6 +96,8 @@ Keys
Learn more about :ref:`indev_keys`.
.. _lv_calendar_header:
Headers
*******
@ -104,10 +117,14 @@ Drop-down
:cpp:expr:`lv_calendar_header_dropdown_create(calendar)` creates a header that
contains 2 drop-drown lists: one for the year and another for the month.
.. _lv_calendar_example:
Example
*******
.. include:: ../examples/widgets/calendar/index.rst
.. _lv_calendar_api:
API
***

21
docs/widgets/canvas.rst
View File

@ -1,19 +1,26 @@
.. _lv_canvas:
==================
Canvas (lv_canvas)
==================
Overview
********
A Canvas inherits from `Image </widgets/img>`__ where the user can draw
A Canvas inherits from :ref:`Image <lv_image>` where the user can draw
anything. Rectangles, texts, images, lines, arcs can be drawn here using
lvgl's drawing engine.
.. _lv_canvas_parts_and_styles:
Parts and Styles
****************
:cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle style properties and image
style properties.
.. _lv_canvas_usage:
Usage
*****
@ -32,8 +39,7 @@ Or you can use
The canvas supports all the color formats like
:cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` or :cpp:enumerator:`LV_COLOR_FORMAT_I2`. See the full
list in the `Color formats </overview/image.html#color-formats>`__
section.
list in the :ref:`Color formats <overview_image_color_formats>` section.
Indexed colors
--------------
@ -67,6 +73,7 @@ The draw function can draw to any color format to which LVGL can render. Typical
:cpp:enumerator:`LV_COLOR_FORMAT_RGB565`, :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`,
:cpp:enumerator:`LV_COLOR_FORMAT_XRGB888`, and :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`.
.. _lv_canvas_events:
Events
******
@ -74,10 +81,12 @@ Events
No special events are sent by canvas objects. The same events are sent
as for the
See the events of the `Images </widgets/img>`__ too.
See the events of the :ref:`lv_image` too.
Learn more about :ref:`events`.
.. _lv_canvas_keys:
Keys
****
@ -85,10 +94,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_canvas_example:
Example
*******
.. include:: ../examples/widgets/canvas/index.rst
.. _lv_canvas_api:
API
***

17
docs/widgets/chart.rst
View File

@ -1,3 +1,6 @@
.. _lv_chart:
================
Chart (lv_chart)
================
@ -11,6 +14,8 @@ charts are supported.
Charts can have: - division lines - 2 y axis - axis ticks and texts on
ticks - cursors - scrolling and zooming
.. _lv_chart_parts_and_styles:
Parts and Styles
****************
@ -36,6 +41,8 @@ Parts and Styles
``width``, ``height``, ``bg_color`` and ``radius`` are used to set
the appearance of points.
.. _lv_chart_usage:
Usage
*****
@ -166,7 +173,7 @@ Note that :cpp:enumerator:`LV_CHART_UPDATE_MODE_SHIFT` also changes the
Tick marks and labels
---------------------
With the help of </widgets/scale>`__ vertical and horizontal scales can be added in a very flexible way.
With the help of `Scale </widgets/scale>`__, vertical and horizontal scales can be added in a very flexible way.
See the example below to learn more.
Zoom
@ -195,6 +202,8 @@ point.
the cursor at a point. If the point's position changes (new value or
scrolling) the cursor will move with the point.
.. _lv_chart_events:
Events
******
@ -206,6 +215,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_chart_keys:
Keys
****
@ -213,10 +224,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_chart_example:
Example
*******
.. include:: ../examples/widgets/chart/index.rst
.. _lv_chart_api:
API
***

15
docs/widgets/checkbox.rst
View File

@ -1,3 +1,6 @@
.. _lv_checkbox:
======================
Checkbox (lv_checkbox)
======================
@ -7,6 +10,8 @@ Overview
The Checkbox object is created from a "tick box" and a label. When the
Checkbox is clicked the tick box is toggled.
.. _lv_checkbox_parts_and_styles:
Parts and Styles
****************
@ -20,6 +25,8 @@ Parts and Styles
The Checkbox is added to the default group (if it is set).
.. _lv_checkbox_usage:
Usage
*****
@ -49,6 +56,8 @@ common state add/clear function:
To get whether the checkbox is checked or not use:
:cpp:expr:`lv_obj_has_state(cb, LV_STATE_CHECKED)`.
.. _lv_checkbox_events:
Events
******
@ -58,6 +67,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_checkbox_keys:
Keys
****
@ -71,10 +82,14 @@ Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated t
Learn more about :ref:`indev_keys`.
.. _lv_checkbox_example:
Example
*******
.. include:: ../examples/widgets/checkbox/index.rst
.. _lv_checkboxapi:
API
***

17
docs/widgets/dropdown.rst
View File

@ -1,3 +1,6 @@
.. _lv_dropdown:
============================
Drop-down list (lv_dropdown)
============================
@ -15,6 +18,8 @@ The Drop-down list is added to the default group (if it is set). Besides
the Drop-down list is an editable object to allow selecting an option
with encoder navigation too.
.. _lv_dropdown_parts_and_styles:
Parts and Styles
****************
@ -53,9 +58,13 @@ The list is hidden/shown on open/close. To add styles to it use
Alternatively the theme can be extended with the new styles.
.. _lv_dropdown_usage:
Usage
*****
.. _lv_dropdown_options:
Options
*******
@ -121,6 +130,8 @@ Manually open/close
To manually open or close the drop-down list the
``lv_dropdown_open/close(dropdown)`` function can be used.
.. _lv_dropdown_events:
Events
******
@ -136,6 +147,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_dropdown_keys:
Keys
****
@ -146,10 +159,14 @@ Keys
Learn more about :ref:`indev_keys`.
.. _lv_dropdown_example:
Example
*******
.. include:: ../examples/widgets/dropdown/index.rst
.. _lv_dropdown_api:
API
***

37
docs/widgets/image.rst
View File

@ -1,5 +1,8 @@
.. _lv_image:
================
Image (lv_image)
==============
================
Overview
********
@ -7,9 +10,11 @@ Overview
Images are the basic object to display images from flash (as arrays) or
from files. Images can display symbols (``LV_SYMBOL_...``) too.
Using the `Image decoder interface </overview/image.html#image-decoder>`__ custom image formats
Using the :ref:`Image decoder interface <overview_image_decoder>` custom image formats
can be supported as well.
.. _lv_image_parts_and_styles:
Parts and Styles
****************
@ -17,6 +22,8 @@ Parts and Styles
background style properties and the image itself using the image
style properties.
.. _lv_image_usage:
Usage
*****
@ -27,7 +34,7 @@ To provide maximum flexibility, the source of the image can be:
- a variable in code (a C array with the pixels).
- a file stored externally (e.g. on an SD card).
- a text with `Symbols </overview/font>`__.
- a text with :ref:`Symbols <fonts_symbols>`.
To set the source of an image, use :cpp:expr:`lv_image_set_src(img, src)`.
@ -40,10 +47,10 @@ To use external files, you also need to convert the image files using
the online converter tool but now you should select the binary output
format. You also need to use LVGL's file system module and register a
driver with some functions for the basic file operation. Go to the
`File system </overview/file-system>`__ to learn more. To set an image sourced
:ref:`File system <overview_file_system>` to learn more. To set an image sourced
from a file, use :cpp:expr:`lv_image_set_src(img, "S:folder1/my_img.bin")`.
You can also set a symbol similarly to `Labels </widgets/label>`__. In
You can also set a symbol similarly to :ref:`Labels <lv_label>`. In
this case, the image will be rendered as text according to the *font*
specified in the style. It enables to use of light-weight monochrome
"letters" instead of real images. You can set symbol like
@ -77,7 +84,7 @@ supported:
- **Alpha indexed**: Only alpha values are stored.
These options can be selected in the image converter. To learn more
about the color formats, read the `Images </overview/image>`__ section.
about the color formats, read the :ref:`Images <overview_image>` section.
Recolor
-------
@ -99,7 +106,7 @@ With :cpp:expr:`lv_image_set_offset_x(img, x_ofs)` and
:cpp:expr:`lv_image_set_offset_y(img, y_ofs)`, you can add some offset to the
displayed image. Useful if the object size is smaller than the image
source size. Using the offset parameter a `Texture atlas <https://en.wikipedia.org/wiki/Texture_atlas>`__
or a "running image" effect can be created by `Animating </overview/animation>`__ the x or y offset.
or a "running image" effect can be created by :ref:`Animating <animations>` the x or y offset.
Transformations
---------------
@ -128,7 +135,7 @@ 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 `Image decoder </overview/images#image-edecoder>`__
C array, or if a custom :ref:`Image decoder <overview_image_decoder>`
returns the whole image.
Note that the real coordinates of image objects won't change during
@ -137,7 +144,7 @@ the original, non-zoomed coordinates.
**IMPORTANT** The transformation of the image is independent of the
transformation properties coming from styles. (See
`here </overview/style#opacity-and-transformations>`__). The main
:ref:`here <styles_opacity_blend_modes_transformations>`). The main
differences are that pure image widget transformation
- doesn't transform the children of the image widget
@ -172,15 +179,19 @@ Or to automatically scale or tile the image
The alignment can be set by :cpp:func:`lv_image_set_align(image, align)`
.. _lv_image_events:
Events
******
No special events are sent by image objects.
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`.
.. _lv_image_keys:
Keys
****
@ -188,10 +199,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_image_example:
Example
*******
.. include:: ../examples/widgets/img/index.rst
.. include:: ../examples/widgets/image/index.rst
.. _lv_image_api:
API
***

25
docs/widgets/imagebutton.rst
View File

@ -1,5 +1,8 @@
.. _lv_imagebutton:
=============================
Image button (lv_imagebutton)
========================
=============================
Overview
********
@ -11,6 +14,8 @@ of drawing a rectangle.
You can set a left, right and center image, and the center image will be
repeated to match the width of the object.
.. _lv_imagebutton_parts_and_styles:
Parts and Styles
****************
@ -18,6 +23,8 @@ Parts and Styles
properties are used, a rectangle will be drawn behind the image
button.
.. _lv_imagebutton_usage:
Usage
*****
@ -27,7 +34,7 @@ Image sources
To set the image in a state, use the
:cpp:expr:`lv_imagebutton_set_src(imagebutton, LV_IMAGEBUTTON_STATE_..., src_left, src_center, src_right)`.
The image sources work the same as described in the `Image object </widgets/img>`__
The image sources work the same as described in the `Image object </widgets/image>`__
except that "Symbols" are not supported by the Image button. Any of the sources can ``NULL``.
The possible states are:
@ -46,10 +53,12 @@ they will be used in pressed state instead of the released images.
States
------
Instead of the regular ``lv_obj_add/remove_state()`` functions the
:cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` functions should be
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.
.. _lv_imagebutton_events:
Events
******
@ -57,6 +66,8 @@ Events
Learn more about :ref:`events`.
.. _lv_imagebutton_keys:
Keys
****
@ -68,10 +79,14 @@ Keys
Learn more about :ref:`indev_keys`.
.. _lv_imagebutton_example:
Example
*******
.. include:: ../examples/widgets/imgagebutton/index.rst
.. include:: ../examples/widgets/imagebutton/index.rst
.. _lv_imagebutton_api:
API
***

27
docs/widgets/keyboard.rst
View File

@ -1,12 +1,17 @@
.. _lv_keyboard:
======================
Keyboard (lv_keyboard)
======================
Overview
********
The Keyboard object is a special `Button matrix </widgets/buttonmatrix>`__
The Keyboard object is a special :ref:`Button matrix <lv_buttonmatrix>`
with predefined keymaps and other features to realize a virtual keyboard
to write texts into a `Text area </widgets/textarea>`__.
to write texts into a :ref:`Text area <lv_textarea>`.
.. _lv_keyboard_parts_and_styles:
Parts and Styles
****************
@ -16,6 +21,8 @@ Similarly to Button matrices Keyboards consist of 2 part:
- :cpp:enumerator:`LV_PART_MAIN` The main part. Uses all the typical background properties
- :cpp:enumerator:`LV_PART_ITEMS` The buttons. Also uses all typical background properties as well as the *text* properties.
.. _lv_keyboard_usage:
Usage
*****
@ -38,7 +45,7 @@ default mode is :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER`.
Assign Text area
----------------
You can assign a `Text area </widgets/textarea>`__ to the Keyboard to
You can assign a :ref:`Text area <lv_textarea>` to the Keyboard to
automatically put the clicked characters there. To assign the text area,
use :cpp:expr:`lv_keyboard_set_textarea(kb, ta)`.
@ -65,7 +72,7 @@ New Keymap
You can specify a new map (layout) for the keyboard with
:cpp:expr:`lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl)`. See
the `Button matrix </widgets/buttonmatrix>`__ for more information about
the :ref:`Button matrix <lv_buttonmatrix>` for more information about
creating new maps and ctrls.
Keep in mind that using following keywords will have the same effect as
@ -81,6 +88,8 @@ with the original map:
- *"abc"* Load the lower case map.
- *"1#"* Load the lower case map.
.. _lv_keyboard_events:
Events
******
@ -101,6 +110,8 @@ with a custom event handler if you wish.
Learn more about :ref:`events`.
.. _lv_keyboard_keys:
Keys
****
@ -110,10 +121,14 @@ Keys
Learn more about :ref:`indev_keys`.
Examples
********
.. _lv_keyboard_example:
Example
*******
.. include:: ../examples/widgets/keyboard/index.rst
.. _lv_keyboard_api:
API
***

41
docs/widgets/label.rst
View File

@ -1,3 +1,6 @@
.. _lv_label:
================
Label (lv_label)
================
@ -6,6 +9,8 @@ Overview
A label is the basic object type that is used to display text.
.. _lv_label_parts_and_styles:
Parts and Styles
****************
@ -18,6 +23,8 @@ Parts and Styles
text <#text-selection>`__. Only ``text_color`` and ``bg_color`` style
properties can be used.
.. _lv_label_usage:
Usage
*****
@ -42,6 +49,8 @@ safe to use with :cpp:func:`lv_label_set_text_static` (except when used with
:cpp:enumerator:`LV_LABEL_LONG_DOT`, as it modifies the buffer in-place), as they are
stored in ROM memory, which is always accessible.
.. _lv_label_newline:
Newline
-------
@ -49,6 +58,8 @@ Newline characters are handled automatically by the label object. You
can use ``\n`` to make a line break. For example:
``"line1\nline2\n\nline4"``
.. _lv_label_long_modes:
Long modes
----------
@ -79,12 +90,7 @@ this implementation detail is unnoticed. This is not the case with
:cpp:func:`lv_label_set_text_static` must be writable if you plan to use
:cpp:enumerator:`LV_LABEL_LONG_DOT`.
Text recolor
------------
In the text, you can use commands to recolor parts of the text. For
example: ``"Write a #ff0000 red# word"``. This feature can be enabled
individually for each label by :cpp:func:`lv_label_set_recolor` function.
.. _lv_label_text_selection:
Text selection
--------------
@ -92,22 +98,25 @@ Text selection
If enabled by :c:macro:`LV_LABEL_TEXT_SELECTION` part of the text can be
selected. It's similar to when you use your mouse on a PC to select a
text. The whole mechanism (click and select the text as you drag your
finger/mouse) is implemented in `Text area </widgets/textarea>`__ and
finger/mouse) is implemented in :ref:`Text area <lv_textarea>` and
the Label widget only allows manual text selection with
:cpp:expr:`lv_label_get_text_selection_start(label, start_char_index)` and
:cpp:expr:`lv_label_get_text_selection_start(label, end_char_index)`.
.. _lv_label_text_alignment:
Text alignment
--------------
To horizontally align the lines of a label the `text_align` style property can be used with
:cpp:expr:`lv_obj_set_style_text_align()` or :cpp:expr:`lv_style_set_text_align()`
:cpp:func:`lv_obj_set_style_text_align` or :cpp:func:`lv_style_set_text_align`
Note that it has a visible effect only if
- the label widget's width is larger than the width of the longest line of the text
- the text has multiple lines with non equal line length
.. _lv_label_very_long_texts:
Very long texts
---------------
@ -115,6 +124,8 @@ LVGL can efficiently handle very long (e.g. > 40k characters) labels by
saving some extra data (~12 bytes) to speed up drawing. To enable this
feature, set ``LV_LABEL_LONG_TXT_HINT 1`` in ``lv_conf.h``.
.. _lv_label_custom_scrolling_animations:
Custom scrolling animations
---------------------------
@ -124,21 +135,27 @@ customized by setting the animation property of a style, using
:cpp:func:`lv_style_set_anim`.
It will be treated as a template which will be used to create the scroll animatins.
.. _lv_label_symbols:
Symbols
-------
The labels can display symbols alongside letters (or on their own). Read
the `Font </overview/font>`__ section to learn more about the symbols.
the :ref:`fonts` section to learn more about the symbols.
.. _lv_label_events:
Events
******
No special events are sent by the Label.
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`.
.. _lv_label_keys:
Keys
****
@ -146,10 +163,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_label_example:
Example
*******
.. include:: ../examples/widgets/label/index.rst
.. _lv_label_api:
API
***

18
docs/widgets/led.rst
View File

@ -1,3 +1,6 @@
.. _lv_led:
============
LED (lv_led)
============
@ -7,11 +10,14 @@ Overview
The LEDs are rectangle-like (or circle) object whose brightness can be
adjusted. With lower brightness the colors of the LED become darker.
.. _lv_led_parts_and_styles:
Parts and Styles
****************
The LEDs have only one main part, called :cpp:enumerator:`LV_LED_PART_MAIN` and it
uses all the typical background style properties.
- :cpp:enumerator:`LV_LED_PART_MAIN` uses all the typical background style properties.
.. _lv_led_usage:
Usage
*****
@ -36,6 +42,8 @@ Use :cpp:expr:`lv_led_on(led)` and :cpp:expr:`lv_led_off(led)` to set the bright
a predefined ON or OFF value. The :cpp:expr:`lv_led_toggle(led)` toggles between
the ON and OFF state.
.. _lv_led_events:
Events
******
@ -43,6 +51,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_led_keys:
Keys
****
@ -50,10 +60,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_led_example:
Example
*******
.. include:: ../examples/widgets/led/index.rst
.. _lv_led_api:
API
***

18
docs/widgets/line.rst
View File

@ -1,3 +1,6 @@
.. _lv_line:
==============
Line (lv_line)
==============
@ -7,11 +10,14 @@ Overview
The Line object is capable of drawing straight lines between a set of
points.
.. _lv_line_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` uses all the typical background properties and line
style properties.
- :cpp:enumerator:`LV_PART_MAIN` uses all the typical background properties and line style properties.
.. _lv_line_usage:
Usage
*****
@ -44,6 +50,8 @@ counter-intuitive in some cases so the y coordinates can be inverted
with :cpp:expr:`lv_line_set_y_invert(line, true)`. In this case, *y == 0* will
be the bottom of the object. *y invert* is disabled by default.
.. _lv_line_events:
Events
******
@ -54,6 +62,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_line_keys:
Keys
****
@ -61,10 +71,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_line_example:
Example
*******
.. include:: ../examples/widgets/line/index.rst
.. _lv_line_api:
API
***

19
docs/widgets/list.rst
View File

@ -1,3 +1,6 @@
.. _lv_list:
==============
List (lv_list)
==============
@ -7,15 +10,19 @@ Overview
The List is basically a rectangle with vertical layout to which Buttons
and Texts can be added
.. _lv_list_parts_and_styles:
Parts and Styles
****************
**Background**
- :cpp:enumerator:`LV_PART_MAIN` The main part of the list that uses all the typical background properties
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See the `Base objects </widgets/obj>`__ documentation for details.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See the :ref:`Base objects <lv_obj>` documentation for details.
**Buttons and Texts** See the `Button </widgets/button>`__\ 's and `Label </widgets/label>`__\ 's documentation.
**Buttons and Texts** See the :ref:`Button <lv_button>`\ 's and :ref:`Label <lv_label>`\ 's documentation.
.. _lv_list_usage:
Usage
*****
@ -35,6 +42,8 @@ Texts
:cpp:expr:`lv_list_add_text(list, text)` adds a text.
.. _lv_list_events:
Events
******
@ -42,6 +51,8 @@ No special events are sent by the List, but sent by the Button as usual.
Learn more about :ref:`events`.
.. _lv_list_keys:
Keys
****
@ -49,10 +60,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_list_example:
Example
*******
.. include:: ../examples/widgets/list/index.rst
.. _lv_list_api:
API
***

34
docs/widgets/menu.rst
View File

@ -1,3 +1,6 @@
.. _lv_menu:
==============
Menu (lv_menu)
==============
@ -7,16 +10,25 @@ Overview
The menu widget can be used to easily create multi-level menus. It
handles the traversal between pages automatically.
.. _lv_menu_parts_and_styles:
Parts and Styles
****************
The menu widget is built from the following objects: - Main container:
lv_menu_main_cont - Main header: lv_menu_main_header_cont - Back button:
`lv_button </widgets/button>`__ - Back button icon: `lv_img </widgets/img>`__ -
Main page: lv_menu_page - Sidebar container: lv_menu_sidebar_cont -
Sidebar header: lv_menu_sidebar_header_cont - Back button:
`lv_button </widgets/button>`__ - Back button icon: `lv_img </widgets/img>`__ -
Sidebar page: lv_menu_page
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`
- 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`
- Sidebar page: :cpp:type:`lv_menu_page`
.. _lv_menu_usage:
Usage
*****
@ -84,6 +96,8 @@ menu:
- :cpp:expr:`lv_menu_section_create(parent page)` creates a new empty section.
- :cpp:expr:`lv_menu_separator_create(parent page)` creates a separator.
.. _lv_menu_events:
Events
******
@ -105,6 +119,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_menu_keys:
Keys
****
@ -112,10 +128,14 @@ No keys are handled by the menu widget.
Learn more about :ref:`indev_keys`.
.. _lv_menu_example:
Example
*******
.. include:: ../examples/widgets/menu/index.rst
.. _lv_menu_api:
API
***

23
docs/widgets/msgbox.rst
View File

@ -1,3 +1,6 @@
.. _lv_msgbox:
=======================
Message box (lv_msgbox)
=======================
@ -14,16 +17,20 @@ will be set automatically to include the text and the buttons.
The message box can be modal (blocking clicks on the rest of the screen)
or not modal.
.. _lv_msgbox_parts_and_styles:
Parts and Styles
****************
The message box is built from other widgets, so you can check these
widgets' documentation for details.
- Background: `lv_obj </widgets/obj>`__
- Close button: `lv_btn </widgets/btn>`__
- Title and text: `lv_label </widgets/label>`__
- Buttons: `lv_btnmatrix </widgets/btnmatrix>`__
- Background: :ref:`lv_obj`
- Close button: :ref:`lv_button`
- Title and text: :ref:`lv_label`
- Buttons: :ref:`lv_buttonmatrix`
.. _lv_msgbox_usage:
Usage
*****
@ -58,6 +65,8 @@ Close the message box
:cpp:expr:`lv_msgbox_close(msgbox)` closes (deletes) the message box.
.. _lv_msgbox_events:
Events
******
@ -72,6 +81,8 @@ Events
Learn more about :ref:`events`.
.. _lv_msgbox_keys:
Keys
****
@ -80,10 +91,14 @@ manually to a group if required.
Learn more about :ref:`indev_keys`.
.. _lv_msgbox_example:
Example
*******
.. include:: ../examples/widgets/msgbox/index.rst
.. _lv_msgbox_api:
API
***

42
docs/widgets/obj.rst
View File

@ -1,3 +1,6 @@
.. _lv_obj:
====================
Base object (lv_obj)
====================
@ -22,12 +25,16 @@ other widgets too. For example :cpp:expr:`lv_obj_set_width(slider, 100)`
The Base object can be directly used as a simple widget: it's nothing
more than a rectangle. In HTML terms, think of it as a ``<div>``.
.. _lv_obj_coordinates:
Coordinates
-----------
Only a small subset of coordinate settings is described here. To see all
the features of LVGL (padding, coordinates in styles, layouts, etc)
visit the `Coordinates </overview/coords>`__ page.
visit the :ref:`Coordinates <coord>` page.
.. _lv_obj_size:
Size
^^^^
@ -37,6 +44,8 @@ The object size can be modified on individual axes with
:cpp:expr:`lv_obj_set_height(obj, new_height)`, or both axes can be modified at
the same time with :cpp:expr:`lv_obj_set_size(obj, new_width, new_height)`.
.. _lv_obj_position:
Position
^^^^^^^^
@ -44,6 +53,8 @@ You can set the position relative to the parent with
:cpp:expr:`lv_obj_set_x(obj, new_x)` and :cpp:expr:`lv_obj_set_y(obj, new_y)`, or both
axes at the same time with :cpp:expr:`lv_obj_set_pos(obj, new_x, new_y)`.
.. _lv_obj_alignment:
Alignment
^^^^^^^^^
@ -68,6 +79,8 @@ For example, to align a text below an image:
The following align types exist: |image1|
.. _lv_obj_parents_and_children:
Parents and children
--------------------
@ -104,6 +117,8 @@ You can change the index of an object in its parent using
You can swap the position of two objects with
:cpp:expr:`lv_obj_swap(obj1, obj2)`.
.. _lv_obj_display_and_screens:
Display and Screens
-------------------
@ -124,6 +139,8 @@ explicitly selected with :cpp:func:`lv_disp_set_default`.
To get an object's screen use the :cpp:expr:`lv_obj_get_screen(obj)` function.
.. _lv_obj_overview_events:
Events
------
@ -133,13 +150,15 @@ To set an event callback for an object, use
To manually send an event to an object, use
:cpp:expr:`lv_event_send(obj, LV_EVENT_..., param)`
Read the `Event overview </overview/event>`__ to learn more about
Read the :ref:`Event overview <events>` to learn more about
events.
.. _lv_obj_styles:
Styles
------
Be sure to read the `Style overview </overview/style>`__. Here only the
Be sure to read the :ref:`Style overview <styles>`. Here only the
most essential functions are described.
A new style can be added to an object with the
@ -150,6 +169,8 @@ is an ORed combination of part and state(s). E.g.
The base objects use :cpp:enumerator:`LV_PART_MAIN` style properties and
:cpp:enumerator:`LV_PART_SCROLLBAR` with the typical background style properties.
.. _lv_obj_flags:
Flags
-----
@ -198,10 +219,12 @@ Some examples:
/*Make an object non-clickable*/
lv_obj_remove_flag(obj, LV_OBJ_FLAG_CLICKABLE);
.. _lv_obj_groups:
Groups
------
Read the `Input devices overview </overview/indev>`__ to learn more
Read the :ref:`Input devices overview <indev>` to learn more
about *Groups*.
Objects are added to a *group* with :cpp:expr:`lv_group_add_obj(group, obj)`,
@ -212,6 +235,8 @@ belongs to.
its group or not. If the object is not added to a group, ``false`` will
be returned.
.. _lv_obj_extended_click_area:
Extended click area
-------------------
@ -221,6 +246,8 @@ However, this can be extended with
.. _events-1:
.. _lv_obj_events:
Events
******
@ -229,6 +256,8 @@ Events
Learn more about :ref:`events`.
.. _lv_obj_keys:
Keys
****
@ -241,18 +270,21 @@ If :cpp:enumerator:`LV_OBJ_FLAG_SCROLLABLE` is enabled, but the object is not ed
:cpp:enumerator:`LV_KEY_DOWN`, :cpp:enumerator:`LV_KEY_LEFT`, :cpp:enumerator:`LV_KEY_RIGHT`) scroll the object.
If the object can only scroll vertically, :cpp:enumerator:`LV_KEY_LEFT` and
:cpp:enumerator:`LV_KEY_RIGHT` will scroll up/down instead, making it compatible with
an encoder input device. See `Input devices overview </overview/indev>`__ for
an encoder input device. See :ref:`Input devices overview <indev>` for
more on encoder behaviors and the edit mode.
Learn more about :ref:`indev_keys`.
.. |image1| image:: /misc/align.png
.. _lv_obj_example:
Example
*******
.. include:: ../examples/widgets/obj/index.rst
.. _lv_obj_api:
API
***

15
docs/widgets/roller.rst
View File

@ -1,3 +1,6 @@
.. _lv_roller:
==================
Roller (lv_roller)
==================
@ -6,6 +9,8 @@ Overview
Roller allows you to simply select one option from a list by scrolling.
.. _lv_roller_parts_and_styles:
Parts and Styles
****************
@ -19,6 +24,8 @@ Parts and Styles
typical background properties it uses the text style properties to
change the appearance of the text in the selected area.
.. _lv_roller_usage:
Usage
*****
@ -52,6 +59,8 @@ This function calculates the height with the current style. If the font,
line space, border width, etc. of the roller changes this function needs
to be called again.
.. _lv_roller_events:
Events
******
@ -61,6 +70,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_roller_keys:
Keys
****
@ -68,10 +79,14 @@ Keys
- ``LV_KEY_LEFT/UP`` Select the previous option
- :cpp:enumerator:`LY_KEY_ENTER` Apply the selected option (Send :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event)
.. _lv_roller_example:
Example
*******
.. include:: ../examples/widgets/roller/index.rst
.. _lv_roller_api:
API
***

16
docs/widgets/scale.rst
View File

@ -1,11 +1,16 @@
.. _lv_scale:
================
Scale (lv_scale)
===============
================
Overview
********
Scale allows you to have a linear scale with ranges and sections with custom styling.
.. _lv_scale_parts_and_styles:
Parts and Styles
****************
@ -17,6 +22,8 @@ The scale widget is divided in the following three parts:
.. image:: /misc/scale.png
.. _lv_scale_usage:
Usage
*****
@ -47,22 +54,29 @@ For labels 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`.
.. _lv_scale_events:
Events
******
No events supported by this widget.
.. _lv_scale_keys:
Keys
****
No keys supported by this widget.
.. _lv_scale_example:
Example
*******
.. include:: ../examples/widgets/scale/index.rst
.. _lv_scale_api:
API
***

15
docs/widgets/slider.rst
View File

@ -1,5 +1,6 @@
.. _slider:
.. _lv_slider:
==================
Slider (lv_slider)
==================
@ -10,6 +11,8 @@ The Slider object looks like a `Bar </widgets/bar>`__ supplemented with
a knob. The knob can be dragged to set a value. Just like Bar, Slider
can be vertical or horizontal.
.. _lv_slider_parts_and_styles:
Parts and Styles
****************
@ -25,6 +28,8 @@ Parts and Styles
knob can be made larger with the ``padding`` values. Padding values
can be asymmetric too.
.. _lv_slider_usage:
Usage
*****
@ -65,6 +70,8 @@ feature is enabled by adding the :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST`:
The extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, value)`) increases to knob's click area.
.. _lv_slider_events:
Events
******
@ -77,6 +84,8 @@ See the events of the `Bar </widgets/bar>`__ too.
Learn more about :ref:`events`.
.. _lv_slider_keys:
Keys
****
@ -85,10 +94,14 @@ Keys
Learn more about :ref:`indev_keys`.
.. _lv_slider_example:
Example
*******
.. include:: ../examples/widgets/slider/index.rst
.. _lv_slider_api:
API
***

16
docs/widgets/span.rst
View File

@ -1,3 +1,6 @@
.. _lv_span:
==============
Span (lv_span)
==============
@ -8,11 +11,15 @@ A spangroup is the object that is used to display rich text. Different
from the label object, ``spangroup`` can render text styled with
different fonts, colors, and sizes into the spangroup object.
.. _lv_span_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The spangroup has only one part.
.. _lv_span_usage:
Usage
*****
@ -103,6 +110,8 @@ Use :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum num
of lines to be displayed in LV_SPAN_MODE_BREAK mode, negative values
indicate no limit.
.. _lv_span_events:
Events
******
@ -110,6 +119,8 @@ No special events are sent by this widget.
Learn more about :ref:`events`.
.. _lv_span_keys:
Keys
****
@ -117,11 +128,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_span_example:
Example
*******
.. include:: ../examples/widgets/span/index.rst
.. _lv_span_api:
API
***

20
docs/widgets/spinbox.rst
View File

@ -1,3 +1,6 @@
.. _lv_spinbox:
====================
Spinbox (lv_spinbox)
====================
@ -6,13 +9,14 @@ Overview
The Spinbox contains a number as text which can be increased or
decreased by *Keys* or API functions. Under the hood the Spinbox is a
modified `Text area </widgets/textarea>`__.
modified :ref:`Text area <lv_textarea>`.
.. _lv_spinbox_parts_and_styles:
Parts and Styles
****************
The parts of the Spinbox are identical to the `Text
area </widgets/textarea>`__.
The parts of the Spinbox are identical to the :ref:`Text area <lv_textarea>`.
Value, range and step
---------------------
@ -52,15 +56,19 @@ rollover mode. If either the minimum or maximum value is reached with
rollover enabled, the value will change to the other limit. If rollover
is disabled the value will remain at the minimum or maximum value.
.. _lv_spinbox_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the value has changed.
See the events of the `Text area </widgets/textarea>`__ too.
See the events of the :ref:`Text area <lv_textarea>` too.
Learn more about :ref:`events`.
.. _lv_spinbox_keys:
Keys
****
@ -71,10 +79,14 @@ Keys
- :cpp:enumerator:`LV_KEY_ENTER` With *Encoder* got the net digit. Jump to the first
after the last.
.. _lv_spinbox_example:
Example
*******
.. include:: ../examples/widgets/spinbox/index.rst
.. _lv_spinbox_api:
API
***

17
docs/widgets/spinner.rst
View File

@ -1,3 +1,6 @@
.. _lv_spinner:
====================
Spinner (lv_spinner)
====================
@ -6,10 +9,14 @@ Overview
The Spinner object is a spinning arc over a ring.
.. _lv_spinner_parts_and_styles:
Parts and Styles
****************
The parts are identical to the parts of `lv_arc </widgets/arc>`__.
The parts are identical to the parts of :ref:`lv_arc`.
.. _lv_spinner_usage:
Usage
*****
@ -23,6 +30,8 @@ To create a spinner use
Using :cpp:expr:`lv_spinner_set_anim_params(spinner, spin_duration, angle)` the duration
of one revulation and the length of he arc can be customized.
.. _lv_spinner_events:
Events
******
@ -32,6 +41,8 @@ See the events of the `Arc </widgets/arc>`__ too.
Learn more about :ref:`events`.
.. _lv_spinner_keys:
Keys
****
@ -39,10 +50,14 @@ No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.
.. _lv_spinner_example:
Example
*******
.. include:: ../examples/widgets/spinner/index.rst
.. _lv_spinner_api:
API
***

15
docs/widgets/switch.rst
View File

@ -1,3 +1,6 @@
.. _lv_switch:
==================
Switch (lv_switch)
==================
@ -7,6 +10,8 @@ Overview
The Switch looks like a little slider and can be used to turn something
on and off.
.. _lv_switch_parts_and_styles:
Parts and Styles
****************
@ -22,6 +27,8 @@ Parts and Styles
the slider. The knob can be made larger with the ``padding`` values.
Padding values can be asymmetric too.
.. _lv_switch_usage:
Usage
*****
@ -36,6 +43,8 @@ To get the current state of the switch (with ``true`` being on), use
Call :cpp:expr:`lv_obj_add_state(obj, LV_STATE_CHECKED)` to turn it on, or
:cpp:expr:`lv_obj_remove_state(obj, LV_STATE_CHECKED)` to turn it off.
.. _lv_switch_events:
Events
******
@ -45,6 +54,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_switch_keys:
Keys
****
@ -54,10 +65,14 @@ Keys
Learn more about :ref:`indev_keys`.
.. _lv_switch_example:
Example
*******
.. include:: ../examples/widgets/switch/index.rst
.. _lv_switch_api:
API
***

15
docs/widgets/table.rst
View File

@ -1,3 +1,6 @@
.. _lv_table:
================
Table (lv_table)
================
@ -15,6 +18,8 @@ The Table is added to the default group (if it is set). Besides the
Table is an editable object to allow selecting a cell with encoder
navigation too.
.. _lv_table_parts_and_styles:
Parts and Styles
****************
@ -23,6 +28,8 @@ Parts and Styles
- :cpp:enumerator:`LV_PART_ITEMS` The cells of the table also use all the typical
background style properties and the text properties.
.. _lv_table_usage:
Usage
*****
@ -74,6 +81,8 @@ automatically sets the table size to show all the columns and rows.
If the width or height is set to a smaller number than the "intrinsic"
size then the table becomes scrollable.
.. _lv_table_events:
Events
******
@ -84,6 +93,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_table_keys:
Keys
****
@ -99,6 +110,8 @@ currently selected cell. Row and column will be set to
Learn more about :ref:`indev_keys`.
.. _lv_table_example:
Example
*******
@ -109,5 +122,7 @@ MicroPython
No examples yet.
.. _lv_table_api:
API
***

31
docs/widgets/tabview.rst
View File

@ -1,3 +1,6 @@
.. _lv_tabview:
====================
Tabview (lv_tabview)
====================
@ -7,10 +10,10 @@ Overview
The Tab view object can be used to organize content in tabs. The Tab
view is built from other widgets:
- Main container: `lv_obj </widgets/obj>`__
- Tab buttons: an `lv_obj </widgets/obj>`__` with `lv_button </widgets/button>`__ s
- Container for the tabs: `lv_obj </widgets/obj>`__
- Content of the tabs: `lv_obj </widgets/obj>`__
- Main container: :ref:`lv_obj`
- Tab buttons: an :ref:`lv_obj` with :ref:`lv_button`
- Container for the tabs: :ref:`lv_obj`
- Content of the tabs: :ref:`lv_obj`
The tab buttons can be positioned on the top, bottom, left and right
side of the Tab view.
@ -18,25 +21,29 @@ side of the Tab view.
A new tab can be selected either by clicking on a tab button or by
sliding horizontally on the content.
.. _lv_tabview_parts_and_styles:
Parts and Styles
****************
There are no special parts on the Tab view but the ``lv_obj`` and
``lv_button`` widgets are used to create the Tab view.
.. _lv_tabview_usage:
Usage
*****
Create a Tab view
-----------------
:cpp:expr:`lv_tabview_create(parent)` creates a new empty
Tab view.
:cpp:expr:`lv_tabview_create(parent)` creates a new empty Tab view.
Add tabs
--------
New tabs can be added with :cpp:expr:`lv_tabview_add_tab(tabview, "Tab name")`.
This will return a pointer to an `lv_obj </widgets/obj>`__ object where
This will return a pointer to an :ref:`lv_obj` object where
the tab's content can be created.
Rename tabs
@ -73,7 +80,9 @@ Get the parts
:cpp:expr:`lv_tabview_get_content(tabview)` returns the container for the tabs,
:cpp:expr:`lv_tabview_get_tab_buttons(tabview)` returns the Tab buttons object
which is a `Button matrix </widgets/buttonmatrix>`__.
which is a :ref:`Button matrix <lv_buttonmatrix>`.
.. _lv_tabview_events:
Events
******
@ -84,6 +93,8 @@ Events
Learn more about :ref:`events`.
.. _lv_tabview_keys:
Keys
****
@ -92,10 +103,14 @@ to a group if required.
Learn more about :ref:`indev_keys`.
.. _lv_tabview_example:
Example
*******
.. include:: ../examples/widgets/tabview/index.rst
.. _lv_tabview_api:
API
***

17
docs/widgets/textarea.rst
View File

@ -1,16 +1,21 @@
.. _lv_textarea:
=======================
Text area (lv_textarea)
=======================
Overview
********
The Text Area is a `Base object <widgets/obj.html>`__ with a
The Text Area is a `Base object </widgets/obj.html>`__ with a
`Label </widgets/label.html>`__ and a cursor on it. Texts or characters
can be added to it. Long lines are wrapped and when the text becomes
long enough the Text area can be scrolled.
One line mode and password modes are supported.
.. _lv_textarea_parts_and_styles:
Parts and Styles
****************
@ -33,6 +38,8 @@ Parts and Styles
- :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling
the placeholder text.
.. _lv_textarea_usage:
Usage
*****
@ -144,6 +151,8 @@ Any part of the text can be selected if enabled with
:cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like
when you select text on your PC with your mouse.
.. _lv_textarea_events:
Events
******
@ -162,6 +171,8 @@ See the events of the `Base object </widgets/obj>`__ too.
Learn more about :ref:`events`.
.. _lv_textarea_keys:
Keys
****
@ -170,10 +181,14 @@ Keys
Learn more about :ref:`indev_keys`.
.. _lv_textarea_example:
Example
*******
.. include:: ../examples/widgets/textarea/index.rst
.. _lv_textarea_api:
API
***

21
docs/widgets/tileview.rst
View File

@ -1,3 +1,6 @@
.. _lv_tileview:
=======================
Tile view (lv_tileview)
=======================
@ -12,13 +15,17 @@ individually to not allow moving from one tile to another.
If the Tile view is screen sized, the user interface resembles what you
may have seen on smartwatches.
.. _lv_tileview_parts_and_styles:
Parts and Styles
****************
The Tile view is built from an `lv_obj </widgets/obj>`__ container and
`lv_obj </widgets/obj>`__ tiles.
The Tile view is built from an :ref:`lv_obj` container and
:ref:`lv_obj` tiles.
The parts and styles work the same as for `lv_obj </widgets/obj>`__.
The parts and styles work the same as for :ref:`lv_obj`.
.. _lv_tileview_usage:
Usage
*****
@ -41,6 +48,8 @@ The Tile view can scroll to a tile with
:cpp:expr:`lv_tileview_set_tile(tileview, tile_obj, LV_ANIM_ON/OFF)` or
:cpp:expr:`lv_tileview_set_tile_by_index(tileview, col_id, row_id, LV_ANIM_ON/OFF)`
.. _lv_tileview_events:
Events
******
@ -48,6 +57,8 @@ Events
:cpp:expr:`lv_tileview_get_tile_active(tabview)` can be used to get current
tile.
.. _lv_tileview_keys:
Keys
****
@ -55,10 +66,14 @@ Keys
Learn more about :ref:`indev_keys`.
.. _lv_tileview_example:
Example
*******
.. include:: ../examples/widgets/tileview/index.rst
.. _lv_tileview_api:
API
***

27
docs/widgets/win.rst
View File

@ -1,3 +1,6 @@
.. _lv_win:
===============
Window (lv_win)
===============
@ -7,17 +10,21 @@ Overview
The Window is container-like object built from a header with title and
buttons and a content area.
.. _lv_win_parts_and_styles:
Parts and Styles
****************
The Window is built from other widgets so you can check their
documentation for details:
- Background: `lv_obj </widgets/obj>`__
- Header on the background: `lv_obj </widgets/obj>`__
- Title on the header: `lv_label </widgets/label>`__
- Buttons on the header: `lv_button </widgets/button>`__
- Content area on the background: `lv_obj </widgets/obj>`__
- Background: :ref:`lv_obj`
- Header on the background: :ref:`lv_obj`
- Title on the header: :ref:`lv_label`
- Buttons on the header: :ref:`lv_button`
- Content area on the background: :ref:`lv_obj`
.. _lv_win_usage:
Usage
*****
@ -45,6 +52,8 @@ the title is set to take all the remaining space on the header. In other
words: it pushes to the right all the buttons that are added after the
title.
.. _lv_win_get_parts:
Get the parts
*************
@ -52,6 +61,8 @@ Get the parts
:cpp:expr:`lv_win_get_content(win)` returns a pointer to the content container
to which the content of the window can be added.
.. _lv_win_events:
Events
******
@ -60,6 +71,8 @@ manually to the return value of :cpp:func:`lv_win_add_button`.
Learn more about :ref:`events`.
.. _lv_win_keys:
Keys
****
@ -67,10 +80,14 @@ No *Keys* are handled by the window.
Learn more about :ref:`indev_keys`.
.. _lv_win_example:
Example
*******
.. include:: ../examples/widgets/win/index.rst
.. _lv_win_api:
API
***

2
examples/libs/libjpeg_turbo/index.rst
View File

@ -1,4 +1,4 @@
Load an JPG image
Load a JPG image
-----------------
.. lv_example:: libs/libjpeg_turbo/lv_example_libjpeg_turbo_1

2
examples/libs/lodepng/index.rst
View File

@ -1,6 +1,6 @@
Open a PNG image from file and variable
---------------------------------------
.. lv_example:: libs/lodepng/lv_example_png_1
.. lv_example:: libs/lodepng/lv_example_lodepng_1
:language: c

2
examples/libs/tjpgd/index.rst
View File

@ -1,4 +1,4 @@
Load an SJPG image
Load a JPG image
------------------
.. lv_example:: libs/tjpgd/lv_example_tjpgd_1