feat(docs): batch 7 of proofread/edited docs (#7281)

docs/conf.py

@@ -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.

docs/details/base-widget/styles/style.rst

@@ -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

docs/details/widgets/bar.rst

@@ -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
 -----
 

docs/details/widgets/slider.rst

@@ -4,71 +4,94 @@
 Slider (lv_slider)
 ==================
 
+
+
 Overview
 ********
 
-The Slider Widget looks like a :ref:`Bar <lv_bar>` supplemented with
+The Slider Widget looks like a :ref:`lv_bar` supplemented with
-a knob. The knob can be dragged to set a value. Just like Bar, Slider
+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
+-  :cpp:enumerator:`LV_PART_MAIN` The background of the Slider. Uses the
-   background style properties. ``padding`` makes the indicator smaller
+   :ref:`typical background style properties <typical bg props>`. ``padding`` makes
-   in the respective direction.
+   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.
+   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.
+-  :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the current value;
-   Also uses all the typical background properties to describe the
+   also uses the :ref:`typical background style properties <typical bg props>` to
-   knob(s). By default, the knob is square (with an optional corner
+   describe the knob(s).  By default, the knob is round (radius-style can modify this)
-   radius) with side length equal to the smaller side of the slider. The
+   with side length equal to the smaller dimension of the Slider.  The knob can be
-   knob can be made larger with the ``padding`` values. Padding values
+   made larger with the ``padding`` values.  Padding values can be asymmetric as well.
-   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
+Once a Slider is created, it has:
-animation time is set by the styles' ``anim_time`` property.
 
-To specify the range (min, max values), :cpp:expr:`lv_slider_set_range(slider, min , max)` can be used.
+- value == 0
-The default range is 0..100, and the default drawing direction is from left to right in horizontal mode and
+- default range of [0..100],
-bottom to top in vertical mode. If the minimum value is greater than the maximum value, like
+- horizontal orientation, with
-100..0, the drawing direction changes to the opposite direction.
+- 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_MODE_NORMAL` A normal Slider as described above (default)
-- :cpp:enumerator:`LV_SLIDER_SYMMETRICAL` Draw the indicator form the zero value to
+- :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
+  :cpp:expr:`lv_bar_set_start_value(slider, new_value, LV_ANIM_ON/OFF)`. The start
-  value has to be always smaller than the end value.
+  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
+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
+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
+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
+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`:
+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
+-  :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
+   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_UP/RIGHT`` Increment Slider's value by 1.
--  ``LV_KEY_DOWN/LEFT`` Decrement the slider's value by 1
+-  ``LV_KEY_DOWN/LEFT`` Decrement Slider's value by 1.
 
 .. admonition::  Further Reading
 

docs/details/widgets/span.rst

@@ -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
-***

docs/details/widgets/spangroup.rst

@@ -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
+***

docs/details/widgets/spinbox.rst

@@ -4,33 +4,40 @@
 Spinbox (lv_spinbox)
 ====================
 
+
 Overview
 ********
 
-The Spinbox contains a number as text which can be increased or
+Spinbox contains an integer displayed as a decimal number with a possible fixed
-decreased by *Keys* or API functions. Under the hood the Spinbox is a
+decimal point position and a configurable number of digits.  The value can be
-modified :ref:`Text area <lv_textarea>`.
+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.
+  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
+- :cpp:expr:`lv_spinbox_set_range(spinbox, -1000, 2500)` sets its range. If the
-  value is changed by :cpp:func:`lv_spinbox_set_value`, by
+  value is changed by :cpp:expr:`lv_spinbox_set_value(spinbox)`, by *Keys*,
-  *Keys*,\ ``lv_spinbox_increment/decrement`` this range will be respected.
+  by :cpp:expr:`lv_spinbox_increment(spinbox)` or :cpp:expr:`lv_spinbox_decrement(spinbox)`
-- :cpp:expr:`lv_spinbox_set_step(spinbox, 100)` sets which digits to change on
+  this range will be respected.
-  increment/decrement. Only multiples of ten can be set, and not for example 3.
+- :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
+sets the number format. ``digit_count`` is the total number of digits to display.
-excluding the decimal separator and the sign. ``separator_position`` is
+``separator_position`` is the number of leading digits before the decimal point.
-the number of digits before the decimal point. If 0, no decimal point is displayed.
+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
+rollover enabled, and the user attempts to continue changing the value in
-is disabled the value will remain at the minimum or maximum value.
+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
+- :cpp:enumerator:`LV_KEY_ENTER` With *Encoder*, move focus to next digit.  If focus
-  after the last.
+  is on last digit, focus moves to first digit.
 
 .. admonition::  Further Reading
 

docs/details/widgets/spinner.rst

@@ -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
+Use :cpp:expr:`lv_spinner_set_anim_params(spinner, spin_duration, angle)` to
-of one revolution and the length of he arc can be customized.
+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
 

docs/details/widgets/switch.rst

@@ -4,31 +4,37 @@
 Switch (lv_switch)
 ==================
 
+
 Overview
 ********
 
-The Switch looks like a little slider and can be used to turn something
+Switch Widgets look like little sliders and are used to display, and optionally
-on and off.
+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
+-  :cpp:enumerator:`LV_PART_MAIN` Switch's background; uses the :ref:`typical
-   background style properties. ``padding`` makes the indicator smaller
+   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.
+   the Switch; also uses the :ref:`typical background style properties <typical bg props>`.
--  :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at left or right side
+-  :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the left or right
-   of the indicator. Also uses all the typical background properties to
+   side of the indicator; also uses the :ref:`typical background style properties
-   describe the knob(s). By default, the knob is square (with an
+   <typical bg props>` to modify the knob's appearance. By default, the knob is round
-   optional corner radius) with side length equal to the smaller side of
+   (radius-style can modify this) with diameter slightly smaller than the smaller
-   the slider. The knob can be made larger with the ``padding`` values.
+   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_UP/RIGHT`` Turns Switch ON
--  ``LV_KEY_DOWN/LEFT`` Turns off the slider
+-  ``LV_KEY_DOWN/LEFT`` Turns Switch OFF
--  :cpp:enumerator:`LV_KEY_ENTER` Toggles the switch
+-  :cpp:enumerator:`LV_KEY_ENTER` Toggles the Switch
 
 .. admonition::  Further Reading
 

docs/details/widgets/table.rst

@@ -4,29 +4,33 @@
 Table (lv_table)
 ================
 
+
 Overview
 ********
 
-Tables, as usual, are built from rows, columns, and cells containing
+Tables are built from rows, columns, and cells containing text.
-texts.
 
-The Table Widget is very lightweight because only the texts are stored.
+The Table Widget is very lightweight because only the text strings are stored.
-No real Widgets are created for cells but they are just drawn on the
+No real Widgets are created for cells --- they are just drawn on the fly.
-fly.
 
-The Table is added to the default group (if it is set). Besides the
+The Table is added to the default group (if one is set).
-Table is an editable Widget to allow selecting a cell with encoder
+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
+-  :cpp:enumerator:`LV_PART_MAIN` The background of the Table; uses the :ref:`typical
-   background style properties.
+   background style properties <typical bg props>`.
--  :cpp:enumerator:`LV_PART_ITEMS` The cells of the table also use all the typical
+-  :cpp:enumerator:`LV_PART_ITEMS` The cells of the Table also use the
-   background style properties and the text properties.
+   :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
+Cells can store only text so numbers need to be converted to text
-before displaying them in a table.
+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
+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.
+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"
+If the width or height is set to a smaller number than its "intrinsic"
-size then the table becomes scrollable.
+size then the Table becomes scrollable.
 
 
 
@@ -104,15 +108,16 @@ Events
 Keys
 ****
 
-The following *Keys* are processed by Table Widgets: -
+The following *Keys* are processed by Table Widgets:
-``LV_KEY_RIGHT/LEFT/UP/DOWN/`` Select a cell.
+
+- ``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