From 67051b026aba57ac15d3fbcb69d89663f3128fca Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 17 Nov 2024 21:51:24 -0700 Subject: [PATCH] feat(docs): batch 7 of proofread/edited docs (#7281) --- docs/conf.py | 3 +- docs/details/base-widget/styles/style.rst | 6 +- docs/details/widgets/bar.rst | 17 ++ docs/details/widgets/slider.rst | 95 +++++++---- docs/details/widgets/span.rst | 155 ------------------ docs/details/widgets/spangroup.rst | 190 ++++++++++++++++++++++ docs/details/widgets/spinbox.rst | 48 +++--- docs/details/widgets/spinner.rst | 16 +- docs/details/widgets/switch.rst | 53 +++--- docs/details/widgets/table.rst | 65 ++++---- 10 files changed, 380 insertions(+), 268 deletions(-) delete mode 100644 docs/details/widgets/span.rst create mode 100644 docs/details/widgets/spangroup.rst diff --git a/docs/conf.py b/docs/conf.py index 3a1f13e91..2e4e38a23 100755 --- a/docs/conf.py +++ b/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. diff --git a/docs/details/base-widget/styles/style.rst b/docs/details/base-widget/styles/style.rst index 194ba0476..0d08391eb 100644 --- a/docs/details/base-widget/styles/style.rst +++ b/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 ` has three parts: @@ -398,11 +398,13 @@ Style Properties Overview For the full list of style properties click :ref:`here `. +.. _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 diff --git a/docs/details/widgets/bar.rst b/docs/details/widgets/bar.rst index e5871aff9..b22e12ca0 100644 --- a/docs/details/widgets/bar.rst +++ b/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 ----- diff --git a/docs/details/widgets/slider.rst b/docs/details/widgets/slider.rst index eda530e54..851d0f792 100644 --- a/docs/details/widgets/slider.rst +++ b/docs/details/widgets/slider.rst @@ -4,71 +4,94 @@ Slider (lv_slider) ================== + + Overview ******** -The Slider Widget looks like a :ref:`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 `. ``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 `. +- :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the current value; + also uses the :ref:`typical background style properties ` 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 diff --git a/docs/details/widgets/span.rst b/docs/details/widgets/span.rst deleted file mode 100644 index 45fb5b090..000000000 --- a/docs/details/widgets/span.rst +++ /dev/null @@ -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 -*** diff --git a/docs/details/widgets/spangroup.rst b/docs/details/widgets/spangroup.rst new file mode 100644 index 000000000..cf21bf5c3 --- /dev/null +++ b/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_(&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 `. +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 +*** diff --git a/docs/details/widgets/spinbox.rst b/docs/details/widgets/spinbox.rst index f7a051656..fde43d359 100644 --- a/docs/details/widgets/spinbox.rst +++ b/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 -decreased by *Keys* or API functions. Under the hood the Spinbox is a -modified :ref:`Text area `. +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 `. +Spinbox's parts are identical to those of :ref:`Text Area `. 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 diff --git a/docs/details/widgets/spinner.rst b/docs/details/widgets/spinner.rst index 38640f746..34f7ade20 100644 --- a/docs/details/widgets/spinner.rst +++ b/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_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 diff --git a/docs/details/widgets/switch.rst b/docs/details/widgets/switch.rst index 032e6341c..6563e9e53 100644 --- a/docs/details/widgets/switch.rst +++ b/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 -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 `. ``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 `. +- :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 + ` 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 diff --git a/docs/details/widgets/table.rst b/docs/details/widgets/table.rst index f6e8e0556..a008b034f 100644 --- a/docs/details/widgets/table.rst +++ b/docs/details/widgets/table.rst @@ -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 `. +- :cpp:enumerator:`LV_PART_ITEMS` The cells of the Table also use the + :ref:`typical background style properties ` 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