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

feat(docs): batch 3 of proofread/edited docs (#7180)

Browse Source
This commit is contained in:
Victor Wheeler
2024-11-04 02:42:40 -07:00
committed by GitHub
parent 58e2d508e1
commit 8f59bdc6a7
6 changed files with 107 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/CODING_STYLE.rst
View File

@@ -45,6 +45,7 @@ Naming conventions
- ``alloc`` allocate - ``alloc`` allocate
- ``ctrl`` control - ``ctrl`` control
- ``pos`` position - ``pos`` position
- Avoid adding new abbreviations - Avoid adding new abbreviations
Coding guide Coding guide
@@ -57,17 +58,17 @@ Coding guide
- Functions: - Functions:
- Write function with single responsibility. - Write functions that use the single-responsibility principle.
- Make the functions ``static`` where possible. - Make functions ``static`` when not part of that object's public API (where possible).
- Variables: - Variables:
- One line, one declaration (BAD: char x, y;) - One line, one declaration (BAD: char x, y;).
- Use ``<stdint.h>`` (*uint8_t*, *int32_t* etc) - Use ``<stdint.h>`` (*uint8_t*, *int32_t* etc).
- Declare variables where needed (not all at function start) - Declare variables where needed (not all at function start).
- Use the smallest required scope - Use the smallest required scope.
- Variables in a file (outside functions) are always *static* - Variables in a file (outside functions) are always *static*.
- Do not use global variables (use functions to set/get static variables) - Do not use global variables (use functions to set/get static variables).
Comments Comments
-------- --------
@@ -88,7 +89,7 @@ like this:
type_name_t * lv_function_name(lv_obj_t * parent); type_name_t * lv_function_name(lv_obj_t * parent);
The normal comment prefix ``/**`` causes the comment to document the code member The normal comment prefix ``/**`` causes the comment to document the code member
coming *after* the comment. When documenting a code member that is *before* the *after* the comment. When documenting a code member that is *before* the
comment, such as a struct member, use ``/**<`` like this: comment, such as a struct member, use ``/**<`` like this:
.. code-block:: c .. code-block:: c
@@ -286,7 +287,7 @@ To learn more refer to the documentation of `MicroPython <integration/bindings/m
Formatting Formatting
---------- ----------
Here is example to show bracket placing and using of white space: Here is example to show bracket placement and use of white space:
.. code-block:: c .. code-block:: c

29
docs/README.md
View File

@@ -154,24 +154,26 @@ reStructuredText does not impose any particular heading levels assigned to certa
If you are creating a new .RST file, use this convention: If you are creating a new .RST file, use this convention:
===== ```
Title =====
===== Title
=====
Chapter Chapter
******* *******
Section Section
------- -------
Sub Section Sub Section
~~~~~~~~~~~ ~~~~~~~~~~~
Sub Sub Section Sub Sub Section
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
Sub Sub Sub Section Sub Sub Sub Section
''''''''''''''''''' '''''''''''''''''''
```
Note that the "underlining" can be longer than the heading title, but if it is shorter, the documentation-generation logic will fail with an error. Note that the "underlining" can be longer than the heading title, but if it is shorter, the documentation-generation logic will fail with an error.
@@ -187,6 +189,7 @@ For improved readability in the .RST file, place at least 2 blank lines above se
* `.. code-block::` is the only directive that should be used. Note carefully that unlike the **link target** directive above, this directive has 2 colons. (The only ReST and sphinx directives that are valid with one colon are **link target**s as shown above.) Lone `::`, `:code:` or `.. code:` should not be used. * `.. code-block::` is the only directive that should be used. Note carefully that unlike the **link target** directive above, this directive has 2 colons. (The only ReST and sphinx directives that are valid with one colon are **link target**s as shown above.) Lone `::`, `:code:` or `.. code:` should not be used.
* If you want to separate code into easier-to-understand sections you can do so with a single empty line. * If you want to separate code into easier-to-understand sections you can do so with a single empty line.
* For syntax highlighting appropriate to the language in the code block, specify the language after the directive. Some examples are: * For syntax highlighting appropriate to the language in the code block, specify the language after the directive. Some examples are:
- `.. code-block:: c`, - `.. code-block:: c`,
- `.. code-block:: cpp`, - `.. code-block:: cpp`,
- `.. code-block:: python`, - `.. code-block:: python`,

10
docs/details/widgets/animimg.rst
View File

@@ -30,15 +30,15 @@ Usage
Image sources Image sources
------------- -------------
To set the image in a state, use the To set the image animation images sources, use
:cpp:expr:`lv_animimg_set_src(imagebutton, dsc[], num)`. :cpp:expr:`lv_animimg_set_src(animimg, dsc[], num)`.
Using the inner animation Using the inner animation
------------------------- -------------------------
For more advanced use cases, the animation internally used by the image can be For more advanced use cases, the animation used internally by the image can be
retrieved using the :cpp:expr:`lv_animimg_get_anim(image)`. This way, the retrieved using :cpp:expr:`lv_animimg_get_anim(animimg)`. Using this, you can
:ref:`Animation <animation>` functions can be used, for example to use the :ref:`Animation <animation>` functions, for example, to
override the animation values using the override the animation values using the
:cpp:expr:`lv_anim_set_values(anim, start, end)` or to set a callback :cpp:expr:`lv_anim_set_values(anim, start, end)` or to set a callback
on the animation completed event. on the animation completed event.

101
docs/details/widgets/arc.rst
View File

@@ -4,6 +4,7 @@
Arc (lv_arc) Arc (lv_arc)
============ ============
Overview Overview
******** ********
@@ -26,6 +27,7 @@ Parts and Styles
size is the same as the indicator's width. Larger padding makes it size is the same as the indicator's width. Larger padding makes it
larger, smaller padding makes it smaller. larger, smaller padding makes it smaller.
.. _lv_arc_usage: .. _lv_arc_usage:
Usage Usage
@@ -41,18 +43,20 @@ is 0..100.
The indicator arc is drawn on the main part's arc. This if the value is The indicator arc is drawn on the main part's arc. This if the value is
set to maximum the indicator arc will cover the entire "background" arc. set to maximum the indicator arc will cover the entire "background" arc.
To set the start and end angle of the background arc use the To set the start and end angle of the background arc use any of these functions:
:cpp:expr:`lv_arc_set_bg_angles(arc, start_angle, end_angle)` functions or
``lv_arc_set_bg_start/end_angle(arc, angle)``. - :cpp:expr:`lv_arc_set_bg_start_angle(arc, angle)`
- :cpp:expr:`lv_arc_set_bg_end_angle(arc, angle)`
- :cpp:expr:`lv_arc_set_bg_angles(arc, start_angle, end_angle)`
Zero degrees is at the middle right (3 o'clock) of the Widget and the Zero degrees is at the middle right (3 o'clock) of the Widget and the
degrees are increasing in clockwise direction. The angles should be in degrees increasing in the clockwise direction. The angle values should be in
the [0;360] range. the range [0..360].
Rotation Rotation
-------- --------
An offset to the 0 degree position can be added with An offset to the 0-degree position can be added with
:cpp:expr:`lv_arc_set_rotation(arc, deg)`. :cpp:expr:`lv_arc_set_rotation(arc, deg)`.
Mode Mode
@@ -60,45 +64,48 @@ Mode
The arc can be one of the following modes: The arc can be one of the following modes:
- :cpp:enumerator:`LV_ARC_MODE_NORMAL` The indicator arc is drawn from the minimum value to the current. - :cpp:enumerator:`LV_ARC_MODE_NORMAL` Indicator arc is drawn clockwise from minimum to current value.
- :cpp:enumerator:`LV_ARC_MODE_REVERSE` The indicator arc is drawn counter-clockwise - :cpp:enumerator:`LV_ARC_MODE_REVERSE` Indicator arc is drawn counter-clockwise
from the maximum value to the current. from maximum to current value.
- :cpp:enumerator:`LV_ARC_MODE_SYMMETRICAL` The indicator arc is drawn from the middle point to the current value. - :cpp:enumerator:`LV_ARC_MODE_SYMMETRICAL` Indicator arc is drawn from middle point to current value.
The mode can be set by :cpp:expr:`lv_arc_set_mode(arc, LV_ARC_MODE_...)` and The mode can be set by :cpp:expr:`lv_arc_set_mode(arc, LV_ARC_MODE_...)` and
used only if the angle is set by :cpp:func:`lv_arc_set_value` or the arc is has no effect until angle is set by :cpp:func:`lv_arc_set_value` or value of the arc
adjusted by finger. is changed by pointer input (finger, mouse, etc.).
Change rate Change rate
----------- -----------
If the arc is pressed the current value will set with a limited speed When the arc's value is changed by pointer input (finger, mouse, etc.), the rate of
according to the set *change rate*. The change rate is defined in its change is limited according to its *change rate*. Change rate is defined in
degree/second unit and can be set with degrees/second units and can be set with
:cpp:expr:`lv_arc_set_change_rage(arc, rate)` :cpp:expr:`lv_arc_set_change_rate(arc, rate)`
Knob offset Knob offset
----------- -----------
Changing the knob offset allows the location of the knob to be moved Changing the knob offset allows the location of the knob to be moved
relative to the end of the arc The knob offset can be set by relative to the end of the arc. The knob offset can be set by
:cpp:expr:`lv_arc_set_knob_offset(arc, offset_angle)`, will only be visible if :cpp:expr:`lv_arc_set_knob_offset(arc, offset_angle)`, and will only be visible if
:cpp:enumerator:`LV_PART_KNOB` is visible :cpp:enumerator:`LV_PART_KNOB` is visible.
Setting the indicator manually Setting indicator programmatically
------------------------------ ----------------------------------
It's also possible to set the angles of the indicator arc directly with It is possible to set indicator angle directly with any of these functions:
:cpp:expr:`lv_arc_set_angles(arc, start_angle, end_angle)` function or
``lv_arc_set_start/end_angle(arc, start_angle)``. In this case the set
"value" and "mode" are ignored.
In other words, the angle and value settings are independent. You should - :cpp:expr:`lv_arc_set_start_angle(arc, start_angle)`
exclusively use one or the other. Mixing the two might result in - :cpp:expr:`lv_arc_set_end_angle(arc, end_angle)`
unintended behavior. - :cpp:expr:`lv_arc_set_angles(arc, start_angle, end_angle)`
To make the arc non-adjustable, remove the style of the knob and make When used, "value" and "mode" are ignored.
the Widget non-clickable:
In other words, the angle and value settings are independent. You should
exclusively use one or the other of the two methods. Mixing the two could
result in unintended behavior.
To make the arc non-adjustable by external input, remove the style of the knob and
make the Widget non-clickable:
.. code-block:: c .. code-block:: c
@@ -110,51 +117,53 @@ Interactive area
By default :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is disabled which By default :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is disabled which
means the arc's whole area is interactive. means the arc's whole area is interactive.
As usual :cpp:func:`lv_obj_set_ext_click_size` can be used to increase As usual :cpp:func:`lv_obj_set_ext_click_area` can be used to increase
the sensitive area outside the arc by a specified number of pixels. the area that will respond to pointer input (touch, mouse, etc.) outside the arc by a
specified number of pixels.
If :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is enabled the arc will be sensitive only If :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is enabled the arc will be sensitive only
in the range of start and end background angles and on the arc itself (not inside the arc). in the range between start and end background angles and on the arc itself (not inside the arc).
In this case ``ext_click_size`` makes the sensitive area ticker both inward and outward. In this case ``ext_click_area`` makes the sensitive area ticker both inward and outward.
Additionally, a tolerance of :cpp:expr:`lv_dpx(50)` pixels is applied to each angle, extending the Additionally, a tolerance of :cpp:expr:`lv_dpx(50)` pixels is applied to each angle, extending the
hit-test range along the arc's length. hit-test range along the arc's length.
Place another Widget to the knob Place another Widget on the knob
-------------------------------- --------------------------------
Another Widget can be positioned according to the current position of Another Widget can be positioned according to the current position of
the arc in order to follow the arc's current value (angle). To do this the arc in order to follow the arc's current value (angle). To do this
use :cpp:expr:`lv_arc_align_obj_to_angle(arc, obj_to_align, radius_offset)`. use :cpp:expr:`lv_arc_align_obj_to_angle(arc, widget_to_align, radius_offset)`.
Similarly Similarly
:cpp:expr:`lv_arc_rotate_obj_to_angle(arc, obj_to_rotate, radius_offset)` can be :cpp:expr:`lv_arc_rotate_obj_to_angle(arc, widget_to_rotate, radius_offset)` can be
used to rotate the Widget to the current value of the arc. used to rotate the Widget to the current value of the arc.
It's a typical use case to call these functions in the ``VALUE_CHANGED`` A typical use case is to call these functions in the ``VALUE_CHANGED``
event of the arc. event of the arc.
.. _lv_arc_events: .. _lv_arc_events:
Events Events
****** ******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when the arc is pressed/dragged to - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when arc is pressed/dragged to
set a new value. a new value.
- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent - :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent
with the following types: with the following types:
- :cpp:enumerator:`LV_ARC_DRAW_PART_BACKGROUND` The background arc. - :cpp:enumerator:`LV_ARC_DRAW_PART_BACKGROUND` The background arc.
- ``part``: :cpp:enumerator:`LV_PART_MAIN` - ``part``: :cpp:enumerator:`LV_PART_MAIN`
- ``p1``: center of the arc - ``p1``: center of arc
- ``radius``: radius of the arc - ``radius``: radius of arc
- ``arc_dsc`` - ``arc_dsc``
- :cpp:enumerator:`LV_ARC_DRAW_PART_FOREGROUND` The foreground arc. - :cpp:enumerator:`LV_ARC_DRAW_PART_FOREGROUND` The foreground arc.
- ``part``: :cpp:enumerator:`LV_PART_INDICATOR` - ``part``: :cpp:enumerator:`LV_PART_INDICATOR`
- ``p1``: center of the arc - ``p1``: center of arc
- ``radius``: radius of the arc - ``radius``: radius of arc
- ``arc_dsc`` - ``arc_dsc``
- LV_ARC_DRAW_PART_KNOB The knob - LV_ARC_DRAW_PART_KNOB The knob
@@ -177,8 +186,8 @@ Events
Keys Keys
**** ****
- ``LV_KEY_RIGHT/UP`` Increases the value by one. - ``LV_KEY_RIGHT/UP`` Increases value by one.
- ``LV_KEY_LEFT/DOWN`` Decreases the value by one. - ``LV_KEY_LEFT/DOWN`` Decreases value by one.
.. admonition:: Further Reading .. admonition:: Further Reading

28
docs/details/widgets/bar.rst
View File

@@ -7,25 +7,25 @@ Bar (lv_bar)
Overview Overview
******** ********
The bar Widget has a background and an indicator on it. The width of the The bar Widget has a background and an indicator. The length of the
indicator is set according to the current value of the bar. indicator against the background indicates the bar's current value.
Vertical bars can be created if the width of the Widget is smaller than Vertical bars can be created if the width of the Widget is smaller than
its height. its height.
Not only the end, but also the start value of the bar can be set, which Both the start and end values of the bar can be set. Changing the start value to a
changes the start position of the indicator. value other than the minimum value in its range changes the start position of the indicator.
.. _lv_bar_parts_and_styles: .. _lv_bar_parts_and_styles:
Parts and Styles Parts and Styles
**************** ****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the bar and it uses the typical - :cpp:enumerator:`LV_PART_MAIN` The bar's background. It uses the typical
background style properties. Adding padding makes the indicator background style properties. Adding padding makes the indicator
smaller or larger. The ``anim_time`` style property sets the smaller or larger. The ``anim_time`` style property sets the
animation time if the values set with :cpp:enumerator:`LV_ANIM_ON`. animation time if the values set with :cpp:enumerator:`LV_ANIM_ON`.
- :cpp:enumerator:`LV_PART_INDICATOR` The indicator itself; also uses all the typical - :cpp:enumerator:`LV_PART_INDICATOR` The bar's indicator; also uses all the typical
background properties. background properties.
.. _lv_bar_usage: .. _lv_bar_usage:
@@ -36,13 +36,13 @@ Usage
Value and range Value and range
--------------- ---------------
A new value can be set by A new value can be set with
``lv_bar_set_value(bar, new_value, LV_ANIM_ON/OFF)``. The value is :cpp:expr:`lv_bar_set_value(bar, new_value, LV_ANIM_ON/OFF)`. The value is
interpreted in a range (minimum and maximum values) which can be interpreted in a range (minimum and maximum values) which can be
modified with :cpp:expr:`lv_bar_set_range(bar, min, max)`. The default range is modified with :cpp:expr:`lv_bar_set_range(bar, min, max)`. The default range is
0..100, and the default drawing direction is from left to right in horizontal mode and 0..100, and the default drawing direction is from left to right in horizontal mode and
bottom to top in vertical mode. If the minimum value is greater than the maximum value, like bottom to top in vertical mode. If the minimum value is greater than the maximum value, like
100..0, the drawing direction changes to the opposite direction. 100..0, the drawing direction is reversed.
The new value in :cpp:func:`lv_bar_set_value` can be set with or without an The new value in :cpp:func:`lv_bar_set_value` can be set with or without an
animation depending on the last parameter (``LV_ANIM_ON/OFF``). animation depending on the last parameter (``LV_ANIM_ON/OFF``).
@@ -53,11 +53,11 @@ Modes
The bar can be one of the following modes: The bar can be one of the following modes:
- :cpp:enumerator:`LV_BAR_MODE_NORMAL` A normal bar as described above - :cpp:enumerator:`LV_BAR_MODE_NORMAL` A normal bar as described above
- :cpp:enumerator:`LV_BAR_MODE_SYMMETRICAL` Draw the indicator from the zero value to current value. Requires a negative - :cpp:enumerator:`LV_BAR_MODE_SYMMETRICAL` Draws indicator from zero value to current value. Requires a negative
minimum range and positive maximum range. minimum value and positive maximum value, e.g. [-100..100].
- :cpp:enumerator:`LV_BAR_MODE_RANGE` Allows setting the start value as well by - :cpp:enumerator:`LV_BAR_MODE_RANGE` Allows setting the start value as well with
``lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)``. The start :cpp:expr:`lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start
value always has to be smaller than the end value. value must be smaller than the end value.

10
docs/details/widgets/button.rst
View File

@@ -10,16 +10,18 @@ Overview
Buttons have no new features compared to the :ref:`base_widget`. Buttons have no new features compared to the :ref:`base_widget`.
They are useful for semantic purposes and have slightly different default settings. They are useful for semantic purposes and have slightly different default settings.
Buttons, by default, differ from Base Widget in the following ways: - Buttons, by default, differ from Base Widget in the following ways:
Not scrollable - Added to the default group - Default height and width
set to :cpp:enumerator:`LV_SIZE_CONTENT` - Not scrollable
- Added to the default group
- Default height and width set to :cpp:enumerator:`LV_SIZE_CONTENT`
.. _lv_button_parts_and_styles: .. _lv_button_parts_and_styles:
Parts and Styles Parts and Styles
**************** ****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the button. Uses the typical - :cpp:enumerator:`LV_PART_MAIN` The background of the button; uses the typical
background style properties. background style properties.
.. _lv_button_usage: .. _lv_button_usage: