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

fix: eliminate misc sphinx warnings... (#6929)

Browse Source
This commit is contained in:
Victor Wheeler 2024-09-26 04:09:04 -06:00 committed by GitHub
parent 99b2061d5b
commit 0d96816722
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
14 changed files with 196 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
demos/README.md
View File

@ -11,19 +11,19 @@
* DEMO USAGE
====================*/
/*Show some widget. It might be required to increase `LV_MEM_SIZE` */
/* Show some widget. It might be required to increase `LV_MEM_SIZE` */
#define LV_USE_DEMO_WIDGETS 0
/*Demonstrate the usage of encoder and keyboard*/
/* Demonstrate the usage of encoder and keyboard */
#define LV_USE_DEMO_KEYPAD_AND_ENCODER 0
/*Benchmark your system*/
/* Benchmark your system */
#define LV_USE_DEMO_BENCHMARK 0
/*Stress test for LVGL*/
/* Stress test for LVGL */
#define LV_USE_DEMO_STRESS 0
/*Music player demo*/
/* Music player demo */
#define LV_USE_DEMO_MUSIC 0
#if LV_USE_DEMO_MUSIC
# define LV_DEMO_MUSIC_SQUARE 0
@ -33,16 +33,16 @@
# define LV_DEMO_MUSIC_AUTO_PLAY 0
#endif
/*Flex layout demo*/
/* Flex layout demo */
#define LV_USE_DEMO_FLEX_LAYOUT 0
/*Smart-phone like multi-language demo*/
/* Smart-phone like multi-language demo */
#define LV_USE_DEMO_MULTILANG 0
/*Widget transformation demo*/
/* Widget transformation demo */
#define LV_USE_DEMO_TRANSFORM 0
/*Demonstrate scroll settings*/
/* Demonstrate scroll settings */
#define LV_USE_DEMO_SCROLL 0
...
```

7
docs/CODING_STYLE.rst
View File

@ -174,7 +174,7 @@ illustrating most of the Doxygen commands used in LVGL.
lv_flex_align_t track_cross_place);
- Always start Doxygen comment with a breif description of the code element it documents.
- Always start Doxygen comment with a brief description of the code element it documents.
- When more detail is needed, add a blank line below the brief description and add
additional information that may be needed by LVGL API users, including preconditions
@ -208,6 +208,7 @@ illustrating most of the Doxygen commands used in LVGL.
If the list needs to be numbered, numbers can also be used.
- Place example code in a code block by surrounding it with ``@code{.c}`` and ``@endcode`` commands.
Doxygen doesn't need the ``{.c}`` part, but the downstream software does.
- Refer reader to additional information using the ``@see`` command. Doxygen adds a
"See also" paragraph. The text following the ``@see`` command will be indented.
@ -285,7 +286,7 @@ To learn more refer to the documentation of `MicroPython <integration/bindings/m
Formatting
----------
Here is example to show bracket placing and using of white spaces:
Here is example to show bracket placing and using of white space:
.. code-block:: c
@ -305,7 +306,7 @@ Here is example to show bracket placing and using of white spaces:
lv_label_ext_t * ext = lv_obj_get_ext(label);
/*Comment before a section*/
/* Comment before a section */
if(text == ext->txt || text == NULL) { /* Bracket of statements starts on same line */
lv_label_refr_text(label);
return;

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

@ -1,7 +1,7 @@
.. _get_started:
===========
Get started
Get Started
===========
There are several ways to get your feet wet with LVGL. Here is one
@ -17,7 +17,7 @@ are learning to use LVGL:
7. Port LVGL to a board. See the :ref:`porting` guide or check the ready to use `Projects <https://github.com/lvgl?q=lv_port_&type=&language=>`__
8. Read the :ref:`overview` page to get a better understanding of the library. (2-3 hours)
9. Check the documentation of the :ref:`widgets` to see their features and usage
10. If you have questions got to the `Forum <http://forum.lvgl.io/>`__
10. If you have questions go to the `Forum <http://forum.lvgl.io/>`__
11. Read the :ref:`contributing` guide to see how you can help to improve LVGL (15 minutes)

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

@ -1,7 +1,7 @@
.. _quick-overview:
==============
Quick overview
Quick Overview
==============
Here you can learn the most important things about LVGL. You should read
@ -9,8 +9,9 @@ this first to get a general impression and read the detailed
:ref:`porting` and :ref:`overview` sections
after that.
Get started in a simulator
--------------------------
Getting Started with a Simulator
--------------------------------
Instead of porting LVGL to embedded hardware straight away, it's highly
recommended to get started in a simulator first.
@ -20,93 +21,97 @@ Go to the :ref:`simulator` section to get ready-to-use projects that can be run
on your PC. This way you can save the time of porting for now and get some
experience with LVGL immediately.
Add LVGL into your project
--------------------------
Add LVGL to Your Project
------------------------
If you would rather try LVGL on your own project follow these steps:
- `Download <https://github.com/lvgl/lvgl/archive/master.zip>`__ or
clone the library from GitHub with ``git clone https://github.com/lvgl/lvgl.git``.
- Copy the ``lvgl`` folder into your project. If you wish you can add only ``lvgl/lvgl.h``, ``lvgl/lv_version.h``, and ``lvgl/src``
for LVGL itself, and ``lvgl/examples`` and ``lvgl/demos`` for the examples and demos respectively.
- Copy ``lvgl/lv_conf_template.h`` as ``lv_conf.h`` next to the
``lvgl`` folder, change the first ``#if 0`` to ``1`` to enable the
file's content and set the :c:macro:`LV_COLOR_DEPTH` defines.
- Include ``lvgl/lvgl.h`` in files where you need to use LVGL related functions.
- `Download <https://github.com/lvgl/lvgl/archive/master.zip>`__ or
clone the library from GitHub with ``git clone https://github.com/lvgl/lvgl.git``.
- Copy the ``lvgl`` folder into your project. If you wish you can add only ``lvgl/lvgl.h``, ``lvgl/lv_version.h``, and ``lvgl/src``
for LVGL itself, and ``lvgl/examples`` and ``lvgl/demos`` for the examples and demos respectively.
- Copy ``lvgl/lv_conf_template.h`` as ``lv_conf.h`` next to the
``lvgl`` folder, change the first ``#if 0`` to ``1`` to enable the
file's content and set the :c:macro:`LV_COLOR_DEPTH` defines.
- Include ``lvgl/lvgl.h`` in files where you need to use LVGL related functions.
- Call :cpp:func:`lv_init`
- Call :cpp:expr:`lv_tick_inc(x)` every ``x`` milliseconds in a Timer or Task
(``x`` should be between 1 and 10). It is required for the internal
timing of LVGL. Alternatively, register a ``tick_get_cb`` with
:cpp:func:`lv_tick_set_cb` so that LVGL can retrieve the current time directly.
- Create a display.
- Call :cpp:expr:`lv_tick_inc(x)` every ``x`` milliseconds in a Timer or Task
(``x`` should be between 1 and 10). It is required for the internal
timing of LVGL. Alternatively, register a ``tick_get_cb`` with
:cpp:func:`lv_tick_set_cb` so that LVGL can retrieve the current time directly.
- Create a display.
.. code:: c
lv_display_t *display = lv_display_create(MY_DISP_HOR_RES, MY_DISP_VER_RES);
.. code-block:: c
- Create a draw buffer: LVGL supports multiple buffering methods. Here you
can see how to set up partial buffering
(that is render the screen and the changed areas in a smaller buffer).
The buffer size can be set freely but 1/10 screen size is a good starting point.
lv_display_t *display = lv_display_create(MY_DISP_HOR_RES, MY_DISP_VER_RES);
.. code:: c
/*Declare a buffer for 1/10 screen size*/
#define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /*will be 2 for RGB565 */
static uint8_t buf1[MY_DISP_HOR_RES * MY_DISP_VER_RES / 10 * BYTE_PER_PIXEL];
lv_display_set_buffers(display, buf1, NULL, sizeof(buf1), LV_DISPLAY_RENDER_MODE_PARTIAL); /*Initialize the display buffer.*/
- Create a draw buffer: LVGL supports multiple buffering methods. Here you can see how to set up partial buffering
(that is render the screen and the changed areas in a smaller buffer). The buffer size can be set freely but 1/10
screen size is a good starting point.
- Implement and register a function which can copy the rendered image
to an area of your display:
.. code-block:: c
.. code:: c
/* Declare a buffer for 1/10 screen size */
#define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /*will be 2 for RGB565 */
static uint8_t buf1[MY_DISP_HOR_RES * MY_DISP_VER_RES / 10 * BYTE_PER_PIXEL];
lv_display_set_buffers(display, buf1, NULL, sizeof(buf1), LV_DISPLAY_RENDER_MODE_PARTIAL); /* Initialize the display buffer. */
lv_display_set_flush_cb(display, my_disp_flush);
void my_disp_flush(lv_display_t * disp, const lv_area_t * area, lv_color_t * color_p)
{
int32_t x, y;
/*It's a very slow but simple implementation.
*`set_pixel` needs to be written by you to a set pixel on the screen*/
for(y = area->y1; y <= area->y2; y++) {
for(x = area->x1; x <= area->x2; x++) {
set_pixel(x, y, *color_p);
color_p++;
}
}
- Implement and register a function which can copy the rendered image
to an area of your display:
lv_display_flush_ready(disp); /* Indicate you are ready with the flushing*/
}
.. code-block:: c
- Implement and register a function which can read an input device.
E.g. for a touchpad:
lv_display_set_flush_cb(display, my_disp_flush);
.. code:: c
void my_disp_flush(lv_display_t * disp, const lv_area_t * area, lv_color_t * color_p)
{
int32_t x, y;
/*It's a very slow but simple implementation.
*`set_pixel` needs to be written by you to a set pixel on the screen*/
for(y = area->y1; y <= area->y2; y++) {
for(x = area->x1; x <= area->x2; x++) {
set_pixel(x, y, *color_p);
color_p++;
}
}
lv_indev_t * indev = lv_indev_create(); /*Create an input device*/
lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER); /*Touch pad is a pointer-like device*/
lv_ondev_set_read_cb(indev, my_touchpad_read); /*Set your driver function*/
lv_display_flush_ready(disp); /* Indicate you are ready with the flushing*/
}
void my_touchpad_read(lv_indev_drv_t * indev_drv, lv_indev_data_t * data)
{
/*`touchpad_is_pressed` and `touchpad_get_xy` needs to be implemented by you*/
if(touchpad_is_pressed()) {
data->state = LV_INDEV_STATE_PRESSED;
touchpad_get_xy(&data->point.x, &data->point.y);
} else {
data->state = LV_INDEV_STATE_RELEASED;
}
}
- Implement and register a function which can read an input device. E.g. for a touchpad:
.. code-block:: c
lv_indev_t * indev = lv_indev_create(); /*Create an input device*/
lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER); /*Touch pad is a pointer-like device*/
lv_ondev_set_read_cb(indev, my_touchpad_read); /*Set your driver function*/
void my_touchpad_read(lv_indev_drv_t * indev_drv, lv_indev_data_t * data)
{
/*`touchpad_is_pressed` and `touchpad_get_xy` needs to be implemented by you*/
if(touchpad_is_pressed()) {
data->state = LV_INDEV_STATE_PRESSED;
touchpad_get_xy(&data->point.x, &data->point.y);
} else {
data->state = LV_INDEV_STATE_RELEASED;
}
}
- Call :cpp:func:`lv_timer_handler` periodically every few milliseconds in
the main ``while(1)`` loop or in an operating system task. It will
redraw the screen if required, handle input devices, animation etc.
- Call :cpp:func:`lv_timer_handler` periodically every few milliseconds in
the main ``while(1)`` loop or in an operating system task. It will
redraw the screen if required, handle input devices, animation etc.
For a more detailed guide go to the :ref:`porting`
section.
Learn the basics
Learn the Basics
----------------
.. _quick-overview_widgets:
@ -138,14 +143,14 @@ object to set its parameters.
For example:
.. code:: c
.. code-block:: c
lv_obj_t * slider1 = lv_slider_create(lv_screen_active());
To set some basic attributes ``lv_obj_set_<parameter_name>(obj, <value>)`` functions can be used. For
example:
.. code:: c
.. code-block:: c
lv_obj_set_x(btn1, 30);
lv_obj_set_y(btn1, 10);
@ -155,7 +160,7 @@ Along with the basic attributes, widgets can have type specific
parameters which are set by ``lv_<widget_type>_set_<parameter_name>(obj, <value>)`` functions. For
example:
.. code:: c
.. code-block:: c
lv_slider_set_value(slider1, 70, LV_ANIM_ON);
@ -174,7 +179,7 @@ called if the object is clicked, released, dragged, being deleted, etc.
A callback is assigned like this:
.. code:: c
.. code-block:: c
lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /*Assign a callback to the button*/
@ -190,13 +195,13 @@ the callback for any event.
From :cpp:expr:`lv_event_t * e` the current event code can be retrieved with:
.. code:: c
.. code-block:: c
lv_event_code_t code = lv_event_get_code(e);
The object that triggered the event can be retrieved with:
.. code:: c
.. code-block:: c
lv_obj_t * obj = lv_event_get_target(e);
@ -213,10 +218,11 @@ has only one part called :cpp:enumerator:`LV_PART_MAIN`. However, a
and :cpp:enumerator:`LV_PART_KNOB`.
By using parts you can apply different styles to sub-elements of a
widget. (See below)
widget. (See below.)
Read the widgets' documentation to learn which parts each uses.
.. _quick-overview_states:
States
@ -245,13 +251,14 @@ object is currently in that state.
To manually add or remove states use:
.. code:: c
.. code-block:: c
lv_obj_add_state(obj, LV_STATE_...);
lv_obj_remove_state(obj, LV_STATE_...);
.. _quick-overview_styles:
Styles
~~~~~~
@ -264,7 +271,7 @@ Before using a style it needs to be initialized with
:cpp:expr:`lv_style_init(&style1)`. After that, properties can be added to
configure the style. For example:
.. code:: c
.. code-block:: c
static lv_style_t style1;
lv_style_init(&style1);
@ -277,25 +284,25 @@ 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
slider is pressed:
.. code:: c
.. code-block:: c
lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR | LV_STATE_PRESSED);
If the *part* is :cpp:enumerator:`LV_PART_MAIN` it can be omitted:
.. code:: c
.. code-block:: c
lv_obj_add_style(btn1, &style1, LV_STATE_PRESSED); /*Equal to LV_PART_MAIN | LV_STATE_PRESSED*/
Similarly, :cpp:enumerator:`LV_STATE_DEFAULT` can be omitted too:
.. code:: c
.. code-block:: c
lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR); /*Equal to LV_PART_INDICATOR | LV_STATE_DEFAULT*/
For :cpp:enumerator:`LV_STATE_DEFAULT` and :cpp:enumerator:`LV_PART_MAIN` simply write ``0``:
.. code:: c
.. code-block:: c
lv_obj_add_style(btn1, &style1, 0); /*Equal to LV_PART_MAIN | LV_STATE_DEFAULT*/
@ -304,7 +311,7 @@ styles to a part of an object. For example ``style_btn`` can set a
default button appearance, and ``style_btn_red`` can overwrite the
background color to make the button red:
.. code:: c
.. code-block:: c
lv_obj_add_style(btn1, &style_btn, 0);
lv_obj_add_style(btn1, &style1_btn_red, 0);
@ -321,7 +328,7 @@ style and all text on that screen will inherit it by default.
Local style properties also can be added to objects. This creates a
style which resides inside the object and is used only by the object:
.. code:: c
.. code-block:: c
lv_obj_set_style_bg_color(slider1, lv_color_hex(0x2080bb), LV_PART_INDICATOR | LV_STATE_PRESSED);
@ -329,6 +336,7 @@ To learn all the features of styles see the :ref:`styles` section.
.. _quick-overview_themes:
Themes
~~~~~~
@ -340,6 +348,7 @@ The theme for your application is a compile time configuration set in
.. _quick-overview_examples:
Examples
--------
@ -347,12 +356,13 @@ Examples
.. _quick-overview_micropython:
MicroPython
-----------
Learn more about :ref:`micropython`.
.. code:: python
.. code-block:: python
# Initialize
import display_driver

12
docs/integration/chip/espressif.rst
View File

@ -114,17 +114,17 @@ The process is described in details below, using ``SPIFFS`` as demonstration.
The exact configuration depends on your flash size and existing partitions,
but the new final result should look something like this:
.. code:: csv
.. csv-table:: Partition Table
nvs, data, nvs, 0x9000, 0x6000,
phy_init, data, phy, 0xf000, 0x1000,
factory, app, factory, 0x10000, 1400k,
storage, data, spiffs, , 400k,
nvs, data, nvs, 0x9000, 0x6000
phy_init, data, phy, 0xf000, 0x1000
factory, app, factory, 0x10000, 1400k
storage, data, spiffs, , 400k
.. note::
If you are not using a custom ``parition.csv`` yet, it can be added
If you are not using a custom ``partition.csv`` yet, it can be added
via ``menuconfig`` (``Partition Table → Partition Table → Custom partition table CSV``).
- Apply changes to the build system

22
docs/overview/event.rst
View File

@ -22,7 +22,7 @@ Add events to a widget
The user can assign callback functions to an object to see its events.
In practice, it looks like this:
.. code:: c
.. code-block:: c
lv_obj_t * btn = lv_button_create(lv_screen_active());
lv_obj_add_event_cb(btn, my_event_cb, LV_EVENT_CLICKED, NULL); /*Assign an event callback*/
@ -44,7 +44,7 @@ more detail.
More events can be added to an object, like this:
.. code:: c
.. code-block:: c
lv_obj_add_event_cb(obj, my_event_cb_1, LV_EVENT_CLICKED, NULL);
lv_obj_add_event_cb(obj, my_event_cb_2, LV_EVENT_PRESSED, NULL);
@ -53,7 +53,7 @@ More events can be added to an object, like this:
Even the same event callback can be used on an object with different
``user_data``. For example:
.. code:: c
.. code-block:: c
lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num1);
lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num2);
@ -64,7 +64,7 @@ Other objects can use the same *event callback*.
In the very same way events can attached to the input devices and displays like this
.. code:: c
.. code-block:: c
lv_display_add_event_cb(disp, event_cb, LV_EVENT_RESOLUTION_CHANGED, NULL);
lv_indev_add_event_cb(indev, event_cb, LV_EVENT_CLICKED, NULL);
@ -73,7 +73,7 @@ In the very same way events can attached to the input devices and displays like
Remove event(s) from widgets
****************************
.. code:: c
.. code-block:: c
uint32_t i;
uint32_t event_cnt = lv_obj_get_event_count(obj);
@ -133,11 +133,11 @@ Input device events
- :cpp:enumerator:`LV_EVENT_HOVER_OVER`: Indev hover over object
- :cpp:enumerator:`LV_EVENT_HOVER_LEAVE`: Indev hover leave object
Drawing events
Drawing Events
--------------
- :cpp:enumerator:`LV_EVENT_COVER_CHECK`: Check if the object fully covers an area. The event parameter is :cpp:type:`lv_cover_check_info_t *`.
- :cpp:enumerator:`LV_EVENT_REFR_EXT_DRAW_SIZE`: Get the required extra draw area around the object (e.g. for shadow). The event parameter is :cpp:type:`int32_t *` to store the size.
- :cpp:enumerator:`LV_EVENT_COVER_CHECK`: Check if the object fully covers an area. The event parameter is :cpp:type:`lv_cover_check_info_t` ``*``.
- :cpp:enumerator:`LV_EVENT_REFR_EXT_DRAW_SIZE`: Get the required extra draw area around the object (e.g. for shadow). The event parameter is :cpp:type:`int32_t` ``*`` to store the size.
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_BEGIN`: Starting the main drawing phase
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN`: Perform the main drawing
- :cpp:enumerator:`LV_EVENT_DRAW_MAIN_END`: Finishing the main drawing phase
@ -150,7 +150,7 @@ Special events
--------------
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED`: The object's value has changed (i.e. slider moved)
- :cpp:enumerator:`LV_EVENT_INSERT`: A text is inserted to the object. The event data is `char *` being inserted.
- :cpp:enumerator:`LV_EVENT_INSERT`: A text is inserted to the object. The event data is :cpp:type:`char` ``*`` being inserted.
- :cpp:enumerator:`LV_EVENT_REFRESH`: Notify the object to refresh something on it (for the user)
- :cpp:enumerator:`LV_EVENT_READY`: A process has finished
- :cpp:enumerator:`LV_EVENT_CANCEL`: A process has been cancelled
@ -234,11 +234,11 @@ contains all data about the event. The following values can be gotten from it:
- :cpp:expr:`lv_event_get_code(e)`: get the event code
- :cpp:expr:`lv_event_get_current_target(e)`: get the object to which an event was sent. I.e. the object whose event handler is being called.
- :cpp:expr:`lv_event_get_target(e)`: get the object that originally triggered the event (different from :cpp:func:`lv_event_get_target` if :ref:`event bubbling <events_bubbling>` is enabled)
- :cpp:expr:`lv_event_get_target(e)`: get the object that originally triggered the event (different from :cpp:func:`lv_event_get_target` if :ref:`event bubbling <event_bubbling>` is enabled)
- :cpp:expr:`lv_event_get_user_data(e)`: get the pointer passed as the last parameter of :cpp:func:`lv_obj_add_event`.
- :cpp:expr:`lv_event_get_param(e)`: get the parameter passed as the last parameter of :cpp:func:`lv_obj_send_event`
.. _events_bubbling:
.. _event_bubbling:
Event bubbling
**************

28
docs/overview/font.rst
View File

@ -9,7 +9,7 @@ to render images of individual letters (glyph). A font is stored in a
:cpp:type:`lv_font_t` variable and can be set in a style's *text_font* field.
For example:
.. code:: c
.. code-block:: c
lv_style_set_text_font(&my_style, &lv_font_montserrat_28); /*Set a larger font*/
@ -36,7 +36,7 @@ and be sure that, :c:macro:`LV_TXT_ENC` is set to :c:macro:`LV_TXT_ENC_UTF8` in
To test it try
.. code:: c
.. code-block:: c
lv_obj_t * label1 = lv_label_create(lv_screen_active(), NULL);
lv_label_set_text(label1, LV_SYMBOL_OK);
@ -101,19 +101,19 @@ font.
The symbols can be used singly as:
.. code:: c
.. code-block:: c
lv_label_set_text(my_label, LV_SYMBOL_OK);
Or together with strings (compile time string concatenation):
.. code:: c
.. code-block:: c
lv_label_set_text(my_label, LV_SYMBOL_OK "Apply");
Or more symbols together:
.. code:: c
.. code-block:: c
lv_label_set_text(my_label, LV_SYMBOL_OK LV_SYMBOL_WIFI LV_SYMBOL_PLAY);
@ -303,7 +303,7 @@ to have a special binary format. (Not TTF or WOFF). Use
Example
.. code:: c
.. code-block:: c
lv_font_t *my_font = lv_binfont_create("X:/path/to/my_font.bin");
if(my_font == NULL) return;
@ -313,8 +313,8 @@ Example
/*Free the font if not required anymore*/
lv_binfont_destroy(my_font);
Load a font from a memory buffer at run-time
******************************************
Load a Font from a Memory Buffer at Run-Time
********************************************
:cpp:func:`lv_binfont_create_from_buffer` can be used to load a font from a memory buffer.
This function may be useful to load a font from an external file system, which is not
@ -325,7 +325,7 @@ supported by LVGL. The font needs to be in the same format as if it were loaded
Example
.. code:: c
.. code-block:: c
lv_font_t *my_font;
uint8_t *buf;
@ -397,10 +397,10 @@ line 1
#!/usr/bin/env python3
Example for a 12px font
-----------------------
Example for a 12-px Font
------------------------
.. code:: bash
.. code-block:: console
cd mkttf
./mkttf.py ./TerminusMedium-12-12.bdf
@ -432,7 +432,7 @@ the font's bitmap and read them when the library needs them. FreeType can be use
To add a new font engine, a custom :cpp:type:`lv_font_t` variable needs to be created:
.. code:: c
.. code-block:: c
/*Describe the properties of a font*/
lv_font_t my_font;
@ -487,7 +487,7 @@ font from ``fallback`` to handle.
``fallback`` can be chained, so it will try to solve until there is no ``fallback`` set.
.. code:: c
.. code-block:: c
/* Roboto font doesn't have support for CJK glyphs */
lv_font_t *roboto = my_font_load_function();

32
docs/overview/fs.rst
View File

@ -13,24 +13,24 @@ drive letter. For example, if an SD card is associated with the letter
If you want to skip the drive prefix from the path, you can use the :c:macro:`LV_FS_DEFAULT_DRIVE_LETTER` config parameter.
Ready to use drivers
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 :ref:`here <libs_filesystem>`.
Adding a driver
Adding a Driver
***************
Registering a driver
Registering a Driver
--------------------
To add a driver, a :cpp:type:`lv_fs_drv_t` needs to be initialized like below.
The :cpp:type:`lv_fs_drv_t` needs to be static, global or dynamically allocated
and not a local variable.
.. code:: c
.. code-block:: c
static lv_fs_drv_t drv; /*Needs to be static or global*/
lv_fs_drv_init(&drv); /*Basic initialization*/
@ -65,7 +65,7 @@ Open callback
The prototype of ``open_cb`` looks like this:
.. code:: c
.. code-block:: c
void * (*open_cb)(lv_fs_drv_t * drv, const char * path, lv_fs_mode_t mode);
@ -83,7 +83,7 @@ Other callbacks
The other callbacks are quite similar. For example ``write_cb`` looks
like this:
.. code:: c
.. code-block:: c
lv_fs_res_t (*write_cb)(lv_fs_drv_t * drv, void * file_p, const void * buf, uint32_t btw, uint32_t * bw);
@ -99,7 +99,7 @@ Usage example
The example below shows how to read from a file:
.. code:: c
.. code-block:: c
lv_fs_file_t f;
lv_fs_res_t res;
@ -120,7 +120,7 @@ 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
practice to insert a ``'/'`` in front of each directory name.
.. code:: c
.. code-block:: c
lv_fs_dir_t dir;
lv_fs_res_t res;
@ -183,8 +183,8 @@ The implementation is documented below. Note that the FS functions make calls
to other driver FS functions when the cache is enabled. i.e., ``lv_fs_read`` may call the driver's ``seek``
so the driver needs to implement more callbacks when the cache is enabled.
``lv_fs_read`` :sub:`(behavior when the cache is enabled)`
-------------------------------------------------
``lv_fs_read`` :sub:`(Behavior When Cache is Enabled)`
----------------------------------------------------------
.. mermaid::
:zoom:
@ -230,21 +230,21 @@ so the driver needs to implement more callbacks when the cache is enabled.
--> P["copy the required bytes
to the destination buffer"]
``lv_fs_write`` :sub:`(behavior when the cache is enabled)`
--------------------------------------------------
``lv_fs_write`` :sub:`(Behavior When Cache is Enabled)`
-------------------------------------------------------
The part of the cache that coincides with the written content
will be updated to reflect the written content.
``lv_fs_seek`` :sub:`(behavior when the cache is enabled)`
-------------------------------------------------
``lv_fs_seek`` :sub:`(Behavior When Cache is Enabled)`
------------------------------------------------------
The driver's ``seek`` will not actually be called unless the ``whence``
is ``LV_FS_SEEK_END``, in which case ``seek`` and ``tell`` will be called
to determine where the end of the file is.
``lv_fs_tell`` :sub:`(behavior when the cache is enabled)`
-------------------------------------------------
``lv_fs_tell`` :sub:`(Behavior When Cache is Enabled)`
------------------------------------------------------
The driver's ``tell`` will not actually be called.

8
docs/overview/layer.rst
View File

@ -24,7 +24,7 @@ its children.
.. image:: /misc/layers.png
.. code:: c
.. code-block:: c
/*Create a screen*/
lv_obj_t * scr = lv_obj_create(NULL, NULL);
@ -89,7 +89,7 @@ everywhere. For example, a menu bar, a pop-up, etc. If the ``click``
attribute is enabled, then ``layer_top`` will absorb all user clicks and
acts as a modal.
.. code:: c
.. code-block:: c
lv_obj_add_flag(lv_layer_top(), LV_OBJ_FLAG_CLICKABLE);
@ -128,8 +128,8 @@ In this case widget will be sliced into ``LV_DRAW_SW_LAYER_SIMPLE_BUF_SIZE`` siz
If there is no memory for a new chunk, LVGL will try allocating layer when another chunk is rendered and freed.
Transformed layer
---------------
Transformed Layer
-----------------
When the widget is transformed a larger part of the widget needs to rendered to provide enough data for transformation. LVGL tries to render as small area of the widget as possible, but due to the nature of transformations no slicing is possible in this case.

8
docs/overview/vg_lite_tvg.rst
View File

@ -9,10 +9,10 @@ Its purpose is to simplify the debugging of VG-Lite adaptation and reduce the ti
It has been integrated into the CI automated compilation and testing process to ensure that the VG-Lite rendering backend can be fully tested after each PR modification.
How it works
How It Works
************
Sort out the APIs in the ``vg_lite.h`` header file provided by the vendor, re-implement the APIs using `ThorVG <https://github.com/thorvg/thorvg>`_,
Sort out the APIs in the ``vg_lite.h`` header file provided by the vendor, re-implement the APIs using `ThorVG <https://github.com/thorvg/thorvg>`_,
and simulate the same rendering images as the real hardware on the simulator.
Configuration
@ -21,7 +21,7 @@ Configuration
1. Enable VG-Lite rendering backend, see `VG-Lite Rendering Backend </overview/renderers/vg_lite>`__.
2. Enable ThorVG and turn on the configuration :c:macro:`LV_USE_THORVG_INTERNAL` or :c:macro:`LV_USE_THORVG_EXTERNAL`.
It is recommended to use the internal ThorVG library to ensure uniform rendering results.
It is recommended to use the internal ThorVG library to ensure uniform rendering results.
3. Enable :c:macro:`LV_USE_VG_LITE_THORVG` and set :c:macro:`LV_DRAW_BUF_ALIGN` to 64. The rest of the options can remain default.
Make sure :c:macro:`LV_VG_LITE_USE_GPU_INIT` is enabled, because the thorvg drawing context needs to be initialized before it can be used.
Make sure :c:macro:`LV_VG_LITE_USE_GPU_INIT` is enabled, because the thorvg drawing context needs to be initialized before it can be used.

19
docs/porting/display.rst
View File

@ -20,7 +20,7 @@ flush_cb
An example ``flush_cb`` looks like this:
.. code:: c
.. code-block:: c
void my_flush_cb(lv_display_t * display, const lv_area_t * area, uint8_t * px_map)
{
@ -83,7 +83,7 @@ The draw buffers can be set with
Example:
.. code:: c
.. code-block:: c
static uint16_t buf[LCD_HOR_RES * LCD_VER_RES / 10];
lv_display_set_buffers(disp, buf, NULL, sizeof(buf), LV_DISPLAY_RENDER_MODE_PARTIAL);
@ -172,10 +172,10 @@ The default color format of the display is set according to :c:macro:`LV_COLOR_D
- :c:macro:`LV_COLOR_DEPTH` ``24``: RGB888 (3 bytes/pixel)
- :c:macro:`LV_COLOR_DEPTH` ``16``: RGB565 (2 bytes/pixel)
- :c:macro:`LV_COLOR_DEPTH` ``8``: L8 (1 bytes/pixel)
- :c:macro:`LV_COLOR_DEPTH` ``1``: I1 (1 bit/pixel) Only support for horizontal mapped buffers. See :refr:`monochrome` for more details:
- :c:macro:`LV_COLOR_DEPTH` ``1``: I1 (1 bit/pixel) Only support for horizontal mapped buffers. See :ref:`monochrome` for more details:
The ``color_format`` can be changed with
:cpp:expr:`lv_display_set_color_depth(display, LV_COLOR_FORMAT_...)`.
``lv_display_set_color_depth(display, LV_COLOR_FORMAT_...)`` .
Besides the default value :c:macro:`LV_COLOR_FORMAT_ARGB8888` can be
used as a well.
@ -183,8 +183,8 @@ It's very important that draw buffer(s) should be large enough for any
selected color format.
Swap endianness
--------------
Swap Endianness
---------------
In case of RGB565 color format it might be required to swap the 2 bytes
because the SPI, I2C or 8 bit parallel port periphery sends them in the wrong order.
@ -256,7 +256,7 @@ the TE signal.
You can do this in the following way:
.. code:: c
.. code-block:: c
/*Delete the original display refresh timer*/
lv_display_delete_refr_timer(disp);
@ -279,7 +279,7 @@ Force refreshing
----------------
Normally the invalidated areas (marked for redraw) are rendered in :cpp:func:`lv_timer_handler` in every
:c:macro:`LV_DEF_REFR_PERIOD` milliseconds. However, by using :cpp:func:`lv_refr_now(display)` you can ask LVGL to
:c:macro:`LV_DEF_REFR_PERIOD` milliseconds. However, by using :cpp:expr:`lv_refr_now(display)` you can ask LVGL to
redraw the invalid areas immediately. The refreshing will happen in :cpp:func:`lv_refr_now` which might take
longer time.
@ -313,8 +313,7 @@ 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.
- :ref:`Drawing <drawing>` to learn more about how rendering
works in LVGL.
- :ref:`Drawing <porting_draw>` to learn more about how rendering works in LVGL.
- :ref:`display_features` to learn more about higher
level display features.

22
docs/porting/indev.rst
View File

@ -9,7 +9,7 @@ Types of input devices
To create an input device use
.. code:: c
.. code-block:: c
/*Register at least one display before you register any input devices*/
lv_indev_t * indev = lv_indev_create();
@ -35,7 +35,7 @@ Touchpad, mouse or any pointer
Input devices that can click points on the screen belong to this
category.
.. code:: c
.. code-block:: c
lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER);
...
@ -68,10 +68,10 @@ the last clicked widget will be either scrolled or it's value will be incremente
As this behavior is tightly related to the last clicked widget, the crown support is
an extension of the pointer input device. Just set ``data->diff`` to the number of
turned steps and LVGL will automatically send :cpp:enum:`LV_EVENT_ROTARY` or scroll the widget based on the
turned steps and LVGL will automatically send :cpp:enumerator:`LV_EVENT_ROTARY` or scroll the widget based on the
``editable`` flag in the widget's class. Non-editable widgets are scrolled and for editable widgets the event is sent.
To get the steps in an event callback use :cpp:func:`int32_t diff = lv_event_get_rotary_diff(e)`
To get the steps in an event callback use :cpp:func:`lv_event_get_rotary_diff`
The rotary sensitivity can be adjusted on 2 levels:
@ -101,7 +101,7 @@ To use a keyboard/keypad:
- Use ``LV_KEY_...`` to navigate among the objects in the group. See
``lv_core/lv_group.h`` for the available keys.
.. code:: c
.. code-block:: c
lv_indev_set_type(indev, LV_INDEV_TYPE_KEYPAD);
@ -137,7 +137,7 @@ In short, the Encoder input devices work like this:
To use an *Encoder* (similarly to the *Keypads*) the objects should be
added to groups.
.. code:: c
.. code-block:: c
lv_indev_set_type(indev, LV_INDEV_TYPE_ENCODER);
@ -150,8 +150,8 @@ added to groups.
else data->state = LV_INDEV_STATE_RELEASED;
}
Using buttons with Encoder logic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using Buttons with Encoder Logic
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In addition to standard encoder behavior, you can also utilize its logic
to navigate(focus) and edit widgets using buttons. This is especially
@ -168,7 +168,7 @@ You need to have 3 buttons available:
If you hold the keys it will simulate an encoder advance with period
specified in ``indev_drv.long_press_repeat_time``.
.. code:: c
.. code-block:: c
lv_indev_set_type(indev, LV_INDEV_TYPE_ENCODER);
@ -199,7 +199,7 @@ should look like ``const lv_point_t points_array[] = { {12,30},{60,90}, ...}``
:important: The points_array can't go out of scope. Either declare it as a global variable
or as a static variable inside a function.`
.. code:: c
.. code-block:: c
lv_indev_set_type(indev, LV_INDEV_TYPE_BUTTON);
@ -279,7 +279,7 @@ might need to read it by polling file descriptor (fd).
You can do this in the following way:
.. code:: c
.. code-block:: c
/*Update the input device's running mode to LV_INDEV_MODE_EVENT*/
lv_indev_set_mode(indev, LV_INDEV_MODE_EVENT);

7
docs/widgets/msgbox.rst
View File

@ -42,13 +42,16 @@ Create a message box
:cpp:expr:`lv_msgbox_create(parent)` creates a message box.
If ``parent`` is ``NULL`` the message box will be modal.
Get the parts
E.g. ``const char * btn_txts[] = {"Ok", "Cancel", NULL}``.
Get the Parts
-------------
The building blocks of the message box can be obtained using the
following functions:
.. code:: c
.. code-block:: c
lv_obj_t * lv_msgbox_get_content(lv_obj_t * obj);
lv_obj_t * lv_msgbox_get_title(lv_obj_t * obj);

18
docs/widgets/scale.rst
View File

@ -52,20 +52,20 @@ Configure ticks
Set the number of total ticks with :cpp:expr:`lv_scale_set_total_tick_count(scale, total_tick_count)`
and then configure the major tick being every Nth ticks with :cpp:expr:`lv_scale_set_major_tick_every(scale, nth_tick)`.
Labels on major ticks can be configured with :cpp:expr:`lv_scale_set_label_show(scale, show_label)`,
set `show_label` to true if labels should be drawn, :cpp:expr:`false` to hide them.
If instead of a numerical value in the major ticks a text is required they can be set
with :cpp:expr:`lv_scale_set_text_src(scale, custom_labels)` using ``NULL`` as the last element,
i.e. :cpp:expr:`static char * custom_labels[3] = {"One", "Two", NULL};`.
Labels on major ticks can be configured with :cpp:expr:`lv_scale_set_label_show(scale, show_label)`,
set `show_label` to true if labels should be drawn, :cpp:expr:`false` to hide them.
If instead of a numerical value in the major ticks a text is required they can be set
with :cpp:expr:`lv_scale_set_text_src(scale, custom_labels)` using ``NULL`` as the last element,
i.e. ``static char * custom_labels[3] = {"One", "Two", NULL}``.
<strong> NOTE: </strong> The major tick value is calculated with the :cpp:expr:`lv_map` API (when not setting the custom labels),
this calculation takes into consideration the total tick number and the scale range, so the label drawn can present rounding errors
when the calculated value is a float number.
The length of the ticks can be configured with the length style property on the :cpp:enumerator:`LV_PART_INDICATOR`
for major ticks and :cpp:enumerator:`LV_PART_ITEMS` for minor ticks, for example with local style:
:cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_INDICATOR);` for major ticks
and :cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_ITEMS);` for minor ticks.
The length of the ticks can be configured with the length style property on the :cpp:enumerator:`LV_PART_INDICATOR`
for major ticks and :cpp:enumerator:`LV_PART_ITEMS` for minor ticks, for example with local style:
:cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_INDICATOR)` for major ticks
and :cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_ITEMS)` for minor ticks.
Sections
--------