feat(docs): batch 5 of proofread/edited docs (#7218)

docs/details/widgets/canvas.rst

@@ -4,20 +4,23 @@
 Canvas (lv_canvas)
 ==================
 
+
 Overview
 ********
 
-A Canvas inherits from :ref:`Image <lv_image>` where the user can draw
+A Canvas inherits from :ref:`Image <lv_image>` and extends it, enabling the user to draw
-anything. Rectangles, texts, images, lines, arcs can be drawn here using
+anything. Rectangles, text, images, lines, arcs, etc. can be drawn here using
-lvgl's drawing engine.
+LVGL's extensive drawing engine.
+
 
 .. _lv_canvas_parts_and_styles:
 
 Parts and Styles
 ****************
 
-- :cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle style properties and image
+- :cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle and image style
-  style properties.
+  properties.
+
 
 .. _lv_canvas_usage:
 
@@ -27,49 +30,52 @@ Usage
 Buffer
 ------
 
-The Canvas needs a buffer in which it stores the drawn image. To assign a
+The Canvas needs a buffer in which to store the drawn image. To assign a
 buffer to a Canvas, use
 :cpp:expr:`lv_canvas_set_buffer(canvas, buffer, width, height, LV_COLOR_FORMAT_...)`.
 Where ``buffer`` is a static buffer (not just a local variable) to hold
-the image of the canvas. For example for a 100x50 ARGB8888 buffer:
+the image of the Canvas. For example for a 100x50 ARGB8888 buffer:
 ``static uint8_t buffer[100 * 50 * 4]``.
 
 Or you can use
-``static uint8_t buffer[LV_CANVAS_BUF_SIZE(width, height, bit_per_pixel, stride_in_bytes)]``.
+``static uint8_t buffer[LV_CANVAS_BUF_SIZE(width, height, bits_per_pixel, stride_in_bytes)]``.
 
-The canvas supports all the color formats like
+Canvas supports all the color formats like
 :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` or :cpp:enumerator:`LV_COLOR_FORMAT_I2`. See the full
 list in the :ref:`Color formats <overview_image_color_formats>` section.
 
 Indexed colors
 --------------
 
-For ``LV_COLOR_FORMAT_I1/2/4/8`` color formats a palette needs to be
+For indexed color formats (``LV_COLOR_FORMAT_I1/2/4/8``), the palette needs to be
-initialized with :cpp:expr:`lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000))`. It
+populated for all palette indices that will be used using
-sets pixels with *index=3* to red.
+:cpp:expr:`lv_canvas_set_palette(canvas, index, color)`.  For example, the following
+sets pixels with *index==3* to red.
+
+.. code-block:: c
+
+    lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000))
 
 Drawing
 -------
 
-To set a pixel's color on the canvas, use
+To set an individual pixel's color on the Canvas, use
-:cpp:expr:`lv_canvas_set_px_color(canvas, x, y, color, opa)`. With
+:cpp:expr:`lv_canvas_set_px(canvas, x, y, color, opa)`.  With indexed color formats
-``LV_COLOR_FORMAT_I1/2/4/8`` the index of the color needs to be passed as
+(``LV_COLOR_FORMAT_I1/2/4/8``) pass the color index as the ``color`` argument.
-color like this ``lv_color_from_int(13);``. It passes index 13 as a color.
-
 
 :cpp:expr:`lv_canvas_fill_bg(canvas, lv_color_hex(0x00ff00), LV_OPA_50)` fills the whole
-canvas to blue with 50% opacity. Note that if the current color format
+Canvas to blue with 50% opacity. Note that if the current color format
 doesn't support colors (e.g. :cpp:enumerator:`LV_COLOR_FORMAT_A8`) the color will be
 ignored. Similarly, if opacity is not supported
-(e.g. :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`) it will be ignored.
+(e.g. :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`), it will be ignored.
 
-An array of pixels can be copied to the canvas with
+An array of pixels can be copied to the Canvas with
 :cpp:expr:`lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height)`. The
-color format of the buffer and the canvas need to match.
+color format of the buffer and Canvas need to match.
 
-To draw something to the canvas use LVGL's draw functions directly. See the examples for more details.
+To draw something to the Canvas use LVGL's draw functions directly. See the examples for more details.
 
-The draw function can draw to any color format to which LVGL can render. Typically it means
+The draw functions can draw to any color format to which LVGL can render. Typically this means
 :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`, :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`,
 :cpp:enumerator:`LV_COLOR_FORMAT_XRGB888`, and :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`.
 
@@ -80,8 +86,7 @@ The draw function can draw to any color format to which LVGL can render. Typical
 Events
 ******
 
-No special events are sent by canvas Widgets. The same events are sent
+No special events are sent by Canvas Widgets.
-as for the
 
 .. admonition::  Further Reading
 

docs/details/widgets/image.rst

@@ -7,10 +7,10 @@ Image (lv_image)
 Overview
 ********
 
-Images are the basic Widget to display images from flash (as arrays) or
+Images are Widgets that display images from flash (as arrays) or
 from files. Images can display symbols (``LV_SYMBOL_...``) as well.
 
-Using the :ref:`Image decoder interface <overview_image_decoder>` custom image formats
+Using the :ref:`Image decoder interface <overview_image_decoder>`, custom image formats
 can be supported as well.
 
 .. _lv_image_parts_and_styles:
@@ -19,7 +19,7 @@ Parts and Styles
 ****************
 
 - :cpp:enumerator:`LV_PART_MAIN` A background rectangle that uses the typical
-  background style properties and the image itself using the image
+  background style properties, and the image itself uses the image
   style properties.
 
 .. _lv_image_usage:
@@ -32,47 +32,52 @@ Image source
 
 To provide maximum flexibility, the source of the image can be:
 
-- a variable in code (a C array with the pixels).
+- a variable in code (a C array containing the pixels).
 - a file stored externally (e.g. on an SD card).
-- a text with :ref:`Symbols <fonts_symbols>`.
+- a :ref:`Symbol <fonts_symbols>` as text.
 
 To set the source of an image, use :cpp:expr:`lv_image_set_src(img, src)`.
 
 To generate a pixel array from a PNG, JPG or BMP image, use the `Online image converter tool <https://lvgl.io/tools/imageconverter>`__
-and set the converted image with its pointer  :cpp:expr:`lv_image_set_src(img1, &converted_img_var)`
+and set the converted image as the image source with its pointer with
-To make the variable visible in the C file, you need to declare it with
+:cpp:expr:`lv_image_set_src(img1, &converted_img_var)`.
+To make the converted image variable accessible from the C file, declare it with
 :cpp:expr:`LV_IMAGE_DECLARE(converted_img_var)`.
 
 To use external files, you also need to convert the image files using
-the online converter tool but now you should select the binary output
+the online converter tool, but select the binary output
 format. You also need to use LVGL's file system module and register a
-driver with some functions for the basic file operation. Go to the
+driver with some functions for basic file operations.  See
-:ref:`File system <overview_file_system>` to learn more. To set an image sourced
+:ref:`File system <overview_file_system>` to learn more.  Then set the translated
-from a file, use :cpp:expr:`lv_image_set_src(img, "S:folder1/my_img.bin")`.
+image as the image source with :cpp:expr:`lv_image_set_src(img, "S:folder1/my_img.bin")`.
 
-You can also set a symbol similarly to :ref:`Labels <lv_label>`. In
+You can also set a symbol as an image source similar to a :ref:`Labels <lv_label>`. In
 this case, the image will be rendered as text according to the *font*
-specified in the style. It enables to use of light-weight monochrome
+specified in the style. It enables the use of light-weight monochrome
-"letters" instead of real images. You can set symbol like
+"characters" instead of real images. You can set a symbol as an image source with
 :cpp:expr:`lv_image_set_src(img1, LV_SYMBOL_OK)`.
 
 Label as an image
 -----------------
 
-Images and labels are sometimes used to convey the same thing. For
+Images and labels are sometimes used to convey the same thing, such as
-example, to describe what a button does. Therefore, images and labels
+describing what a button does.  In this context, images and labels
-are somewhat interchangeable, that is the images can display texts by
+are somewhat interchangeable:  images can display text by
-using :c:macro:`LV_SYMBOL_DUMMY` as the prefix of the text. For example,
+using the macro :c:macro:`LV_SYMBOL_DUMMY` (which equates to a 3-byte C string
-:cpp:expr:`lv_image_set_src(img, LV_SYMBOL_DUMMY, "Some text")`.
+containing a special code) as the prefix of the text.  For example,
+``lv_image_set_src(img, LV_SYMBOL_DUMMY "Some text")``.
 
 Transparency
 ------------
 
-The internal (variable) and external images support 2 transparency
+The internal (pixel array) and external images support 2 transparency
 handling methods:
 
--  **Alpha byte**: An alpha byte is added to every pixel that contains
+-  **Alpha byte**: An alpha channel is added to every pixel that contains
-   the pixel's opacity
+   its opacity, typically a byte.  It is the 'A' in the the various color formats
+   that contain an alpha channel, such as ARGB8888, ARGB8565, ARGB1555, etc.
+-  **Indexed transparent color**:  a specific index in a color palette serves to
+   signal transparency for each pixel that uses it.
 
 Palette and Alpha index
 -----------------------
@@ -80,11 +85,11 @@ Palette and Alpha index
 Besides the *True color* (RGB) color format, the following formats are
 supported:
 
-- **Indexed**: Image has a palette.
+- **Indexed**: Image has a color palette, and each pixel is an index into that palette.
-- **Alpha indexed**: Only alpha values are stored.
+- **Alpha indexed**: The values stored at pixel positions are alpha (opacity) values.
 
-These options can be selected in the image converter. To learn more
+These options can be selected in the image converter. Learn more
-about the color formats, read the :ref:`Images <overview_image>` section.
+about color formats in the :ref:`overview_image_color_formats` section.
 
 Recolor
 -------
@@ -95,7 +100,7 @@ inactive, pressed, etc.) of an image without storing more versions of
 the same image. This feature can be enabled in the style by setting
 ``img_recolor_opa`` between :cpp:enumerator:`LV_OPA_TRANSP` (no recolor, value: 0) and
 :cpp:enumerator:`LV_OPA_COVER` (full recolor, value: 255). The default value is
-:cpp:enumerator:`LV_OPA_TRANSP` so this feature is disabled.
+:cpp:enumerator:`LV_OPA_TRANSP` causing this feature to be disabled.
 
 The color to mix is set by ``img_recolor``.
 
@@ -111,55 +116,56 @@ or a "running image" effect can be created by :ref:`Animating <animation>` the x
 Transformations
 ---------------
 
-Using the :cpp:expr:`lv_image_set_scale(img, factor)` the images will be zoomed.
+You can zoom images in or out by using :cpp:expr:`lv_image_set_scale(img, factor)`.
 Set ``factor`` to ``256`` or :c:macro:`LV_SCALE_NONE` to disable zooming. A
 larger value enlarges the images (e.g. ``512`` double size), a smaller
-value shrinks it (e.g. ``128`` half size). Fractional scale works as
+value shrinks it (e.g. ``128`` half size). Fractional scaling works using a value
-well. E.g. ``281`` for 10% enlargement.
+that is proportionally larger or smaller, e.g. ``281`` for 10% enlargement.
 
 :cpp:expr:`lv_image_set_scale_x(img, factor)` and
-:cpp:expr:`lv_image_set_scale_y(img, factor)` also can be used to
+:cpp:expr:`lv_image_set_scale_y(img, factor)` can also be used to
-the scale independently horizontally and vertically (non-uniform scale).
+set the horizontal and vertical scaling independently.  They can be different values.
 
-To rotate the image use :cpp:expr:`lv_image_set_rotation(img, angle)`. Angle has 0.1
+To rotate the image use :cpp:expr:`lv_image_set_rotation(img, angle_x10)`.
-degree precision, so for 45.8° set 458.
+The ``angle_x10`` argument is an ``int32_t`` containing the angle (in degrees)
+multiplied by 10.  This gives 0.1-degree resolution.  Example:  458 means 45.8°.
 
 By default, the pivot point of the rotation is the center of the image.
-It can be changed with :cpp:expr:`lv_image_set_pivot(img, pivot_x, pivot_y)`.
+This can be changed with :cpp:expr:`lv_image_set_pivot(img, pivot_x, pivot_y)` where
-``0;0`` is the top left corner.
+the coordinates ``(0,0)`` represent the top left corner.
 
 The quality of the transformation can be adjusted with
-:cpp:expr:`lv_image_set_antialias(img, true)`. With enabled anti-aliasing
+:cpp:expr:`lv_image_set_antialias(img, true)`. Enabling anti-aliasing
-the transformations are higher quality but slower.
+causes the transformations to be of higher quality, but slower.
 
-The transformations require the whole image to be available. Therefore
+Transformations require the whole image to be available. Therefore
-indexed images (``LV_COLOR_FORMAT_I1/2/4/8_...``), alpha only images cannot be transformed.
+indexed images (``LV_COLOR_FORMAT_I1/2/4/8_...``) and alpha only images cannot be transformed.
-In other words transformations work only on normal (A)RGB or A8 images stored as
+In other words transformations work only on normal (A)RGB or A8 images stored as a
-C array, or if a custom :ref:`overview_image_decoder`
+C array, or on images provided by a custom :ref:`overview_image_decoder`
-returns the whole image.
+that returns the whole image.
 
-Note that the real coordinates of image Widgets won't change during
+Note that the real coordinates of image Widgets do not change with a
 transformation. That is :cpp:expr:`lv_obj_get_width/height/x/y()` will return
 the original, non-zoomed coordinates.
 
-**IMPORTANT** The transformation of the image is independent of the
+**IMPORTANT**:  The transformation of the image is independent of the transformation
-transformation properties coming from styles. (See
+properties :ref:`coming from styles <style_opacity_blend_modes_transformations>`.
-:ref:`here <style_opacity_blend_modes_transformations>`). The main
+The main differences are that pure Image Widget transformations:
-differences are that pure image widget transformation
 
-- doesn't transform the children of the image widget
+- do not transform the children of the Image Widget, and
-- image is transformed directly without creating an intermediate layer (buffer) to snapshot the widget
+- the image is transformed directly without creating an intermediate layer (buffer) to snapshot the Widget.
 
 Inner align
 -----------
 
-By default the image widget's width and height is :cpp:enumerator:`LV_SIZE_CONTENT`.
+By default the image Widget's width and height are :cpp:enumerator:`LV_SIZE_CONTENT`,
-It means that the widget will be sized automatically according to the image source.
+meaning that the Widget will be sized automatically to the size of its image source.
 
-If the widget's width or height is set the larger value the ``inner_align`` property tells
+If the Widget's width or height is set to a different value, the value of the ``inner_align``
-how to align the image source inside the widget.
+property (set using :cpp:expr:`lv_image_set_inner_align(widget, align)`) governs how
+the image source is aligned inside the Widget.
 
-The alignment set any of these:
+``align`` can be any of these values:
 
 - :cpp:enumerator:`LV_IMAGE_ALIGN_DEFAULT`: Meaning top left
 - :cpp:enumerator:`LV_IMAGE_ALIGN_TOP_LEFT`
@@ -174,16 +180,14 @@ The alignment set any of these:
 - :cpp:enumerator:`LV_IMAGE_ALIGN_STRETCH`
 - :cpp:enumerator:`LV_IMAGE_ALIGN_TILE`
 
-The ``offset`` value is applied after the image source is aligned. For example setting an ``y=-10``
+Any ``offset`` value is applied after the image source is aligned. For example setting
-and :cpp:enumerator:`LV_IMAGE_ALIGN_CENTER` will move the image source up a little bit
+an offset of ``y=-10`` with ``align`` == :cpp:enumerator:`LV_IMAGE_ALIGN_CENTER` will
-from the center of the widget.
+move the image source up 10 pixels from the center of the Widget.
 
-Or to automatically scale or tile the image
+To automatically scale or tile the image, pass one of these ``align`` values:
 
-- :cpp:enumerator:`LV_IMAGE_ALIGN_STRETCH` Set X and Y scale to fill the widget's area
+- :cpp:enumerator:`LV_IMAGE_ALIGN_STRETCH` Set X and Y scale to fill the Widget's area
-- :cpp:enumerator:`LV_IMAGE_ALIGN_TILE` Tile the image to will the widget area. Offset is applied to shift the tiling.
+- :cpp:enumerator:`LV_IMAGE_ALIGN_TILE` Tile image to fill Widget's area. Offset is applied to shift the tiling.
-
-The alignment can be set by :cpp:func:`lv_image_set_inner_align`
 
 
 
@@ -193,8 +197,8 @@ Events
 ******
 
 No special events are sent by Image Widgets.  By default, Image Widgets are created
-without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make a Label Widget
+without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make an Image Widget
-emit LV_EVENT_CLICKED events if desired.
+detect and emit LV_EVENT_CLICKED events if desired.
 
 .. admonition::  Further Reading
 

docs/details/widgets/imagebutton.rst

@@ -4,24 +4,27 @@
 Image Button (lv_imagebutton)
 =============================
 
+
 Overview
 ********
 
-The Image button is very similar to the simple 'Button' Widget. The only
+The Image Button is very similar to the simple 'Button' Widget. The only
-difference is that it displays user-defined images in each state instead
+difference is that it displays user-defined images for each state instead
-of drawing a rectangle.
+of drawing a rectangle.  The list of states is covered below.
 
 You can set a left, right and center image, and the center image will be
 repeated to match the width of the Widget.
 
+
 .. _lv_imagebutton_parts_and_styles:
 
 Parts and Styles
 ****************
 
 -  :cpp:enumerator:`LV_PART_MAIN` Refers to the image(s). If background style
-   properties are used, a rectangle will be drawn behind the image
+   properties are used, a rectangle will be drawn behind the Image
-   button.
+   Button.
+
 
 .. _lv_imagebutton_usage:
 
@@ -31,15 +34,16 @@ Usage
 Image sources
 -------------
 
-To set the image in a state, use the
+To set the image for a particular state, use
 :cpp:expr:`lv_imagebutton_set_src(imagebutton, LV_IMAGEBUTTON_STATE_..., src_left, src_center, src_right)`.
 
-The image sources work the same as described in the :ref:`Image Widget <lv_image>`
+The image sources work the same as described in :ref:`Image Widget <lv_image>`
-except that "Symbols" are not supported by the Image button. Any of the sources can ``NULL``.
+except that "Symbols" are not supported by the Image Button. ``NULL`` can be passed
+for any of the sources.
 
-If only ``src_center`` is specified, the width of the widget will be set automatically to the
+If only ``src_center`` is specified, the width of the Widget will be set automatically to the
 width of the image. However, if all three sources are set, the width needs to be set by the user
-(using e.g. :cpp:expr:`lv_obj_set_width`) and the center image will be tiled to fill the given size.
+(using e.g. :cpp:func:`lv_obj_set_width`) and the center image will be tiled as needed to fill the given size.
 
 The possible states are:
 
@@ -50,16 +54,17 @@ The possible states are:
 - :cpp:enumerator:`LV_IMAGEBUTTON_STATE_CHECKED_PRESSED`
 - :cpp:enumerator:`LV_IMAGEBUTTON_STATE_CHECKED_DISABLED`
 
-If you set sources only in :cpp:enumerator:`LV_IMAGEBUTTON_STATE_RELEASED`, these sources
+The image sources set for state :cpp:enumerator:`LV_IMAGEBUTTON_STATE_RELEASED` are
-will be used in other states as well. If you set e.g. :cpp:enumerator:`LV_IMAGEBUTTON_STATE_PRESSED`
+used for any state that has not had image sources set for it.  If an image sources
-they will be used in pressed state instead of the released images.
+have been set for other states, e.g. :cpp:enumerator:`LV_IMAGEBUTTON_STATE_PRESSED`,
+they will be used instead when the Image Button is in that state.
 
-States
+Setting State Programmatically
-------
+------------------------------
 
 Instead of the regular :cpp:func:`lv_obj_add_state` and :cpp:func:`lv_obj_remove_state` functions,
-the :cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` function should be
+use :cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` to
-used to manually set a state.
+set the state of Image Buttons.
 
 
 
@@ -68,7 +73,8 @@ used to manually set a state.
 Events
 ******
 
--  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the button is toggled.
+-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when Image Button's CHECKED state is toggled.
+   This requires the Image Button's :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` flag to be set.
 
 .. admonition::  Further Reading
 
@@ -83,11 +89,11 @@ Events
 Keys
 ****
 
--  ``LV_KEY_RIGHT/UP`` Go to toggled state if :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE`
+-  ``LV_KEY_RIGHT/UP`` Go to CHECKED state if :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE`
    is enabled.
--  ``LV_KEY_LEFT/DOWN`` Go to non-toggled state if
+-  ``LV_KEY_LEFT/DOWN`` Go to un-CHECKED state if
    :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` is enabled.
--  :cpp:enumerator:`LV_KEY_ENTER` Clicks the button
+-  :cpp:enumerator:`LV_KEY_ENTER` Clicks the Image Button
 
 .. admonition::  Further Reading
 

docs/details/widgets/keyboard.rst

@@ -4,22 +4,25 @@
 Keyboard (lv_keyboard)
 ======================
 
+
 Overview
 ********
 
-The Keyboard Widget is a special :ref:`Button matrix <lv_buttonmatrix>`
+The Keyboard Widget is a special :ref:`lv_buttonmatrix`
-with predefined keymaps and other features to realize a virtual keyboard
+with predefined keymaps and other features to provide an on-screen virtual keyboard
-to write texts into a :ref:`Text area <lv_textarea>`.
+to write text into a :ref:`lv_textarea`.
+
 
 .. _lv_keyboard_parts_and_styles:
 
 Parts and Styles
 ****************
 
-Similarly to Button matrices Keyboards consist of 2 part:
+Similar to Button Matrix, the Keyboard Widget consist of 2 part:
 
 - :cpp:enumerator:`LV_PART_MAIN` The main part. Uses all the typical background properties
-- :cpp:enumerator:`LV_PART_ITEMS` The buttons. Also uses all typical background properties as well as the *text* properties.
+- :cpp:enumerator:`LV_PART_ITEMS` The buttons. Also uses all typical background properties as well as *text* properties.
+
 
 .. _lv_keyboard_usage:
 
@@ -29,7 +32,7 @@ Usage
 Modes
 -----
 
-The Keyboards have the following modes:
+Keyboards have the following modes:
 
 - :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_LOWER` Display lower case letters
 - :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER` Display upper case letters
@@ -37,56 +40,57 @@ The Keyboards have the following modes:
 - :cpp:enumerator:`LV_KEYBOARD_MODE_NUMBER` Display numbers, +/- sign, and decimal dot
 - :cpp:enumerator:`LV_KEYBOARD_MODE_USER_1` through :cpp:enumerator:`LV_KEYBOARD_MODE_USER_4` User-defined modes.
 
-The ``TEXT`` modes' layout contains buttons to change mode.
+The layouts of the ``TEXT`` modes contain "keys" to change mode.
 
-To set the mode manually, use :cpp:expr:`lv_keyboard_set_mode(kb, mode)`. The
+To set the mode programmatically, use :cpp:expr:`lv_keyboard_set_mode(kb, mode)`. The
 default mode is :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER`.
 
-Assign Text area
+Assign Text Area
 ----------------
 
-You can assign a :ref:`Text area <lv_textarea>` to the Keyboard to
+You can assign a :ref:`Text Area <lv_textarea>` Widget to the Keyboard to
-automatically put the clicked characters there. To assign the text area,
+automatically put the clicked characters there. To assign the Text Area,
-use :cpp:expr:`lv_keyboard_set_textarea(kb, ta)`.
+use :cpp:expr:`lv_keyboard_set_textarea(kb, text_area)`.
 
-Key Popovers
+Key Pop-Overs
-------------
+-------------
 
-To enable key popovers on press, like on common Android and iOS
+To enable key pop-overs on press, like on common Android and iOS
-keyboards, use :cpp:expr:`lv_keyboard_set_popovers(kb, true)`. The default
+keyboards, use :cpp:expr:`lv_keyboard_set_popovers(kb, true)`. Default
-control maps are preconfigured to only show the popovers on keys that
+control maps are preconfigured to only show the pop-overs on keys that
-produce a symbol and not on e.g. space. If you use a custom keymap, set
+produce a symbol (i.e. not on space). If you use a custom keymap (see below), set
-the :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER` flag for all keys that you want to
+the :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER` flag for each key for which
-show a popover.
+a pop-over should be shown.
 
-Note that popovers for keys in the top row will draw outside the widget
+Note that pop-overs for keys in the top row will draw outside the Widget
 boundaries. To account for this, reserve extra free space on top of the
-keyboard or ensure that the keyboard is added *after* any widgets
+Keyboard or ensure that the Keyboard is added *after* any Widgets
-adjacent to its top boundary so that the popovers can draw over those.
+adjacent to its top boundary (placing it "above" those Widgets) so that pop-overs
+will be drawn over them.
 
-The popovers currently are merely a visual effect and don't allow
+Pop-overs currently are merely a visual effect and don't allow
-selecting additional characters such as accents yet.
+selecting additional characters such as accented characters yet.
 
 New Keymap
 ----------
 
-You can specify a new map (layout) for the keyboard with
+You can specify a new map (layout) for the Keyboard with
 :cpp:expr:`lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl)`. See
-the :ref:`Button matrix <lv_buttonmatrix>` for more information about
+Button Matrix's :ref:`button map` section for more information about
-creating new maps and ctrls.
+creating new maps.
 
-Keep in mind that using following keywords will have the same effect as
+Keep in mind that using following keywords in the map will have the same effect as
 with the original map:
 
-- :c:macro:`LV_SYMBOL_OK` Send :cpp:enumerator:`LV_EVENT_READY` to the assigned Text area.
+- :c:macro:`LV_SYMBOL_OK` Send :cpp:enumerator:`LV_EVENT_READY` to the assigned Text Area.
-- :c:macro:`LV_SYMBOL_CLOSE` or :c:macro:`LV_SYMBOL_KEYBOARD` Send :cpp:enumerator:`LV_EVENT_CANCEL` to the assigned Text area.
+- :c:macro:`LV_SYMBOL_CLOSE` or :c:macro:`LV_SYMBOL_KEYBOARD` Send :cpp:enumerator:`LV_EVENT_CANCEL` to the assigned Text Area.
-- :c:macro:`LV_SYMBOL_BACKSPACE` Delete on the left.
+- :c:macro:`LV_SYMBOL_BACKSPACE` Delete character to the left.
-- :c:macro:`LV_SYMBOL_LEFT` Move the cursor left.
+- :c:macro:`LV_SYMBOL_LEFT` Move cursor left.
-- :c:macro:`LV_SYMBOL_RIGHT` Move the cursor right.
+- :c:macro:`LV_SYMBOL_RIGHT` Move cursor right.
 - :c:macro:`LV_SYMBOL_NEW_LINE` New line.
-- ``"ABC"`` Load the uppercase map.
+- ``"ABC"`` Load upper-case map.
-- ``"abc"`` Load the lower case map.
+- ``"abc"`` Load lower-case map.
-- ``"1#"`` Load the lower case map.
+- ``"1#"`` Load number map.
 
 
 
@@ -96,21 +100,21 @@ Events
 ******
 
 -  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the button is pressed/released
-   or repeated after long press. The event data is set to the ID of the
+   or repeated after long press. The event data contains the ID of the
    pressed/released button.
--  :cpp:enumerator:`LV_EVENT_READY`: The *Ok* button is clicked.
+-  :cpp:enumerator:`LV_EVENT_READY`: The *Ok* button was clicked.
--  :cpp:enumerator:`LV_EVENT_CANCEL`: The *Close* button is clicked.
+-  :cpp:enumerator:`LV_EVENT_CANCEL`: The *Close* button was clicked.
 
-The keyboard has a **default event handler** callback called
+The Keyboard has a **default event handler** callback called
 :cpp:func:`lv_keyboard_def_event_cb`, which handles the button pressing, map
-changing, the assigned text area, etc. You can remove it and replace it
+changing, sending events to the assigned text area, etc. You can remove it and replace it
-with a custom event handler if you wish.
+with a custom event handler if you wish, or add an additional call-back of your own.
 
 .. note::
 
-    In 8.0 and newer, adding an event handler to the keyboard does not remove the
+    In LVGL v8.0 and newer, adding an event handler to the Keyboard does not remove the
     default event handler. This behavior differs from v7, where adding an event
-    handler would always replace the previous one.
+    handler would replace the previous one.
 
 .. admonition::  Further Reading
 
@@ -125,8 +129,8 @@ with a custom event handler if you wish.
 Keys
 ****
 
--  ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons and
+-  ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons,
-   select one.
+   selecting the one navigated to.
 -  :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button.
 
 .. admonition::  Further Reading

docs/details/widgets/label.rst

@@ -4,25 +4,28 @@
 Label (lv_label)
 ================
 
+
 Overview
 ********
 
-A label is the basic Widget type that is used to display text.
+A Label is the Widget used to display text.
+
 
 .. _lv_label_parts_and_styles:
 
 Parts and Styles
 ****************
 
-- :cpp:enumerator:`LV_PART_MAIN` Uses all the typical background properties and the
+- :cpp:enumerator:`LV_PART_MAIN` Uses all the typical background and
-  text properties. The padding values can be used to add space between
+  text properties. Padding values can be used to add space between
-  the text and the background.
+  the text and the edges of the Label's background.
 - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
-  larger than the widget's size.
+  larger than the Widget's size.
 - :cpp:enumerator:`LV_PART_SELECTED` Tells the style of the
   :ref:`selected text <lv_label_text_selection>`. Only ``text_color`` and ``bg_color`` style
   properties can be used.
 
+
 .. _lv_label_usage:
 
 Usage
@@ -31,41 +34,43 @@ Usage
 Set text
 --------
 
-You can set the text on a label at runtime with
+You can set the text on a Label at runtime with
 :cpp:expr:`lv_label_set_text(label, "New text")`. This will allocate a buffer
 dynamically, and the provided string will be copied into that buffer.
 Therefore, you don't need to keep the text you pass to
 :cpp:func:`lv_label_set_text` in scope after that function returns.
 
-With :cpp:expr:`lv_label_set_text_fmt(label, "Value: %d", 15)` printf formatting
+With :cpp:expr:`lv_label_set_text_fmt(label, fmt, ...)` printf formatting
-can be used to set the text.
+can be used to set the text.  Example:  :cpp:expr:`lv_label_set_text_fmt(label, "Value: %d", 15)`.
 
 Labels are able to show text from a static character buffer as well.  To do so, use
 :cpp:expr:`lv_label_set_text_static(label, "Text")`.  In this case, the text is not
 stored in dynamic memory and the given buffer is used directly instead.  This means
-that the character buffer *must not* be a local variable that goes out of scope when
+that the contents of the character buffer *must* remain valid for the life of the
-the function exits.
+label or until another buffer is set via one of the above functions.
 
 ``const`` strings are safe to use with :cpp:func:`lv_label_set_text_static` since
 they are stored in ROM memory, which is always accessible.
 
-.. danger::
+.. warning::
 
     Do not use ``const`` strings with :cpp:func:`lv_label_set_text_static` when the
-    label is being used in :cpp:enumerator:`LV_LABEL_LONG_DOT` mode since the label
+    Label is being used in :cpp:enumerator:`LV_LABEL_LONG_DOT` mode since the Label
     will attempt to do an in-place edit of the string.  This will cause an MCU
     exception by attempting to modify program memory (ROM).
 
+.. _label_rapidly_updating_text:
+
 .. caution::
 
-    If your label is updated with new strings rapidly (e.g. > 30X / second, such as
+    If your Label is updated with new strings rapidly (e.g. > 30X / second, such as
-    RPM in a dashboard), and the length of those strings changes frequently, it is
+    RPM in a dashboard, or an ADC value), and the length of those strings changes
-    advisable to:
+    frequently, it is advisable to:
 
     - allocate a static string buffer large enough contain the largest possible string,
     - update that buffer with the new strings only when they will make a visible
       difference for the end user, and
-    - update the label with :cpp:expr:`lv_label_set_text_static(label, buffer)` using that buffer.
+    - update the Label with :cpp:expr:`lv_label_set_text_static(label, buffer)` using that buffer.
 
     Reason:  if you use :cpp:expr:`lv_label_set_text(label, new_text)`, a memory
     realloc() will be forced every time the length of the string changes.  That
@@ -76,7 +81,7 @@ they are stored in ROM memory, which is always accessible.
 Newline
 -------
 
-Newline characters are handled automatically by the label Widget. You
+Newline characters are handled automatically by the Label Widget. You
 can use ``\n`` to make a line break. For example:
 ``"line1\nline2\n\nline4"``
 
@@ -85,22 +90,22 @@ can use ``\n`` to make a line break. For example:
 Long modes
 ----------
 
-By default, the width and height of the label is set to
+By default, the width and height of the Label are set to
-:c:macro:`LV_SIZE_CONTENT`. Therefore, the size of the label is automatically
+:c:macro:`LV_SIZE_CONTENT`. Thus, the size of the Label is automatically expanded
-expanded to the text size. Otherwise, if the width or height are
+to the text size + padding + border width. Otherwise, if the width or height are
 explicitly set (using e.g.\ :cpp:func:`lv_obj_set_width` or a layout), the lines
-wider than the label's width can be manipulated according to several
+wider than the Label's width can be manipulated according to several
 long mode policies. Similarly, the policies can be applied if the height
-of the text is greater than the height of the label.
+of the text is greater than the height of the Label.
 
-- :cpp:enumerator:`LV_LABEL_LONG_WRAP` Wrap lines that are too long. If the height is :c:macro:`LV_SIZE_CONTENT` the label's
+- :cpp:enumerator:`LV_LABEL_LONG_WRAP` Wrap lines that are too long. If the height is :c:macro:`LV_SIZE_CONTENT` the Label's
   height will be expanded, otherwise the text will be clipped. (Default)
-- :cpp:enumerator:`LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the label with dots (``.``)
+- :cpp:enumerator:`LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the Label with dots (``.``)
-- :cpp:enumerator:`LV_LABEL_LONG_SCROLL` If the text is wider than the label scroll it horizontally back and forth. If it's
+- :cpp:enumerator:`LV_LABEL_LONG_SCROLL` If the text is wider than the label, scroll it horizontally back and forth. If it's
   higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
-- :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` If the text is wider than the label scroll it horizontally continuously. If it's
+- :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` If the text is wider than the Label, scroll it horizontally continuously. If it's
   higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
-- :cpp:enumerator:`LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside the label.
+- :cpp:enumerator:`LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside the Label.
 
 You can specify the long mode with :cpp:expr:`lv_label_set_long_mode(label, LV_LABEL_LONG_...)`
 
@@ -118,33 +123,34 @@ Text selection
 --------------
 
 If enabled by :c:macro:`LV_LABEL_TEXT_SELECTION` part of the text can be
-selected. It's similar to when you use your mouse on a PC to select a
+selected. It's similar to when you use your mouse on a PC to select
 text. The whole mechanism (click and select the text as you drag your
 finger/mouse) is implemented in :ref:`Text area <lv_textarea>` and
-the Label widget only allows manual text selection with
+the Label Widget only allows programmatic text selection with
 :cpp:expr:`lv_label_get_text_selection_start(label, start_char_index)` and
-:cpp:expr:`lv_label_get_text_selection_start(label, end_char_index)`.
+:cpp:expr:`lv_label_get_text_selection_end(label, end_char_index)`.
 
 .. _lv_label_text_alignment:
 
 Text alignment
 --------------
 
-To horizontally align the lines of a label the `text_align` style property can be used with
+To horizontally align the lines of a Label the `text_align` style property can be used with
-:cpp:func:`lv_obj_set_style_text_align` or :cpp:func:`lv_style_set_text_align`
+:cpp:func:`lv_obj_set_style_text_align` or :cpp:func:`lv_style_set_text_align`,
-Note that it has a visible effect only if
+passing one of the ``LV_TEXT_ALIGN_...`` enumeration values.
+Note that this has a visible effect only if:
 
-- the label widget's width is larger than the width of the longest line of the text
+- the Label Widget's width is larger than the width of the longest line of text, and
-- the text has multiple lines with non equal line length
+- the text has multiple lines with different line lengths.
 
 .. _lv_label_very_long_texts:
 
-Very long texts
+Very long text
----------------
+--------------
 
-LVGL can efficiently handle very long (e.g. > 40k characters) labels by
+LVGL can efficiently handle very long (e.g. > 40k characters) Labels by
 saving some extra data (~12 bytes) to speed up drawing. To enable this
-feature, set ``LV_LABEL_LONG_TXT_HINT   1`` in ``lv_conf.h``.
+feature, set ``LV_LABEL_LONG_TXT_HINT`` to ``1`` in ``lv_conf.h``.
 
 .. _lv_label_custom_scrolling_animations:
 
@@ -153,7 +159,7 @@ Custom scrolling animations
 
 Some aspects of the scrolling animations in long modes
 :cpp:enumerator:`LV_LABEL_LONG_SCROLL` and :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` can be
-customized by setting the animation property of a style, using
+customized by setting the Label's animation style property, using
 :cpp:func:`lv_style_set_anim`.
 It will be treated as a template which will be used to create the scroll animations.
 
@@ -162,8 +168,8 @@ It will be treated as a template which will be used to create the scroll animati
 Symbols
 -------
 
-The labels can display symbols alongside letters (or on their own). Read
+The Labels can display symbols alongside letters (or on their own). Read
-the :ref:`font` section to learn more about the symbols.
+the :ref:`font` section to learn more about symbols.
 
 
 

docs/details/widgets/led.rst

@@ -7,8 +7,8 @@ LED (lv_led)
 Overview
 ********
 
-The LEDs are rectangle-like (or circle) Widget whose brightness can be
+LEDs are rectangle-like (or circle) Widgets whose brightness can be
-adjusted. With lower brightness the colors of the LED become darker.
+adjusted. With lower brightness the color of the LED becomes darker.
 
 .. _lv_led_parts_and_styles:
 
@@ -25,15 +25,15 @@ Usage
 Color
 -----
 
-You can set the color of the LED with
+You set the color of the LED with
-:cpp:expr:`lv_led_set_color(led, lv_color_hex(0xff0080))`. This will be used as
+:cpp:expr:`lv_led_set_color(led, lv_color_hex(0xff0080))`. This will be used as its
 background color, border color, and shadow color.
 
 Brightness
 ----------
 
-You can set their brightness with :cpp:expr:`lv_led_set_bright(led, bright)`.
+You can set their brightness with :cpp:expr:`lv_led_set_brightness(led, brightness)`.
-The brightness should be between 0 (darkest) and 255 (lightest).
+The ``brightness`` value should be in the range 0 (darkest) to 255 (lightest).
 
 Toggle
 ------
@@ -42,6 +42,10 @@ Use :cpp:expr:`lv_led_on(led)` and :cpp:expr:`lv_led_off(led)` to set the bright
 a predefined ON or OFF value. The :cpp:expr:`lv_led_toggle(led)` toggles between
 the ON and OFF state.
 
+You can set custom LED ON and OFF brightness values by defining macros
+``LV_LED_BRIGHT_MAX`` and ``LV_LED_BRIGHT_MIN`` in your project.  Their default
+values are 80 and 255. These too must be in the range [0..255].
+
 
 
 .. _lv_led_events:

docs/details/widgets/line.rst

@@ -25,22 +25,22 @@ Usage
 Set points
 ----------
 
-The points have to be stored in an :cpp:struct:`lv_point_precise_t` array and passed to
+A Line's points have to be stored in an :cpp:struct:`lv_point_precise_t` array and passed to
 the Widget by the :cpp:expr:`lv_line_set_points(lines, point_array, point_cnt)`
 function.
 
 Their coordinates can either be specified as raw pixel coordinates
-(e.g. ``{5, 10}``), or as a percentage of the line's bounding box using
+(e.g. ``{5, 10}``), or as a percentage of the Line's bounding box using
-:cpp:expr:`lv_pct(x)`. In the latter case, the line's width/height may need to
+:cpp:expr:`lv_pct(x)`. In the latter case, the Line's width/height may need to
-be set explicitly using ``lv_obj_set_width/height``, as percentage
+be set explicitly using :cpp:func:`lv_obj_set_width` and :cpp:func:`lv_obj_set_height`,
-values do not automatically expand the bounding box.
+as percentage values do not automatically expand the bounding box.
 
 Auto-size
 ---------
 
 By default, the Line's width and height are set to :c:macro:`LV_SIZE_CONTENT`.
 This means it will automatically set its size to fit all the points. If
-the size is set explicitly, parts on the line may not be visible.
+the size is set explicitly, parts on the Line may not be visible.
 
 Invert y
 --------
@@ -48,7 +48,7 @@ Invert y
 By default, the *y == 0* point is in the top of the Widget. It might be
 counter-intuitive in some cases so the y coordinates can be inverted
 with :cpp:expr:`lv_line_set_y_invert(line, true)`. In this case, *y == 0* will
-be the bottom of the Widget. *y invert* is disabled by default.
+be at the bottom of the Widget. *y invert* is disabled by default.
 
 
 
@@ -57,7 +57,7 @@ be the bottom of the Widget. *y invert* is disabled by default.
 Events
 ******
 
-Only the :ref:`Generic events <events>` are sent by Line Widgets.
+Only :ref:`generic events <events>` are sent by Line Widgets.
 
 .. admonition::  Further Reading
 

docs/details/widgets/list.rst

@@ -4,11 +4,13 @@
 List (lv_list)
 ==============
 
+
 Overview
 ********
 
-The List is basically a rectangle with vertical layout to which Buttons
+The List Widget is basically a rectangle with vertical layout to which Buttons
-and Texts can be added
+and Text can be added.
+
 
 .. _lv_list_parts_and_styles:
 
@@ -17,11 +19,14 @@ Parts and Styles
 
 **Background**
 
-- :cpp:enumerator:`LV_PART_MAIN` The main part of the list that uses all the typical background properties
+- :cpp:enumerator:`LV_PART_MAIN` The main part of the List that uses all the typical background properties
-- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See the :ref:`base_widget`
+- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See :ref:`base_widget`
   documentation for details.
 
-**Buttons and Texts** See the :ref:`Button <lv_button>`\ 's and :ref:`Label <lv_label>`\ 's documentation.
+**Buttons and Text**
+
+- See the :ref:`Button <lv_button>`'s and :ref:`Label <lv_label>`'s documentation.
+
 
 .. _lv_list_usage:
 
@@ -32,16 +37,17 @@ Buttons
 -------
 
 :cpp:expr:`lv_list_add_button(list, icon, text)` adds a full-width button with an icon
+(that can be an image or symbol) and text.  This function returns a pointer to the
+button created, which you can use to, for example, add an event call-back.
 
-- that can be an image or symbol
+The text is scrolled horizontally if it is longer than the button.
-- and a text.
 
-The text starts to scroll horizontally if it's too long.
+Text
+----
 
-Texts
+:cpp:expr:`lv_list_add_text(list, text)` adds a text string.  This function returns a
------
+pointer to the label created, which you can use to, for example, change its text
-
+with one of the ``lv_label_set_text...()`` functions.
-:cpp:expr:`lv_list_add_text(list, text)` adds a text.
 
 
 
@@ -50,7 +56,7 @@ Texts
 Events
 ******
 
-No special events are sent by List Widgets, but events are sent by Buttons as usual.
+No special events are sent by List Widgets, but events can be sent by Buttons as usual.
 
 .. admonition::  Further Reading
 

docs/details/widgets/lottie.rst

@@ -7,15 +7,15 @@ Lottie (lv_lottie)
 Overview
 ********
 
-The Lottie widget is capable of parsing, rasterizing, and playing `Lottie animations <https://lottiefiles.com>`__.
+The Lottie Widget is capable of parsing, rasterizing, and playing `Lottie animations <https://lottiefiles.com>`__.
 
 The Lottie animations are vector based animation. Think of it as the modern combination of SVG and GIF.
 
 The animations can be downloaded from various sources, such as `https://lottiefiles.com/ <https://lottiefiles.com/>`__
-or you can create your own animations using for example Adobe After Effects.
+or you can create your own animations using, for example, Adobe After Effects.
 
-The Lottie widget is based on :ref:`lv_canvas` because in order to render the animation
+The Lottie Widget is based on :ref:`lv_canvas` because in order to render the animation
-the user needs to provide a buffer where the current frame is stored.
+the user needs to provide a buffer where the current animation frame is stored.
 
 .. _lv_lottie_parts_and_styles:
 
@@ -32,9 +32,9 @@ Usage
 Dependencies
 ------------
 
-The Lottie widget uses the `ThorVG <https://github.com/thorvg/thorvg>`__ library which is `integrated into LVGL <https://github.com/lvgl/lvgl/tree/master/src/libs/thorvg>`__.
+The Lottie Widget uses the `ThorVG <https://github.com/thorvg/thorvg>`__ library which is `integrated into LVGL <https://github.com/lvgl/lvgl/tree/master/src/libs/thorvg>`__.
 In order to use Lottie animations :c:macro:`LV_USE_THORVG_INTERNAL` (to use the built-in ThorVG) or
-:c:macro:`LV_USE_THORVG_EXTERNAL` (to link it externally) needs to enabled. For vector graphics in general
+:c:macro:`LV_USE_THORVG_EXTERNAL` (to link it externally) needs to enabled in ``lv_conf.h``. For vector graphics in general
 :c:macro:`LV_USE_VECTOR_GRAPHIC` also needs to be enabled.
 
 As ThorVG is written in C++, when using :c:macro:`LV_USE_THORVG_INTERNAL` be sure that you
@@ -43,12 +43,12 @@ can compile the cpp files.
 Set a buffer
 ------------
 
-In order to render the animation a buffer needs to assign to the Lottie widget.
+In order to render the animation a buffer needs to be assigned to the Lottie Widget.
 The animations are rendered in ARGB8888 format, therefor the buffer's size should be equal to
 ``target_width x target_height x 4`` bytes.
 
 To keep the buffer size and the animation size consistent,
-the size of the widget (i.e. the size of the animation) is set to the dimensions of the buffer internally.
+the size of the Widget (i.e. the size of the animation) is set to the dimensions of the buffer internally.
 
 The buffer can be set with either :cpp:expr:`lv_lottie_set_buffer(lottie, w, h, buf)`
 or :cpp:expr:`lv_lottie_set_draw_buf(lottie, draw_buf)`.
@@ -58,12 +58,13 @@ When a draw buffer is used, it must be already initialized by the user with :cpp
 Set a source
 ------------
 
-``lv_example_lottie_approve.c`` contains an example animation. Instead storing the JSON string, a hex array is stored for the
+``lv_example_lottie_approve.c`` contains an example animation. Instead of storing the JSON string, a hex array is stored for the
 following reasons:
-- avoid escaping ``"`` character in the JSON file
-- some compilers don't support very long strings
 
-``lvgl/scripts/filetohex.py`` can be used to convert a Lottie file a hex
+- to avoid escaping ``"`` character in the JSON file, and
+- some compilers don't support very long strings.
+
+``lvgl/scripts/filetohex.py`` can be used to convert a Lottie file to a hex
 array. E.g.:
 
 .. code-block:: shell
@@ -79,7 +80,11 @@ Note that the Lottie loader doesn't support LVGL's File System interface but a "
 Get the animation
 -----------------
 
-``lv_anim_t * a = lv_lottie_get_anim(lottie)`` return the LVGL animation which controls the
+.. code-block:: c
+
+    lv_anim_t * a = lv_lottie_get_anim(lottie)
+
+returns the LVGL animation which controls the
 Lottie animation. By default it is running infinitely at 60FPS however the LVGL animation
 can be freely adjusted.
 
@@ -90,7 +95,7 @@ can be freely adjusted.
 Events
 ******
 
-No *Keys* are processed by Lottie Widgets.
+No events are emitted by Lottie Widgets.
 
 .. admonition::  Further Reading