Mirrors_UI_SDK/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2026-05-26 19:15:38 +08:00
Code Issues Actions 25 Packages Projects Releases Wiki Activity

docs(misc): fix typos, grammar and add missing function links to api pages (#9126)

Browse Source
This commit is contained in:
Victor Wheeler
2025-10-27 12:50:26 -06:00
committed by GitHub
parent b48b6217af
commit ec060c97e5
5 changed files with 51 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api_doc_builder.py
+9 -9
View File
@@ -4,11 +4,11 @@ Create and provide links to API pages in LVGL doc build.
Uses doxygen_xml.py module to:
- Prep and run Doxygen
- Prep and run Doxygen,
- make Doxygen XML output available, and
- make Doxygen-documented symbols from the C code available.
Because these 3 files are acceptable in a C project:
Because these 5 files are acceptable in a C project:
1. ./path/to/one/aaa.c
2. ./path/to/one/aaa.h
@@ -21,19 +21,19 @@ we see that:
- duplicate filename stems ('aaa' above) are acceptable, and
- they must not only be differentiated by their extensions, but also by their path.
On the other hand, Sphinx link reference names for :ref:`link_ref_name` link
references must be unique throughout a document project. Since API pages are
On the other hand, Sphinx link target names for :ref:`link_ref_name` link
target names must be unique throughout a document project. Since API pages are
generated from C source files, to make this effective, they must include:
A. at least part of the path,
B. filename stem, and
C. extension
in the link reference names. Prior to 11-Aug-2025, link reference names were formed
in the link target names. Prior to 11-Aug-2025, link target names were formed
using ONLY the filename stem. This created a conflict when an example of #4 above
appeared in the LVGL code, and caused a doc-build failure because the API-page link
reference names to #2 and #4 were identical, and Sphinx (correctly) does not allow
that. So after 11-Aug-2025, these link reference names are now differentiated all 3
target names to #2 and #4 were identical, and Sphinx (correctly) does not allow
that. So after 11-Aug-2025, these link target names are now differentiated via all 3
of A, B and C above.
.. note::
@@ -565,7 +565,7 @@ def _add_hyperlinks_to_eligible_files(intermediate_dir: str,
if html_includes:
# Convert `html_includes` set to a list of strings containing the
# Sphinx hyperlink syntax "link references". Example from above:
# Sphinx hyperlink syntax "link target names". Example from above:
# [':ref:`lv_draw_line_h`\n',
# ':ref:`lv_draw_sdl_h`\n',
# ':ref:`lv_draw_sw_blend_to_i1_h`\n',
@@ -576,7 +576,7 @@ def _add_hyperlinks_to_eligible_files(intermediate_dir: str,
)
# Convert that list to a single string of Sphinx hyperlink
# references with blank lines between them.
# target names with blank lines between them.
# :ref:`lv_draw_line_h`
#
# :ref:`lv_draw_sdl_h`
docs/src/conf.py
+2
View File
@@ -452,6 +452,8 @@ todo_include_todos = True
# -------------------------------------------------------------------------
# See https://sphinx-sitemap.readthedocs.io/en/latest/index.html
sitemap_url_scheme = "{link}"
# Prettyfy output using 4 spaces to indent.
sitemap_prettify = 4
# -------------------------------------------------------------------------
# Options for breathe extension
docs/src/details/common-widget-features/events.rst
+17 -3
View File
@@ -13,11 +13,12 @@ interesting to the user, e.g. when a Widget:
- has its value changed
- is redrawn, etc.
Besides Widgets, events can be registered on displays and input devices as well.
Besides Widgets, events can be registered for displays and input devices as well.
It is not detailed below, but you can do this by changing the prefix of the functions
from ``lv_obj_`` to ``lv_display_`` or ``lv_indev_``.
.. _adding_events_to_a_widget:
Adding Events to a Widget
@@ -81,6 +82,7 @@ In the very same way, events can be attached to input devices and displays like
lv_indev_add_event_cb(indev, event_cb, LV_EVENT_CLICKED, NULL);
Removing Event(s) from Widgets
******************************
@@ -97,6 +99,7 @@ Removing Event(s) from Widgets
}
.. _events_codes:
Event Codes
@@ -116,6 +119,7 @@ are sent,
The following event codes exist:
.. _indev_events:
Input Device Events
@@ -146,6 +150,7 @@ Input Device Events
- :cpp:enumerator:`LV_EVENT_HOVER_OVER`: Indev hover over Widget
- :cpp:enumerator:`LV_EVENT_HOVER_LEAVE`: Indev hover leave Widget
Drawing Events
--------------
@@ -167,6 +172,7 @@ Drawing Events
LVGL will generate an assertion failure with a message
indicating that invalidating an area is not allowed during rendering.
Special Events
--------------
@@ -176,6 +182,7 @@ Special Events
- :cpp:enumerator:`LV_EVENT_READY`: A process has finished
- :cpp:enumerator:`LV_EVENT_CANCEL`: A process has been cancelled
Other Events
------------
@@ -193,6 +200,7 @@ Other Events
- :cpp:enumerator:`LV_EVENT_LAYOUT_CHANGED`: The children position has changed due to a layout recalculation
- :cpp:enumerator:`LV_EVENT_GET_SELF_SIZE`: Get the internal size of a widget
Display Events
--------------
@@ -221,6 +229,7 @@ user notify a Widget to refresh itself. Some examples:
- add/remove styles to/from a Widget if a limit is exceeded, etc
Sending Events Manually
***********************
@@ -241,6 +250,7 @@ The same works for display and input devices with
``lv_indev_send_event(widget, <EVENT_CODE>, &some_data)``.
Fields of lv_event_t
********************
@@ -262,9 +272,10 @@ contains all data about the event. The following values can be retrieved from it
Only call :cpp:expr:`lv_event_get_target_obj(e)` when the event target is known to be a Widget.
Calling it for Display or Indev targets is considered Undefined Behavior.
.. _event_bubbling:
.. _event_bubbling:
Event Bubbling
**************
@@ -277,6 +288,8 @@ The *target* parameter of the event is always the current target Widget,
not the original Widget. To get the original target call
:cpp:expr:`lv_event_get_target_obj(e)` in the event handler.
.. _event_trickle:
Event Trickle
@@ -295,8 +308,8 @@ not the original Widget. To get the original target call
:cpp:expr:`lv_event_get_target_obj(e)` in the event handler.
.. _events_examples:
.. _events_examples:
Examples
********
@@ -304,6 +317,7 @@ Examples
.. include:: ../../examples/event/index.rst
.. _events_api:
API
docs/src/details/integration/overview/timer_handler.rst
+3 -3
View File
@@ -68,13 +68,13 @@ When No Timers Are Ready
:c:func:`lv_timer_handler` will return :c:macro:`LV_NO_TIMER_READY` (``UINT32_MAX``)
if there are no running timers. This can happen if there are no indevs or they are disabled with `lv_indev_enable()`, running
animations, or running user-created timers. :c:func:`lv_timer_handler` will continue
animations, or running user-created timers. :cpp:func:`lv_timer_handler` will continue
to return :c:macro:`LV_NO_TIMER_READY` until there is a running timer. Display
timers will stay paused when there is no reason to refresh.
:c:func:`lv_timer_handler` should be called after something is created, deleted, or
:cpp:func:`lv_timer_handler` should be called after something is created, deleted, or
modified so that a refresh will be performed if necessary. In practice this means
waiting without a timeout for some external event. After the
external events are received and handled, :c:func:`lv_timer_handler` should be
external events are received and handled, :cpp:func:`lv_timer_handler` should be
called again.
.. code-block:: c
docs/src/details/xml/ui_elements/animations.rst
+20 -13
View File
@@ -12,8 +12,10 @@ XML animations are built on top of :ref:`Timeline animations <animations_timelin
Timelines are composed of simple animations. For example: *"change the ``bg_opa``
of ``my_button_2`` from 0 to 255 in 500 ms."*
Each component can define its own timeline animations, which can then be played by the
component itself or by any parent component.
Each Component can define its own timeline animations, which can then be played by the
Component itself or by any parent Component.
Defining Timelines
******************
@@ -29,7 +31,7 @@ Example:
<component>
<animations>
<!-- Show the component and its children -->
<!-- Show Component and its children -->
<timeline name="load">
<animation prop="translate_x" target="self" start="-30" end="0" duration="500"/>
<animation prop="opa" target="text" start="0" end="255" duration="500" delay="200"/>
@@ -61,7 +63,7 @@ Supported properties of ``<animation>`` are:
- ``prop``: Style property to animate. All integer style properties are supported (colors are not).
- ``selector``: Style selector, e.g. ``knob|pressed``. Default: ``main|default``.
- ``target``: Name of the UI element to animate. ``self`` refers to the root element of the component (the ``<view>``).
- ``target``: Name of the UI element to animate. ``self`` refers to the root element of the Component (the ``<view>``).
- ``start``: Start value (integer only).
- ``end``: End value (integer only).
- ``duration``: Duration of the animation in milliseconds.
@@ -70,15 +72,17 @@ Supported properties of ``<animation>`` are:
``<include_timeline>`` also can be used in ``<timeline>``\ s to "merge" the animations
of another timeline. Imagine that in the example above ``my_icon`` defines a ``"show_up"`` timeline
which fades in and scales up the icon. All these are described in the ``my_icon.xml`` in an
which fades in and enlarges the icon. All these are described in the ``my_icon.xml`` in an
encapsulated way but can be referenced in other timelines.
To include a timeline, the following properties shall be used:
To include a timeline, use the following properties:
- ``target``: name of the target UI element whose timeline should be included. ``self`` refers to the root element of the component (the ``<view>``).
- ``timeline``: name of the timeline to include. Shall be defined in the ``target``'s XML file.
- ``target``: name of the target UI element whose timeline should be included. ``self`` refers to the root element of the Component (the ``<view>``).
- ``timeline``: name of the timeline to include. Must be defined in the ``target``'s XML file.
- ``delay``: Delay before starting in milliseconds. Default is 0.
Playing Timelines
*****************
@@ -98,10 +102,13 @@ Example:
</view>
You set a ``target`` UI element and select one of its ``timeline``\ s to play.
If ``target="self"``, the timeline is looked up in the current component/widget/screen
If ``target="self"``, the timeline is looked up in the current Component/widget/Screen
(i.e. in the current XML file).
You can also set a ``delay`` and ``reverse="true"`` when playing a timeline.
Under the Hood
**************
@@ -111,16 +118,16 @@ When an XML file is registered, the contents of the ``<animations>`` section are
and the ``<timeline>``'s data is stored as a "blueprint". The descriptors store the targets'
names as strings.
When an instance of a component or screen is created, as the last step ``lv_anim_timeline``\ s are
When an instance of a Component or Screen is created, as the last step ``lv_anim_timeline``\ s are
created and initialized from the saved "blueprints". If ``<include_timeline>``\ s are also used,
the requested timeline is included in the component's timeline at this point too.
the requested timeline is included in the Component's timeline at this point too.
As all the children are also created at this point, the saved animation target names are resolved
to pointers by using :cpp:expr:`lv_obj_find_by_name`.
The created timeline instances and their names are saved in the component's instance.
The created timeline instances and their names are saved in the Component's instance.
Since each instance has its own timeline, you can have multiple components (e.g. 10 ``<list_item>``\ s)
Since each instance has its own timeline, you can have multiple Components (e.g. 10 ``<list_item>``\ s)
and play their ``load`` timelines independently with different delays.
When a ``<play_timeline_event>`` is added to a UI element, the target and timeline