mirror of
https://github.com/lvgl/lvgl.git
synced 2024-11-23 01:33:59 +08:00
feat(docs): batch 7 of proofread/edited docs (#7281)
This commit is contained in:
Victor Wheeler
GitHub
parent
7232ad74a0
commit
67051b026a
@ -448,7 +448,7 @@ redirects = {
|
||||
"widgets/roller": "../details/widgets/roller.html" ,
|
||||
"widgets/scale": "../details/widgets/scale.html" ,
|
||||
"widgets/slider": "../details/widgets/slider.html" ,
|
||||
"widgets/span": "../details/widgets/span.html" ,
|
||||
"widgets/span": "../details/widgets/spangroup.html" ,
|
||||
"widgets/spinbox": "../details/widgets/spinbox.html" ,
|
||||
"widgets/spinner": "../details/widgets/spinner.html" ,
|
||||
"widgets/switch": "../details/widgets/switch.html" ,
|
||||
@ -457,6 +457,7 @@ redirects = {
|
||||
"widgets/textarea": "../details/widgets/textarea.html" ,
|
||||
"widgets/tileview": "../details/widgets/tileview.html" ,
|
||||
"widgets/win": "../details/widgets/win.html" ,
|
||||
"details/widgets/span": "../../details/widgets/spangroup.html" ,
|
||||
}
|
||||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
|
||||
@ -176,7 +176,7 @@ The following predefined parts exist in LVGL:
|
||||
- :cpp:enumerator:`LV_PART_KNOB`: Like a handle to grab to adjust a value
|
||||
- :cpp:enumerator:`LV_PART_SELECTED`: Indicate the currently selected option or section
|
||||
- :cpp:enumerator:`LV_PART_ITEMS`: Used if the widget has multiple similar elements (e.g. table cells)
|
||||
- :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. text area's or chart's cursor
|
||||
- :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. Text Area's or chart's cursor
|
||||
- :cpp:enumerator:`LV_PART_CUSTOM_FIRST`: Custom part identifiers can be added starting from here.
|
||||
|
||||
For example a :ref:`Slider <lv_slider>` has three parts:
|
||||
@ -398,11 +398,13 @@ Style Properties Overview
|
||||
For the full list of style properties click :ref:`here <style_properties>`.
|
||||
|
||||
|
||||
.. _typical bg props:
|
||||
|
||||
Typical background properties
|
||||
-----------------------------
|
||||
|
||||
In documentation of widgets you will see sentences like "The
|
||||
widget uses the typical background properties". These "typical
|
||||
_____ Widget uses the typical background style properties". These "typical
|
||||
background properties" are the properties being referred to:
|
||||
|
||||
- Background
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
Bar (lv_bar)
|
||||
============
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
@ -16,6 +17,8 @@ its height.
|
||||
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
|
||||
@ -33,6 +36,19 @@ Parts and Styles
|
||||
Usage
|
||||
*****
|
||||
|
||||
|
||||
Orientation and size
|
||||
--------------------
|
||||
|
||||
- for orientation, width and height, simply set width and height style properties;
|
||||
- :cpp:expr:`lv_bar_set_orientation(slider, orientation)` to override orientation
|
||||
caused by ``width`` and ``height``. Valid values for ``orientation`` are:
|
||||
|
||||
- LV_BAR_ORIENTATION_AUTO,
|
||||
- LV_BAR_ORIENTATION_HORIZONTAL,
|
||||
- LV_BAR_ORIENTATION_VERTICAL.
|
||||
|
||||
|
||||
Value and range
|
||||
---------------
|
||||
|
||||
@ -47,6 +63,7 @@ bottom to top in vertical mode. If the minimum value is greater than the maximum
|
||||
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``).
|
||||
|
||||
|
||||
Modes
|
||||
-----
|
||||
|
||||
|
||||
@ -4,71 +4,94 @@
|
||||
Slider (lv_slider)
|
||||
==================
|
||||
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Slider Widget looks like a :ref:`Bar <lv_bar>` supplemented with
|
||||
a knob. The knob can be dragged to set a value. Just like Bar, Slider
|
||||
The Slider Widget looks like a :ref:`lv_bar` supplemented with
|
||||
a knob. The knob can be dragged to set the Slider's value. Like Bar, a Slider
|
||||
can be vertical or horizontal.
|
||||
|
||||
|
||||
|
||||
.. _lv_slider_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the slider. Uses all the typical
|
||||
background style properties. ``padding`` makes the indicator smaller
|
||||
in the respective direction.
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the Slider. Uses the
|
||||
:ref:`typical background style properties <typical bg props>`. ``padding`` makes
|
||||
the indicator smaller in the respective direction.
|
||||
- :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of
|
||||
the slider. Also uses all the typical background style properties.
|
||||
- :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the current value.
|
||||
Also uses all the typical background properties to describe the
|
||||
knob(s). By default, the knob is square (with an optional corner
|
||||
radius) with side length equal to the smaller side of the slider. The
|
||||
knob can be made larger with the ``padding`` values. Padding values
|
||||
can be asymmetric as well.
|
||||
the Slider; also uses the :ref:`typical background style properties <typical bg props>`.
|
||||
- :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the current value;
|
||||
also uses the :ref:`typical background style properties <typical bg props>` to
|
||||
describe the knob(s). By default, the knob is round (radius-style can modify this)
|
||||
with side length equal to the smaller dimension of the Slider. The knob can be
|
||||
made larger with the ``padding`` values. Padding values can be asymmetric as well.
|
||||
|
||||
|
||||
|
||||
.. _lv_slider_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
Value and range
|
||||
---------------
|
||||
Value, range and orientation
|
||||
----------------------------
|
||||
|
||||
To set an initial value use :cpp:expr:`lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)`. The
|
||||
animation time is set by the styles' ``anim_time`` property.
|
||||
Once a Slider is created, it has:
|
||||
|
||||
To specify the range (min, max values), :cpp:expr:`lv_slider_set_range(slider, min , max)` can be used.
|
||||
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.
|
||||
- value == 0
|
||||
- default range of [0..100],
|
||||
- horizontal orientation, with
|
||||
- default width of approximately 2 inches (according to configured value of :c:macro:`LV_DPI_DEF`),
|
||||
- default hight of approximately 1/10 inch (according to configured value of :c:macro:`LV_DPI_DEF`).
|
||||
|
||||
To set a different value use:
|
||||
|
||||
- :cpp:expr:`lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)` (animation time
|
||||
is set by the styles' ``anim_time`` property);
|
||||
- :cpp:expr:`lv_slider_set_range(slider, min , max)`; and
|
||||
- for orientation, width and height, simply set width and height style properties;
|
||||
- :cpp:expr:`lv_bar_set_orientation(slider, orientation)` to override orientation
|
||||
caused by ``width`` and ``height``. Valid values for ``orientation`` are:
|
||||
|
||||
- LV_BAR_ORIENTATION_AUTO,
|
||||
- LV_BAR_ORIENTATION_HORIZONTAL,
|
||||
- LV_BAR_ORIENTATION_VERTICAL.
|
||||
|
||||
The default drawing direction is from left to right in horizontal orientation and
|
||||
bottom to top in vertical orientation. If the minimum value is set to be greater
|
||||
than the maximum value (e.g. [100..0]), the drawing direction is reversed.
|
||||
|
||||
Modes
|
||||
-----
|
||||
|
||||
The slider can be one of the following modes:
|
||||
The Slider can be in one of the following modes:
|
||||
|
||||
- :cpp:enumerator:`LV_SLIDER_MODE_NORMAL` A normal slider as described above
|
||||
- :cpp:enumerator:`LV_SLIDER_SYMMETRICAL` Draw the indicator form the zero value to
|
||||
- :cpp:enumerator:`LV_SLIDER_MODE_NORMAL` A normal Slider as described above (default)
|
||||
- :cpp:enumerator:`LV_SLIDER_SYMMETRICAL` Draw the indicator from the zero value to
|
||||
current value. Requires negative minimum range and positive maximum range.
|
||||
- :cpp:enumerator:`LV_SLIDER_RANGE` Allows setting the start value as well by
|
||||
:cpp:expr:`lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start
|
||||
value has to be always smaller than the end value.
|
||||
:cpp:expr:`lv_bar_set_start_value(slider, new_value, LV_ANIM_ON/OFF)`. The start
|
||||
value must always be smaller than the end value.
|
||||
|
||||
The mode can be changed with :cpp:expr:`lv_slider_set_mode(slider, LV_SLIDER_MODE_...)`
|
||||
|
||||
Knob-only mode
|
||||
--------------
|
||||
|
||||
Normally, the slider can be adjusted either by dragging the knob, or by
|
||||
clicking on the slider bar. In the latter case the knob moves to the
|
||||
point clicked and slider value changes accordingly. In some cases it is
|
||||
desirable to set the slider to react on dragging the knob only. This
|
||||
feature is enabled by adding the :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST`:
|
||||
Normally, the Slider can be adjusted either by dragging the knob, or by
|
||||
clicking on the Slider bar. In the latter case the knob moves to the
|
||||
point clicked and the Slider value changes accordingly. In some cases it is
|
||||
desirable to set the Slider to react on dragging the knob only. This
|
||||
feature is enabled by adding the :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` flag:
|
||||
:cpp:expr:`lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST)`.
|
||||
|
||||
The extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, value)`) increases to knob's click area.
|
||||
Any extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, value)`)
|
||||
increases the knob's click area.
|
||||
|
||||
|
||||
|
||||
@ -77,10 +100,10 @@ The extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, val
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent while the slider is being dragged or
|
||||
changed with keys. The event is sent continuously while the slider is
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent while the Slider is being dragged or
|
||||
changed with keys. The event is sent continuously while the Slider is
|
||||
being dragged.
|
||||
- :cpp:enumerator:`LV_EVENT_RELEASED` Sent when the slider has just been released.
|
||||
- :cpp:enumerator:`LV_EVENT_RELEASED` Sent once when Slider is released.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
@ -97,8 +120,8 @@ Events
|
||||
Keys
|
||||
****
|
||||
|
||||
- ``LV_KEY_UP/RIGHT`` Increment the slider's value by 1
|
||||
- ``LV_KEY_DOWN/LEFT`` Decrement the slider's value by 1
|
||||
- ``LV_KEY_UP/RIGHT`` Increment Slider's value by 1.
|
||||
- ``LV_KEY_DOWN/LEFT`` Decrement Slider's value by 1.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -1,155 +0,0 @@
|
||||
.. _lv_span:
|
||||
|
||||
==============
|
||||
Span (lv_span)
|
||||
==============
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
A spangroup is the Widget that is used to display rich text. Different
|
||||
from the label Widget, ``spangroup`` can render text styled with
|
||||
different fonts, colors, and sizes into the spangroup Widget.
|
||||
|
||||
.. _lv_span_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The spangroup has only one part.
|
||||
|
||||
.. _lv_span_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
Set text and style
|
||||
------------------
|
||||
|
||||
The spangroup Widget uses span to describe text and text style. so,
|
||||
first we need to create ``span`` descriptor using ``lv_span_t * span = lv_spangroup_new_span(spangroup)``.
|
||||
Then use :cpp:expr:`lv_span_set_text(span, "text")` to set text. The style of the span is
|
||||
configured as with a normal style Widget by using its ``style`` member,
|
||||
eg::cpp:expr:`lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))`.
|
||||
|
||||
If spangroup Widget ``mode != LV_SPAN_MODE_FIXED`` you must call
|
||||
:cpp:func:`lv_spangroup_refr_mode` after you have modified ``span``
|
||||
style(eg:set text, changed the font size, del span).
|
||||
|
||||
Retrieving a span child
|
||||
-----------------------
|
||||
|
||||
Spangroups store their children differently from normal Widgets, so
|
||||
normal functions for getting children won't work.
|
||||
|
||||
:cpp:expr:`lv_spangroup_get_child(spangroup, id)` will return a pointer to the
|
||||
child span at index ``id``. In addition, ``id`` can be negative to index
|
||||
from the end of the spangroup where ``-1`` is the youngest child, ``-2``
|
||||
is second youngest, etc.
|
||||
|
||||
E.g. ``lv_span_t* span = lv_spangroup_get_child(spangroup, 0)`` will
|
||||
return the first child of the spangroup.
|
||||
``lv_span_t* span = lv_spangroup_get_child(spangroup, -1)`` will return
|
||||
the last (or most recent) child.
|
||||
|
||||
Child Count
|
||||
-----------
|
||||
|
||||
Use the function :cpp:expr:`lv_spangroup_get_span_count(spangroup)` to get back
|
||||
the number of spans the group is maintaining.
|
||||
|
||||
E.g. ``uint32_t size = lv_spangroup_get_span_count(spangroup)``
|
||||
|
||||
Text align
|
||||
----------
|
||||
|
||||
Like label Widget, the spangroup can be set to one the following modes:
|
||||
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align to left.
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Align to center.
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align to right.
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align auto.
|
||||
|
||||
Use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER)`
|
||||
to set text align.
|
||||
|
||||
Modes
|
||||
-----
|
||||
|
||||
The spangroup can be set to one the following modes:
|
||||
|
||||
- :cpp:enumerator:`LV_SPAN_MODE_FIXED` Fixes the Widget size.
|
||||
- :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand the Widget size to the text size but stay on a single line.
|
||||
- :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width, break lines that are too long and auto expand height.
|
||||
|
||||
Use the function :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set
|
||||
Widget mode.
|
||||
|
||||
Overflow
|
||||
--------
|
||||
|
||||
The spangroup can be set to one the following modes:
|
||||
|
||||
- :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates the text at the limit of the area.
|
||||
- :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` will display an ellipsis (``...``) when text overflows the area.
|
||||
|
||||
Use function :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set Widget overflow mode.
|
||||
|
||||
First line indent
|
||||
-----------------
|
||||
|
||||
Use function :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the
|
||||
first line. all modes support pixel units, in addition to :cpp:enumerator:`LV_SPAN_MODE_FIXED`
|
||||
and :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode supports percentage units
|
||||
as well.
|
||||
|
||||
Lines
|
||||
-----
|
||||
|
||||
Use function :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum number
|
||||
of lines to be displayed in :cpp:enumerator::`LV_SPAN_MODE_BREAK` mode, negative values
|
||||
indicate no limit.
|
||||
|
||||
|
||||
|
||||
.. _lv_span_events:
|
||||
|
||||
Events
|
||||
******
|
||||
|
||||
No special events are sent by this widget.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
|
||||
|
||||
Learn more about :ref:`events`.
|
||||
|
||||
|
||||
|
||||
.. _lv_span_keys:
|
||||
|
||||
Keys
|
||||
****
|
||||
|
||||
No *Keys* are processed by Span Widgets.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
Learn more about :ref:`indev_keys`.
|
||||
|
||||
|
||||
|
||||
.. _lv_span_example:
|
||||
|
||||
Example
|
||||
*******
|
||||
|
||||
.. include:: ../../examples/widgets/span/index.rst
|
||||
|
||||
|
||||
|
||||
.. _lv_span_api:
|
||||
|
||||
API
|
||||
***
|
||||
190
docs/details/widgets/spangroup.rst
Normal file
190
docs/details/widgets/spangroup.rst
Normal file
@ -0,0 +1,190 @@
|
||||
.. _lv_spangroup:
|
||||
|
||||
========================
|
||||
Spangroup (lv_spangroup)
|
||||
========================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Spangroup Widget is used to display rich text. Different
|
||||
from the Label Widget, Spangroups can render text styled with
|
||||
different fonts, colors, and sizes into the Spangroup Widget.
|
||||
See example below.
|
||||
|
||||
A Spangroup contains 0 or more Span Descriptors ("Spans"). Each Span contains its
|
||||
own text and style properties for that text. You add 1 Span (as a child) to the
|
||||
Spangroup for each "span" of uniquely-styled text needed. Each Span so added is
|
||||
appended to the end of the list. The list sequence determines the order in which the
|
||||
Spans are displayed. Spans can be added to, and removed from, the Spangroup
|
||||
throughout its life. The number of Spans that can be added is limited only by
|
||||
available RAM.
|
||||
|
||||
|
||||
|
||||
.. _lv_spangroup_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` Spangroup has only one part.
|
||||
|
||||
|
||||
|
||||
.. _lv_spangroup_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
Set text and style
|
||||
------------------
|
||||
|
||||
Add each needed Span to a Spangroup like this:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_span_t * span = lv_spangroup_new_span(spangroup);
|
||||
|
||||
After a Span is created, use the following functions to set its text
|
||||
and style properties:
|
||||
|
||||
- :cpp:expr:`lv_span_set_text(span, "text")`
|
||||
- :cpp:expr:`lv_style_set_<property_name>(&span->style, value)`
|
||||
|
||||
Example of the latter: :cpp:expr:`lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))`.
|
||||
|
||||
If the Spangroup Widget's ``mode != LV_SPAN_MODE_FIXED`` call
|
||||
:cpp:expr:`lv_spangroup_refr_mode(spangroup)` after you have modifying any of its
|
||||
Spans to ensure it is redrawn appropriately.
|
||||
|
||||
|
||||
Retrieving a Span child
|
||||
-----------------------
|
||||
|
||||
Spangroups store their children differently from normal Widgets, so
|
||||
normal functions for getting children won't work.
|
||||
|
||||
:cpp:expr:`lv_spangroup_get_child(spangroup, id)` will return a pointer to the
|
||||
child Span at index ``id``. In addition, ``id`` can be negative to index
|
||||
from the end of the Spangroup where ``-1`` is the youngest child, ``-2``
|
||||
is second youngest, etc.
|
||||
|
||||
E.g. ``lv_span_t * span = lv_spangroup_get_child(spangroup, 0)`` will
|
||||
return the first child of the Spangroup.
|
||||
``lv_span_t * span = lv_spangroup_get_child(spangroup, -1)`` will return
|
||||
the last (or most recent) child.
|
||||
|
||||
|
||||
Child count
|
||||
-----------
|
||||
|
||||
Use :cpp:expr:`lv_spangroup_get_span_count(spangroup)` to get
|
||||
the number of contained Spans.
|
||||
|
||||
E.g. ``uint32_t size = lv_spangroup_get_span_count(spangroup)``
|
||||
|
||||
|
||||
Removing a Span
|
||||
---------------
|
||||
You can remove a Span at any time during the Spangroup's life using the function
|
||||
:cpp:expr:`lv_spangroup_delete_span(spangroup, span)`.
|
||||
|
||||
|
||||
Text align
|
||||
----------
|
||||
|
||||
Like the Label Widget, a Spangroup can be set to one the following text-alignment modes:
|
||||
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align text to left.
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Center text.
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align text to right edge.
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align auto.
|
||||
|
||||
Use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_...)`
|
||||
to set text alignment.
|
||||
|
||||
|
||||
Modes
|
||||
-----
|
||||
|
||||
A Spangroup can be set to one the following modes:
|
||||
|
||||
- :cpp:enumerator:`LV_SPAN_MODE_FIXED` Fixes its size.
|
||||
- :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand size to text size but stay on one line.
|
||||
- :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width; break lines that are too long and auto-expand height.
|
||||
|
||||
Use :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set its mode.
|
||||
|
||||
|
||||
Overflow
|
||||
--------
|
||||
|
||||
A Spangroup can be set to handle text overflow in one of the following ways:
|
||||
|
||||
- :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates text at the limit of the area.
|
||||
- :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` display an ellipsis (``...``) when text overflows the area.
|
||||
|
||||
Use :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set
|
||||
the Spangroup's overflow mode.
|
||||
|
||||
|
||||
First line indent
|
||||
-----------------
|
||||
|
||||
Use :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the
|
||||
first line. All modes support pixel units. In addition, :cpp:enumerator:`LV_SPAN_MODE_FIXED`
|
||||
and :cpp:enumerator:`LV_SPAN_MODE_BREAK` modes support :ref:`percentage units <coord_units>`.
|
||||
as well.
|
||||
|
||||
|
||||
Lines
|
||||
-----
|
||||
|
||||
Use :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum number
|
||||
of lines to be displayed in :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode. A negative
|
||||
value indicates no limit.
|
||||
|
||||
|
||||
|
||||
.. _lv_spangroup_events:
|
||||
|
||||
Events
|
||||
******
|
||||
|
||||
No special events are sent by Span Widgets.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
|
||||
|
||||
Learn more about :ref:`events`.
|
||||
|
||||
|
||||
|
||||
.. _lv_spangroup_keys:
|
||||
|
||||
Keys
|
||||
****
|
||||
|
||||
No *Keys* are processed by Span Widgets.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
Learn more about :ref:`indev_keys`.
|
||||
|
||||
|
||||
|
||||
.. _lv_spangroup_example:
|
||||
|
||||
Example
|
||||
*******
|
||||
|
||||
.. include:: ../../examples/widgets/span/index.rst
|
||||
|
||||
|
||||
|
||||
.. _lv_spangroup_api:
|
||||
|
||||
API
|
||||
***
|
||||
@ -4,33 +4,40 @@
|
||||
Spinbox (lv_spinbox)
|
||||
====================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Spinbox contains a number as text which can be increased or
|
||||
decreased by *Keys* or API functions. Under the hood the Spinbox is a
|
||||
modified :ref:`Text area <lv_textarea>`.
|
||||
Spinbox contains an integer displayed as a decimal number with a possible fixed
|
||||
decimal point position and a configurable number of digits. The value can be
|
||||
increased or decreased by *Keys* or API functions. Under the hood Spinbox is a
|
||||
:ref:`lv_textarea` with behaviors extended to enable a numeric value
|
||||
to be viewed and modified with configurable constraints.
|
||||
|
||||
|
||||
|
||||
.. _lv_spinbox_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
The parts of the Spinbox are identical to the :ref:`Text area <lv_textarea>`.
|
||||
Spinbox's parts are identical to those of :ref:`Text Area <lv_textarea_parts_and_styles>`.
|
||||
|
||||
Value, range and step
|
||||
---------------------
|
||||
|
||||
- :cpp:expr:`lv_spinbox_set_value(spinbox, 1234)` sets a new value on the Spinbox.
|
||||
- :cpp:expr:`lv_spinbox_set_value(spinbox, 1234)` sets a new value for the Spinbox.
|
||||
- :cpp:expr:`lv_spinbox_increment(spinbox)` and :cpp:expr:`lv_spinbox_decrement(spinbox)`
|
||||
increments/decrements the value of the Spinbox according to the currently selected digit.
|
||||
- :cpp:expr:`lv_spinbox_set_range(spinbox, -1000, 2500)` sets a range. If the
|
||||
value is changed by :cpp:func:`lv_spinbox_set_value`, by
|
||||
*Keys*,\ ``lv_spinbox_increment/decrement`` this range will be respected.
|
||||
- :cpp:expr:`lv_spinbox_set_step(spinbox, 100)` sets which digits to change on
|
||||
increment/decrement. Only multiples of ten can be set, and not for example 3.
|
||||
increments/decrements the value of the Spinbox according to the currently-selected digit.
|
||||
- :cpp:expr:`lv_spinbox_set_range(spinbox, -1000, 2500)` sets its range. If the
|
||||
value is changed by :cpp:expr:`lv_spinbox_set_value(spinbox)`, by *Keys*,
|
||||
by :cpp:expr:`lv_spinbox_increment(spinbox)` or :cpp:expr:`lv_spinbox_decrement(spinbox)`
|
||||
this range will be respected.
|
||||
- :cpp:expr:`lv_spinbox_set_step(spinbox, 100)` sets which digit to change on
|
||||
increment/decrement. Only multiples of ten can be set.
|
||||
- :cpp:expr:`lv_spinbox_set_cursor_pos(spinbox, 1)` sets the cursor to a specific
|
||||
digit to change on increment/decrement. For example position '0' sets the cursor to the least significant digit.
|
||||
digit to change on increment/decrement. Position '0' sets the cursor to
|
||||
the least significant digit.
|
||||
|
||||
If an encoder is used as input device, the selected digit is shifted to
|
||||
the right by default whenever the encoder button is clicked. To change this behaviour to shifting
|
||||
@ -40,17 +47,18 @@ Format
|
||||
------
|
||||
|
||||
:cpp:expr:`lv_spinbox_set_digit_format(spinbox, digit_count, separator_position)`
|
||||
sets the number format. ``digit_count`` is the number of digits
|
||||
excluding the decimal separator and the sign. ``separator_position`` is
|
||||
the number of digits before the decimal point. If 0, no decimal point is displayed.
|
||||
sets the number format. ``digit_count`` is the total number of digits to display.
|
||||
``separator_position`` is the number of leading digits before the decimal point.
|
||||
Pass 0 for ``separator_position`` to display no decimal point.
|
||||
|
||||
Rollover
|
||||
--------
|
||||
|
||||
:cpp:expr:`lv_spinbox_set_rollover(spinbox, true/false)` enables/disabled
|
||||
rollover mode. If either the minimum or maximum value is reached with
|
||||
rollover enabled, the value will change to the other limit. If rollover
|
||||
is disabled the value will remain at the minimum or maximum value.
|
||||
rollover enabled, and the user attempts to continue changing the value in
|
||||
the same direction, the value will change to the other limit. If rollover
|
||||
is disabled the value will stop at the minimum or maximum value.
|
||||
|
||||
|
||||
|
||||
@ -59,7 +67,7 @@ is disabled the value will remain at the minimum or maximum value.
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the value has changed.
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when value has changed.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
@ -80,8 +88,8 @@ Keys
|
||||
*Encoder* decrement/increment the selected digit.
|
||||
- ``LV_KEY_UP/DOWN`` With *Keypad* and *Encoder* increment/decrement
|
||||
the value.
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` With *Encoder* got the net digit. Jump to the first
|
||||
after the last.
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` With *Encoder*, move focus to next digit. If focus
|
||||
is on last digit, focus moves to first digit.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -4,17 +4,23 @@
|
||||
Spinner (lv_spinner)
|
||||
====================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Spinner Widget is a spinning arc over a ring.
|
||||
The Spinner Widget is a spinning arc over a ring, typically used to show some type of
|
||||
activity is in progress.
|
||||
|
||||
|
||||
|
||||
.. _lv_spinner_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
The parts are identical to the parts of :ref:`lv_arc`.
|
||||
Spinner's parts are identical to those of :ref:`Arc <lv_arc_parts_and_styles>`.
|
||||
|
||||
|
||||
|
||||
.. _lv_spinner_usage:
|
||||
|
||||
@ -27,8 +33,8 @@ Create a spinner
|
||||
To create a spinner use
|
||||
:cpp:expr:`lv_spinner_create(parent)`.
|
||||
|
||||
Using :cpp:expr:`lv_spinner_set_anim_params(spinner, spin_duration, angle)` the duration
|
||||
of one revolution and the length of he arc can be customized.
|
||||
Use :cpp:expr:`lv_spinner_set_anim_params(spinner, spin_duration, angle)` to
|
||||
customize the duration of one revolution and the length of the arc.
|
||||
|
||||
|
||||
|
||||
@ -37,7 +43,7 @@ of one revolution and the length of he arc can be customized.
|
||||
Events
|
||||
******
|
||||
|
||||
No special events are sent to Spinner Widgets.
|
||||
No special events are sent by Spinner Widgets.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -4,31 +4,37 @@
|
||||
Switch (lv_switch)
|
||||
==================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Switch looks like a little slider and can be used to turn something
|
||||
on and off.
|
||||
Switch Widgets look like little sliders and are used to display, and optionally
|
||||
modify, a value that can be "on" or "off".
|
||||
|
||||
By default, a Switch is oriented horizontally. It's orientation will be vertical
|
||||
if you set ``width`` < ``height``.
|
||||
|
||||
|
||||
Vertical Switch can be created if the width of the Widget is smaller than its height.
|
||||
|
||||
.. _lv_switch_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the switch uses all the typical
|
||||
background style properties. ``padding`` makes the indicator smaller
|
||||
- :cpp:enumerator:`LV_PART_MAIN` Switch's background; uses the :ref:`typical
|
||||
background style properties <typical bg props>`. ``padding`` makes the indicator smaller
|
||||
in the respective direction.
|
||||
- :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of
|
||||
the switch. Also uses all the typical background style properties.
|
||||
- :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at left or right side
|
||||
of the indicator. Also uses all the typical background properties to
|
||||
describe the knob(s). By default, the knob is square (with an
|
||||
optional corner radius) with side length equal to the smaller side of
|
||||
the slider. The knob can be made larger with the ``padding`` values.
|
||||
the Switch; also uses the :ref:`typical background style properties <typical bg props>`.
|
||||
- :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the left or right
|
||||
side of the indicator; also uses the :ref:`typical background style properties
|
||||
<typical bg props>` to modify the knob's appearance. By default, the knob is round
|
||||
(radius-style can modify this) with diameter slightly smaller than the smaller
|
||||
side of the slider. The knob can be made larger with the ``padding`` values.
|
||||
Padding values can be asymmetric as well.
|
||||
|
||||
|
||||
|
||||
.. _lv_switch_usage:
|
||||
|
||||
Usage
|
||||
@ -37,18 +43,27 @@ Usage
|
||||
Change state
|
||||
------------
|
||||
|
||||
The switch uses the standard :cpp:enumerator:`LV_STATE_CHECKED` state.
|
||||
The Switch uses the standard :cpp:enumerator:`LV_STATE_CHECKED` state.
|
||||
|
||||
To get the current state of the switch (with ``true`` being on), use
|
||||
To get the current state of the Switch (with ``true`` being on), use
|
||||
:cpp:expr:`lv_obj_has_state(widget, LV_STATE_CHECKED)`.
|
||||
|
||||
Call :cpp:expr:`lv_obj_add_state(widget, LV_STATE_CHECKED)` to turn it on, or
|
||||
:cpp:expr:`lv_obj_remove_state(widget, LV_STATE_CHECKED)` to turn it off.
|
||||
:cpp:expr:`lv_obj_remove_state(widget, LV_STATE_CHECKED)` to turn it off
|
||||
programmatically.
|
||||
|
||||
Change orientation
|
||||
------------------
|
||||
|
||||
:cpp:expr:`lv_switch_set_orientation(widget, LV_SWITCH_ORIENTATION_VERTICAL)` change orientation, default orientation is :cpp:enumerator:`LV_SWITCH_ORIENTATION_AUTO`, adaptive based on the width and height of the Widget.
|
||||
Swith a Switch is created, its default orientation is
|
||||
:cpp:enumerator:`LV_SWITCH_ORIENTATION_AUTO`, which causes it to be oriented based
|
||||
on ``width`` and ``height``. You can change this behavior using
|
||||
:cpp:expr:`lv_switch_set_orientation(widget, orientation)`. Possible values for
|
||||
``orientation`` are:
|
||||
|
||||
- :cpp:enumerator:`LV_SWITCH_ORIENTATION_AUTO`
|
||||
- :cpp:enumerator:`LV_SWITCH_ORIENTATION_HORIZONTAL`
|
||||
- :cpp:enumerator:`LV_SWITCH_ORIENTATION_VERTICAL`
|
||||
|
||||
|
||||
|
||||
@ -57,7 +72,7 @@ Change orientation
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the switch changes state.
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when Switch changes state.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
@ -72,9 +87,9 @@ Events
|
||||
Keys
|
||||
****
|
||||
|
||||
- ``LV_KEY_UP/RIGHT`` Turns on the slider
|
||||
- ``LV_KEY_DOWN/LEFT`` Turns off the slider
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` Toggles the switch
|
||||
- ``LV_KEY_UP/RIGHT`` Turns Switch ON
|
||||
- ``LV_KEY_DOWN/LEFT`` Turns Switch OFF
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` Toggles the Switch
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -4,29 +4,33 @@
|
||||
Table (lv_table)
|
||||
================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Tables, as usual, are built from rows, columns, and cells containing
|
||||
texts.
|
||||
Tables are built from rows, columns, and cells containing text.
|
||||
|
||||
The Table Widget is very lightweight because only the texts are stored.
|
||||
No real Widgets are created for cells but they are just drawn on the
|
||||
fly.
|
||||
The Table Widget is very lightweight because only the text strings are stored.
|
||||
No real Widgets are created for cells --- they are just drawn on the fly.
|
||||
|
||||
The Table is added to the default group (if it is set). Besides the
|
||||
Table is an editable Widget to allow selecting a cell with encoder
|
||||
The Table is added to the default group (if one is set).
|
||||
Table is an editable Widget, allow selecting a cell with encoder and keyboard
|
||||
navigation as well.
|
||||
|
||||
|
||||
|
||||
.. _lv_table_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the table uses all the typical
|
||||
background style properties.
|
||||
- :cpp:enumerator:`LV_PART_ITEMS` The cells of the table also use all the typical
|
||||
background style properties and the text properties.
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the Table; uses the :ref:`typical
|
||||
background style properties <typical bg props>`.
|
||||
- :cpp:enumerator:`LV_PART_ITEMS` The cells of the Table also use the
|
||||
:ref:`typical background style properties <typical bg props>` as well as text
|
||||
style properties.
|
||||
|
||||
|
||||
|
||||
.. _lv_table_usage:
|
||||
|
||||
@ -36,31 +40,31 @@ Usage
|
||||
Set cell value
|
||||
--------------
|
||||
|
||||
The cells can store only text so numbers need to be converted to text
|
||||
before displaying them in a table.
|
||||
Cells can store only text so numbers need to be converted to text
|
||||
before displaying them in a Table.
|
||||
|
||||
:cpp:expr:`lv_table_set_cell_value(table, row, col, "Content")`. The text is
|
||||
saved by the table so it can be even a local variable.
|
||||
saved by the Table so the buffer containing the string can be a local variable.
|
||||
|
||||
Line breaks can be used in the text like ``"Value\n60.3"``.
|
||||
|
||||
New rows and columns are automatically added is required
|
||||
New rows and columns are automatically added as required.
|
||||
|
||||
Rows and Columns
|
||||
----------------
|
||||
|
||||
To explicitly set number of rows and columns use
|
||||
:cpp:expr:`lv_table_set_row_count(table, row_cnt)` and
|
||||
:cpp:expr:`lv_table_set_column_count(table, col_cnt)`
|
||||
:cpp:expr:`lv_table_set_column_count(table, col_cnt)`.
|
||||
|
||||
Width and Height
|
||||
----------------
|
||||
|
||||
The width of the columns can be set with
|
||||
Column width can be set with
|
||||
:cpp:expr:`lv_table_set_column_width(table, col_id, width)`. The overall width of
|
||||
the Table Widget will be set to the sum of columns widths.
|
||||
the Table Widget will be set to the sum of all column widths.
|
||||
|
||||
The height is calculated automatically from the cell styles (font,
|
||||
Height is calculated automatically from the cell styles (font,
|
||||
padding etc) and the number of rows.
|
||||
|
||||
Merge cells
|
||||
@ -68,18 +72,18 @@ Merge cells
|
||||
|
||||
Cells can be merged horizontally with
|
||||
:cpp:expr:`lv_table_add_cell_ctrl(table, row, col, LV_TABLE_CELL_CTRL_MERGE_RIGHT)`.
|
||||
To merge more adjacent cells call this function for each cell.
|
||||
To merge more adjacent cells, call this function for each cell.
|
||||
|
||||
Scroll
|
||||
------
|
||||
Scrolling
|
||||
---------
|
||||
|
||||
If the label's width or height is set to :c:macro:`LV_SIZE_CONTENT` that size
|
||||
will be used to show the whole table in the respective direction. E.g.
|
||||
If a Table's width or height is set to :c:macro:`LV_SIZE_CONTENT` that size
|
||||
will be used to show the whole Table in the respective direction. E.g.
|
||||
:cpp:expr:`lv_obj_set_size(table, LV_SIZE_CONTENT, LV_SIZE_CONTENT)`
|
||||
automatically sets the table size to show all the columns and rows.
|
||||
automatically sets the Table size to show all columns and rows.
|
||||
|
||||
If the width or height is set to a smaller number than the "intrinsic"
|
||||
size then the table becomes scrollable.
|
||||
If the width or height is set to a smaller number than its "intrinsic"
|
||||
size then the Table becomes scrollable.
|
||||
|
||||
|
||||
|
||||
@ -104,15 +108,16 @@ Events
|
||||
Keys
|
||||
****
|
||||
|
||||
The following *Keys* are processed by Table Widgets: -
|
||||
``LV_KEY_RIGHT/LEFT/UP/DOWN/`` Select a cell.
|
||||
The following *Keys* are processed by Table Widgets:
|
||||
|
||||
- ``LV_KEY_RIGHT/LEFT/UP/DOWN/`` Select a cell.
|
||||
|
||||
Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to
|
||||
``LV_EVENT_PRESSED/PRESSING/RELEASED`` etc.
|
||||
|
||||
:cpp:expr:`lv_table_get_selected_cell(table, &row, &col)` can be used to get the
|
||||
currently selected cell. Row and column will be set to
|
||||
:c:macro:`LV_TABLE_CELL_NONE` no cell is selected.
|
||||
:c:macro:`LV_TABLE_CELL_NONE` if no cell is selected.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user