github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages 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
94 changed files with 1441 additions and 837 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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
***