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

fix(docs): fix most sphinx warnings (#6916)

Browse Source 
Co-authored-by: Kevin Schlosser <kdschlosser@users.noreply.github.com>
Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com>
This commit is contained in:
Victor Wheeler
2024-09-30 06:57:22 -06:00
committed by GitHub
parent a298c245ac
commit 0458acd998
98 changed files with 1389 additions and 1070 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
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
@@ -21,8 +21,9 @@ 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 to Your Project
------------------------
Add LVGL into your project
--------------------------
If you would rather try LVGL on your own project follow these steps:
@@ -30,15 +31,13 @@ If you would rather try LVGL on your own project follow these steps:
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.
- 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.
- 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.
- Call :cpp:func:`lv_init`
- Create a display.
@@ -107,39 +106,36 @@ If you would rather try LVGL on your own project follow these steps:
redraw the screen if required, handle input devices, animation etc.
For a more detailed guide go to the :ref:`porting`
section.
For a more detailed guide go to the :ref:`porting` section.
Learn the Basics
Learn the basics
----------------
.. _quick-overview_widgets:
Widgets
~~~~~~~
The graphical elements like Buttons, Labels, Sliders, Charts etc. are
called objects or widgets. Go to :ref:`widgets` to see the
full list of available widgets.
The graphical elements like Buttons, Labels, Sliders, Charts etc. are called objects or widgets.
Go to :ref:`widgets` to see the full list of available widgets.
Every object has a parent object where it is created. For example, if a
label is created on a button, the button is the parent of label.
Every object has a parent object where it is created. For example, if a label is created on a button,
the button is the parent of label.
The child object moves with the parent and if the parent is deleted the
children will be deleted too.
The child object moves with the parent and if the parent is deleted the children will be deleted too.
Children can be visible only within their parent's bounding area. In
other words, the parts of the children outside the parent are clipped.
Children can be visible only within their parent's bounding area. In other words, the parts of the
children outside the parent are clipped.
A Screen is the "root" parent. You can have any number of screens.
To get the current screen call :cpp:func:`lv_screen_active`, and to load a screen
use :cpp:expr:`lv_screen_load(scr1)`.
To get the current screen call :cpp:func:`lv_screen_active`, and to load a screen use :cpp:expr:`lv_screen_load(scr1)`.
You can create a new object with ``lv_<type>_create(parent)``. It will return an :cpp:type:`lv_obj_t` ``*`` variable
that can be used as a reference to the object to set its parameters.
You can create a new object with ``lv_<type>_create(parent)``. It will
return an :cpp:type:`lv_obj_t` ``*`` variable that can be used as a reference to the
object to set its parameters.
For example:
@@ -147,8 +143,8 @@ For example:
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:
To set some basic attributes ``lv_obj_set_<parameter_name>(obj, <value>)`` functions can be used. For example:
.. code-block:: c
@@ -156,26 +152,27 @@ example:
lv_obj_set_y(btn1, 10);
lv_obj_set_size(btn1, 200, 50);
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:
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-block:: c
lv_slider_set_value(slider1, 70, LV_ANIM_ON);
To see the full API visit the documentation of the widgets or the
related header file
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
~~~~~~
Events are used to inform the user that something has happened with an
object. You can assign one or more callbacks to an object which will be
called if the object is clicked, released, dragged, being deleted, etc.
Events are used to inform the user that something has happened with an object. You can assign one or more
callbacks to an object which will be called if the object is clicked, released, dragged, being deleted, etc.
A callback is assigned like this:
@@ -190,8 +187,8 @@ A callback is assigned like this:
printf("Clicked\n");
}
:cpp:enumerator:`LV_EVENT_ALL` can be used instead of :cpp:enumerator:`LV_EVENT_CLICKED` to invoke
the callback for any event.
:cpp:enumerator:`LV_EVENT_ALL` can be used instead of :cpp:enumerator:`LV_EVENT_CLICKED` to invoke the callback for any event.
From :cpp:expr:`lv_event_t * e` the current event code can be retrieved with:
@@ -199,14 +196,17 @@ From :cpp:expr:`lv_event_t * e` the current event code can be retrieved with:
lv_event_code_t code = lv_event_get_code(e);
The object that triggered the event can be retrieved with:
.. code-block:: c
lv_obj_t * obj = lv_event_get_target(e);
To learn all features of the events go to the :ref:`events` section.
.. _quick-overview_parts:
Parts
@@ -256,20 +256,18 @@ To manually add or remove states use:
lv_obj_add_state(obj, LV_STATE_...);
lv_obj_remove_state(obj, LV_STATE_...);
.. _quick-overview_styles:
.. _quick-overview_styles:
Styles
~~~~~~
A style instance contains properties such as background color, border
width, font, etc. that describe the appearance of objects.
A style instance contains properties such as background color, border width, font, etc. that describe the
appearance of objects.
Styles are represented with :cpp:struct:`lv_style_t` variables. Only their pointer
is saved in the objects so they need to be defined as static or global.
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:
Styles are represented with :cpp:struct:`lv_style_t` variables. Only their pointer is saved in the objects so
they need to be defined as static or global. 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-block:: c
@@ -278,73 +276,76 @@ 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:`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
slider is pressed:
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-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-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-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-block:: c
lv_obj_add_style(btn1, &style1, 0); /*Equal to LV_PART_MAIN | LV_STATE_DEFAULT*/
Styles can be cascaded (similarly to CSS). It means you can add more
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:
Styles can be cascaded (similarly to CSS). It means you can add more 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-block:: c
lv_obj_add_style(btn1, &style_btn, 0);
lv_obj_add_style(btn1, &style1_btn_red, 0);
If a property is not set on for the current state, the style with
:cpp:enumerator:`LV_STATE_DEFAULT` will be used. A default value is used if the
property is not defined in the default state.
Some properties (typically the text-related ones) can be inherited. This
means if a property is not set in an object it will be searched for in
its parents too. For example, you can set the font once in the screen's
style and all text on that screen will inherit it by default.
If a property is not set on for the current state, the style with :cpp:enumerator:`LV_STATE_DEFAULT` will be used.
A default value is used if the property is not defined in the default state.
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:
Some properties (typically the text-related ones) can be inherited. This means if a property is not set in an object
it will be searched for in its parents too. For example, you can set the font once in the screen's 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-block:: c
lv_obj_set_style_bg_color(slider1, lv_color_hex(0x2080bb), LV_PART_INDICATOR | LV_STATE_PRESSED);
To learn all the features of styles see the :ref:`styles` section.
.. _quick-overview_themes:
Themes
~~~~~~
Themes are the default styles for objects. Styles from a theme are
applied automatically when objects are created.
Themes are the default styles for objects. Styles from a theme are applied automatically when objects are created.
The theme for your application is a compile time configuration set in ``lv_conf.h``.
The theme for your application is a compile time configuration set in
``lv_conf.h``.
.. _quick-overview_examples:
@@ -354,6 +355,7 @@ Examples
.. include:: ../examples/get_started/index.rst
.. _quick-overview_micropython:
@@ -364,14 +366,14 @@ Learn more about :ref:`micropython`.
.. code-block:: python
# Initialize
import display_driver
import lvgl as lv
# Initialize
import display_driver
import lvgl as lv
# Create a button with a label
scr = lv.obj()
btn = lv.button(scr)
btn.align(lv.ALIGN.CENTER, 0, 0)
label = lv.label(btn)
label.set_text('Hello World!')
lv.screen_load(scr)
# Create a button with a label
scr = lv.obj()
btn = lv.button(scr)
btn.align(lv.ALIGN.CENTER, 0, 0)
label = lv.label(btn)
label.set_text('Hello World!')
lv.screen_load(scr)