mirror of
https://github.com/lvgl/lvgl.git
synced 2024-11-23 01:33:59 +08:00
feat(docs): batch 3 of proofread/edited docs (#7180)
This commit is contained in:
Victor Wheeler
GitHub
parent
58e2d508e1
commit
8f59bdc6a7
@ -45,6 +45,7 @@ Naming conventions
|
||||
- ``alloc`` allocate
|
||||
- ``ctrl`` control
|
||||
- ``pos`` position
|
||||
|
||||
- Avoid adding new abbreviations
|
||||
|
||||
Coding guide
|
||||
@ -57,17 +58,17 @@ Coding guide
|
||||
|
||||
- Functions:
|
||||
|
||||
- Write function with single responsibility.
|
||||
- Make the functions ``static`` where possible.
|
||||
- Write functions that use the single-responsibility principle.
|
||||
- Make functions ``static`` when not part of that object's public API (where possible).
|
||||
|
||||
- Variables:
|
||||
|
||||
- One line, one declaration (BAD: char x, y;)
|
||||
- Use ``<stdint.h>`` (*uint8_t*, *int32_t* etc)
|
||||
- Declare variables where needed (not all at function start)
|
||||
- Use the smallest required scope
|
||||
- Variables in a file (outside functions) are always *static*
|
||||
- Do not use global variables (use functions to set/get static variables)
|
||||
- One line, one declaration (BAD: char x, y;).
|
||||
- Use ``<stdint.h>`` (*uint8_t*, *int32_t* etc).
|
||||
- Declare variables where needed (not all at function start).
|
||||
- Use the smallest required scope.
|
||||
- Variables in a file (outside functions) are always *static*.
|
||||
- Do not use global variables (use functions to set/get static variables).
|
||||
|
||||
Comments
|
||||
--------
|
||||
@ -88,7 +89,7 @@ like this:
|
||||
type_name_t * lv_function_name(lv_obj_t * parent);
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: c
|
||||
@ -286,7 +287,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 space:
|
||||
Here is example to show bracket placement and use of white space:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
=====
|
||||
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.
|
||||
|
||||
@ -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.
|
||||
* 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:
|
||||
|
||||
- `.. code-block:: c`,
|
||||
- `.. code-block:: cpp`,
|
||||
- `.. code-block:: python`,
|
||||
|
||||
@ -30,15 +30,15 @@ Usage
|
||||
Image sources
|
||||
-------------
|
||||
|
||||
To set the image in a state, use the
|
||||
:cpp:expr:`lv_animimg_set_src(imagebutton, dsc[], num)`.
|
||||
To set the image animation images sources, use
|
||||
:cpp:expr:`lv_animimg_set_src(animimg, dsc[], num)`.
|
||||
|
||||
Using the inner animation
|
||||
-------------------------
|
||||
|
||||
For more advanced use cases, the animation internally used by the image can be
|
||||
retrieved using the :cpp:expr:`lv_animimg_get_anim(image)`. This way, the
|
||||
:ref:`Animation <animation>` functions can be used, for example to
|
||||
For more advanced use cases, the animation used internally by the image can be
|
||||
retrieved using :cpp:expr:`lv_animimg_get_anim(animimg)`. Using this, you can
|
||||
use the :ref:`Animation <animation>` functions, for example, to
|
||||
override the animation values using the
|
||||
:cpp:expr:`lv_anim_set_values(anim, start, end)` or to set a callback
|
||||
on the animation completed event.
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
Arc (lv_arc)
|
||||
============
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
@ -26,6 +27,7 @@ Parts and Styles
|
||||
size is the same as the indicator's width. Larger padding makes it
|
||||
larger, smaller padding makes it smaller.
|
||||
|
||||
|
||||
.. _lv_arc_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
|
||||
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
|
||||
:cpp:expr:`lv_arc_set_bg_angles(arc, start_angle, end_angle)` functions or
|
||||
``lv_arc_set_bg_start/end_angle(arc, angle)``.
|
||||
To set the start and end angle of the background arc use any of these functions:
|
||||
|
||||
- :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
|
||||
degrees are increasing in clockwise direction. The angles should be in
|
||||
the [0;360] range.
|
||||
degrees increasing in the clockwise direction. The angle values should be in
|
||||
the range [0..360].
|
||||
|
||||
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)`.
|
||||
|
||||
Mode
|
||||
@ -60,45 +64,48 @@ Mode
|
||||
|
||||
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_REVERSE` The indicator arc is drawn counter-clockwise
|
||||
from the maximum value to the current.
|
||||
- :cpp:enumerator:`LV_ARC_MODE_SYMMETRICAL` The indicator arc is drawn from the middle point to the current value.
|
||||
- :cpp:enumerator:`LV_ARC_MODE_NORMAL` Indicator arc is drawn clockwise from minimum to current value.
|
||||
- :cpp:enumerator:`LV_ARC_MODE_REVERSE` Indicator arc is drawn counter-clockwise
|
||||
from maximum to 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
|
||||
used only if the angle is set by :cpp:func:`lv_arc_set_value` or the arc is
|
||||
adjusted by finger.
|
||||
has no effect until angle is set by :cpp:func:`lv_arc_set_value` or value of the arc
|
||||
is changed by pointer input (finger, mouse, etc.).
|
||||
|
||||
Change rate
|
||||
-----------
|
||||
|
||||
If the arc is pressed the current value will set with a limited speed
|
||||
according to the set *change rate*. The change rate is defined in
|
||||
degree/second unit and can be set with
|
||||
:cpp:expr:`lv_arc_set_change_rage(arc, rate)`
|
||||
When the arc's value is changed by pointer input (finger, mouse, etc.), the rate of
|
||||
its change is limited according to its *change rate*. Change rate is defined in
|
||||
degrees/second units and can be set with
|
||||
:cpp:expr:`lv_arc_set_change_rate(arc, rate)`
|
||||
|
||||
Knob offset
|
||||
-----------
|
||||
|
||||
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
|
||||
:cpp:expr:`lv_arc_set_knob_offset(arc, offset_angle)`, will only be visible if
|
||||
:cpp:enumerator:`LV_PART_KNOB` is visible
|
||||
relative to the end of the arc. The knob offset can be set by
|
||||
:cpp:expr:`lv_arc_set_knob_offset(arc, offset_angle)`, and will only be visible if
|
||||
: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
|
||||
: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.
|
||||
It is possible to set indicator angle directly with any of these functions:
|
||||
|
||||
In other words, the angle and value settings are independent. You should
|
||||
exclusively use one or the other. Mixing the two might result in
|
||||
unintended behavior.
|
||||
- :cpp:expr:`lv_arc_set_start_angle(arc, start_angle)`
|
||||
- :cpp:expr:`lv_arc_set_end_angle(arc, end_angle)`
|
||||
- :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
|
||||
the Widget non-clickable:
|
||||
When used, "value" and "mode" are ignored.
|
||||
|
||||
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
|
||||
|
||||
@ -110,51 +117,53 @@ Interactive area
|
||||
|
||||
By default :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is disabled which
|
||||
means the arc's whole area is interactive.
|
||||
As usual :cpp:func:`lv_obj_set_ext_click_size` can be used to increase
|
||||
the sensitive area outside the arc by a specified number of pixels.
|
||||
As usual :cpp:func:`lv_obj_set_ext_click_area` can be used to increase
|
||||
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
|
||||
in the range of 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 the range between start and end background angles and on the arc itself (not inside the arc).
|
||||
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
|
||||
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
|
||||
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
|
||||
: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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _lv_arc_events:
|
||||
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when the arc is pressed/dragged to
|
||||
set a new value.
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when arc is pressed/dragged to
|
||||
a new value.
|
||||
- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent
|
||||
with the following types:
|
||||
|
||||
- :cpp:enumerator:`LV_ARC_DRAW_PART_BACKGROUND` The background arc.
|
||||
|
||||
- ``part``: :cpp:enumerator:`LV_PART_MAIN`
|
||||
- ``p1``: center of the arc
|
||||
- ``radius``: radius of the arc
|
||||
- ``p1``: center of arc
|
||||
- ``radius``: radius of arc
|
||||
- ``arc_dsc``
|
||||
|
||||
- :cpp:enumerator:`LV_ARC_DRAW_PART_FOREGROUND` The foreground arc.
|
||||
|
||||
- ``part``: :cpp:enumerator:`LV_PART_INDICATOR`
|
||||
- ``p1``: center of the arc
|
||||
- ``radius``: radius of the arc
|
||||
- ``p1``: center of arc
|
||||
- ``radius``: radius of arc
|
||||
- ``arc_dsc``
|
||||
|
||||
- LV_ARC_DRAW_PART_KNOB The knob
|
||||
@ -177,8 +186,8 @@ Events
|
||||
Keys
|
||||
****
|
||||
|
||||
- ``LV_KEY_RIGHT/UP`` Increases the value by one.
|
||||
- ``LV_KEY_LEFT/DOWN`` Decreases the value by one.
|
||||
- ``LV_KEY_RIGHT/UP`` Increases value by one.
|
||||
- ``LV_KEY_LEFT/DOWN`` Decreases value by one.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -7,25 +7,25 @@ Bar (lv_bar)
|
||||
Overview
|
||||
********
|
||||
|
||||
The bar Widget has a background and an indicator on it. The width of the
|
||||
indicator is set according to the current value of the bar.
|
||||
The bar Widget has a background and an indicator. The length of the
|
||||
indicator against the background indicates the bar's current value.
|
||||
|
||||
Vertical bars can be created if the width of the Widget is smaller than
|
||||
its height.
|
||||
|
||||
Not only the end, but also the start value of the bar can be set, which
|
||||
changes the start position of the indicator.
|
||||
Both the start and end values of the bar can be set. Changing the start value to a
|
||||
value other than the minimum value in its range changes the start position of the indicator.
|
||||
|
||||
.. _lv_bar_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
|
||||
smaller or larger. The ``anim_time`` style property sets the
|
||||
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.
|
||||
|
||||
.. _lv_bar_usage:
|
||||
@ -36,13 +36,13 @@ Usage
|
||||
Value and range
|
||||
---------------
|
||||
|
||||
A new value can be set by
|
||||
``lv_bar_set_value(bar, new_value, LV_ANIM_ON/OFF)``. The value is
|
||||
A new value can be set with
|
||||
: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
|
||||
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
|
||||
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
|
||||
animation depending on the last parameter (``LV_ANIM_ON/OFF``).
|
||||
@ -53,11 +53,11 @@ 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_SYMMETRICAL` Draw the indicator from the zero value to current value. Requires a negative
|
||||
minimum range and positive maximum range.
|
||||
- :cpp:enumerator:`LV_BAR_MODE_RANGE` Allows setting the start value as well by
|
||||
``lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)``. The start
|
||||
value always has to be smaller than the end value.
|
||||
- :cpp:enumerator:`LV_BAR_MODE_SYMMETRICAL` Draws indicator from zero value to current value. Requires a negative
|
||||
minimum value and positive maximum value, e.g. [-100..100].
|
||||
- :cpp:enumerator:`LV_BAR_MODE_RANGE` Allows setting the start value as well with
|
||||
:cpp:expr:`lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start
|
||||
value must be smaller than the end value.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -10,16 +10,18 @@ Overview
|
||||
Buttons have no new features compared to the :ref:`base_widget`.
|
||||
They are useful for semantic purposes and have slightly different default settings.
|
||||
|
||||
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`
|
||||
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`
|
||||
|
||||
.. _lv_button_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.
|
||||
|
||||
.. _lv_button_usage:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user