diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 2b26b2cbf..c2c9e0dad 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -152,7 +152,7 @@ div.body { font-size: 75%; } -/* This replaces a color present in `pygments.css` which is used to highlight recognized +/* This replaces a color present in `pygments.css` which is used to highlight * function names. It is too dark for DARK mode, and nearly black in LIGHT mode so it is * difficult to tell that it is even highlighted. This color override remedies both. */ .highlight .nf { color: #2648ee } /* Name.Function */ diff --git a/docs/details/base-widget/coord.rst b/docs/details/base-widget/coord.rst index f00545ff0..95bd88274 100644 --- a/docs/details/base-widget/coord.rst +++ b/docs/details/base-widget/coord.rst @@ -42,7 +42,7 @@ have a choice of several different types of units you can use. :cpp:expr:`lv_pct(value)` converts ``value`` to a percentage. E.g. :cpp:expr:`lv_obj_set_width(btn, lv_pct(50))`. If you want to avoid the overhead of the call to :cpp:func:`lv_pct`, you can - also use the macro :c:macro:`LV_PCT(x)` to mean the same thing. + also use the macro :cpp:expr:`LV_PCT(x)` to mean the same thing. Note that when you use this feature, your value is *stored as a percent* so that if/when the size of the parent container (or other positioning factor) changes, this style value dynamically @@ -57,7 +57,7 @@ have a choice of several different types of units you can use. :inches: Specify size as 1/160-th portion of an inch as if it were pixels on a 160-DPI display, even though a display may have a different - DPI. Use :cpp:expr:`lv_dpx(n)` or :c:macro:`LV_DPX(n)` to do + DPI. Use :cpp:expr:`lv_dpx(n)` or :cpp:expr:`LV_DPX(n)` to do this. Examples: +----+-----+----------------------------+ @@ -84,11 +84,11 @@ Boxing Model LVGL follows CSS's `border-box `__ model. A Widget's "box" is built from the following parts: -- bounding box: the width/height of the elements. -- border width: the width of the border. -- padding: space between the sides of the Widget and its children. -- margin: space outside of the Widget (considered only by some layouts) -- content: the content area which is the size of the bounding box reduced by the border width and padding. +:bounding box: the width/height of the elements. +:border width: the width of the border. +:padding: space between the sides of the Widget and its children. +:margin: space outside of the Widget (considered only by some layouts) +:content: the content area which is the size of the bounding box reduced by the border width and padding. .. image:: /misc/boxmodel.png :alt: The box models of LVGL: The content area is smaller than the bounding box with the padding and border width @@ -391,6 +391,8 @@ position setting. However, to keep the LVGL API lean, only the most common coordinate setting features have a "simple" version and the more complex features can be used via styles. + + .. _coord_translation: Translation @@ -459,6 +461,8 @@ The translation actually moves the Widget. That means it makes the scrollbars and :c:macro:`LV_SIZE_CONTENT` sized Widgets react to the position change. + + .. _coord_transformation: Transformation diff --git a/docs/details/base-widget/styles/style-properties.rst b/docs/details/base-widget/styles/style-properties.rst index 0b56dd1cd..00c6df4be 100644 --- a/docs/details/base-widget/styles/style-properties.rst +++ b/docs/details/base-widget/styles/style-properties.rst @@ -765,7 +765,7 @@ Properties to describe the outline. It's like a border but drawn outside of the outline_width ~~~~~~~~~~~~~ -Set width of outline in pixels. +Set width of outline in pixels. .. raw:: html @@ -1004,7 +1004,7 @@ Set gap between dashes in pixels. Note that dash works only on horizontal and ve line_rounded ~~~~~~~~~~~~ -Make end points of the lines rounded. `true`: rounded, `false`: perpendicular line ending +Make end points of the lines rounded. `true`: rounded, `false`: perpendicular line ending .. raw:: html @@ -1065,7 +1065,7 @@ Set width (thickness) of arcs in pixels. arc_rounded ~~~~~~~~~~~ -Make end points of arcs rounded. `true`: rounded, `false`: perpendicular line ending +Make end points of arcs rounded. `true`: rounded, `false`: perpendicular line ending .. raw:: html @@ -1154,7 +1154,7 @@ Set opacity of text. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transpar text_font ~~~~~~~~~ -Set font of text (a pointer `lv_font_t *`). +Set font of text (a pointer `lv_font_t *`). .. raw:: html @@ -1327,7 +1327,7 @@ The intensity of mixing of color filter. anim ~~~~ -Animation template for Widget's animation. Should be a pointer to `lv_anim_t`. The animation parameters are widget specific, e.g. animation time could be the E.g. blink time of the cursor on the text area or scroll time of a roller. See Widgets' documentation to learn more. +Animation template for Widget's animation. Should be a pointer to `lv_anim_t`. The animation parameters are widget specific, e.g. animation time could be the E.g. blink time of the cursor on the Text Area or scroll time of a roller. See Widgets' documentation to learn more. .. raw:: html @@ -1341,7 +1341,7 @@ Animation template for Widget's animation. Should be a pointer to `lv_anim_t`. T anim_duration ~~~~~~~~~~~~~ -Animation duration in milliseconds. Its meaning is widget specific. E.g. blink time of the cursor on the text area or scroll time of a roller. See Widgets' documentation to learn more. +Animation duration in milliseconds. Its meaning is widget specific. E.g. blink time of the cursor on the Text Area or scroll time of a roller. See Widgets' documentation to learn more. .. raw:: html diff --git a/docs/details/debugging/log.rst b/docs/details/debugging/log.rst index 06535666b..8a01230c0 100644 --- a/docs/details/debugging/log.rst +++ b/docs/details/debugging/log.rst @@ -7,7 +7,8 @@ Logging LVGL has a built-in *Log* module to inform the user about what is happening in the library. -Log level + +Log Level ********* To enable logging, set :c:macro:`LV_USE_LOG` in ``lv_conf.h`` and set @@ -24,7 +25,7 @@ The events which have a higher level than the set log level will be logged as well. E.g. if you :c:macro:`LV_LOG_LEVEL_WARN`, errors will be also logged. -Printing logs +Printing Logs ************* Logging with printf @@ -53,14 +54,15 @@ For example: lv_log_register_print_cb(my_log_cb); -Add logs + +Add Logs ******** You can also use the log module via the ``LV_LOG_TRACE/INFO/WARN/ERROR/USER(text)`` or ``LV_LOG(text)`` functions. Here: -- ``LV_LOG_TRACE/INFO/WARN/ERROR/USER(text)`` append following information to your ``text`` +- ``LV_LOG_TRACE/INFO/WARN/ERROR/USER(text)`` append the following information to your ``text`` - Log Level - \__FILE\_\_ - \__LINE\_\_ diff --git a/docs/details/integration/driver/windows.rst b/docs/details/integration/driver/windows.rst index bc8902c55..33151f7c0 100644 --- a/docs/details/integration/driver/windows.rst +++ b/docs/details/integration/driver/windows.rst @@ -3,13 +3,13 @@ Windows Display/Inputs driver ============================= Overview --------- +******** The **Windows** display/input `driver `__ offers support for simulating the LVGL display and keyboard/mouse inputs in a Windows Win32 window. The main purpose for this driver is for testing/debugging the LVGL application in a **Windows** simulation window via **simulator mode**, or developing a standard **Windows** desktop application with LVGL via **application mode**. -Here are the **similarity** for simulator mode and application mode. +These are the **similarities** between simulator mode and application mode. - Support LVGL pointer, keypad and encoder devices integration. - Support Windows touch input. @@ -17,35 +17,38 @@ Here are the **similarity** for simulator mode and application mode. - Support Per-monitor DPI Aware (both V1 and V2). - Provide HWND-based interoperability for other Windows UI infrastructures. -Here are the **differences** for simulator mode and application mode. +These are the **differences** between simulator mode and application mode. Simulator Mode -^^^^^^^^^^^^^^ +-------------- -- Designed for LVGL simulation scenario. -- Keep the LVGL display resolution all time for trying best to simulate UI layout which will see in their production devices. -- When Windows DPI scaling setting is changed, Windows backend will stretch the display content. +- Designed for LVGL device-simulation scenario --- simulates LVGL rendering to a hardware display panel. +- Keeps LVGL display resolution constant in order to best simulate UI layout which will will be seen in production devices. +- When Windows DPI scaling setting is changed, Windows backend will stretch display content. Application Mode -^^^^^^^^^^^^^^^^ +---------------- -- Designed for Windows desktop application development scenario. -- Have the Window resizing support and LVGL display resolution will be changed. -- When Windows DPI scaling setting is changed, the LVGL display DPI value will also be changed. +- Designed for Windows desktop application-development scenario. +- Has Window resizing support and LVGL display resolution is changed dynamically. +- When Windows DPI scaling setting is changed, LVGL display DPI value is also changed. - The resolution you set for lv_windows_create_display is the window size instead of window client size for following the convention of other Windows desktop UI infrastructures. - The applications based on this mode should adapt the LVGL display resolution changing for supporting window resizing properly. Prerequisites -------------- +************* The minimum Windows OS requirement for this driver is Windows Vista RTM. -If you use Windows API shim libraries like `YY-Thunks `__, the tested minimum Windows OS requirement for this driver is Windows XP RTM. +If you use Windows API shim libraries like `YY-Thunks +`__, the tested minimum Windows OS +requirement for this driver is Windows XP RTM. -According to the Windows GDI API this driver used. Maybe the minimum Windows OS requirement limitation for this driver is Windows 2000 RTM. +According to the Windows GDI API this driver used, it is possible the minimum Windows OS +requirement limitation for this driver is Windows 2000 RTM. -Configure Windows driver ------------------------- +Configure Windows Driver +************************ Enable the Windows driver support in lv_conf.h, by cmake compiler define or by KConfig @@ -54,7 +57,7 @@ Enable the Windows driver support in lv_conf.h, by cmake compiler define or by K #define LV_USE_WINDOWS 1 Usage ------ +***** .. code-block:: c diff --git a/docs/details/main-components/display.rst b/docs/details/main-components/display.rst index 4b64fb26f..c2040ad04 100644 --- a/docs/details/main-components/display.rst +++ b/docs/details/main-components/display.rst @@ -157,7 +157,7 @@ If you added ``user_data`` to the Display, you can retrieve it in an event like .. code-block:: c - lv_display_t *display1; + lv_display_t *display1; my_type_t *my_user_data; display1 = (lv_display_t *)lv_event_get_current_target(e); my_user_data = lv_display_get_user_data(display1); @@ -383,17 +383,14 @@ Rotation LVGL supports rotation of the display in 90 degree increments. - The orientation of the display can be changed with -``lv_display_set_rotation(disp, LV_DISPLAY_ROTATION_0/90/180/270)``. -LVGL will swap the horizontal and vertical resolutions internally -according to the set degree, however will not perform the actual rotation. - -When changing the rotation :cpp:enumerator:`LV_EVENT_SIZE_CHANGED` event is -emitted (for any part of your system that has "subscribed" to this event) to -allow reconfiguring of the hardware. In lack of hardware display rotation support -:cpp:func:`lv_draw_sw_rotate` can be used to rotate the buffer in the -:ref:`flush_callback`. +:cpp:expr:`lv_display_set_rotation(disp, LV_DISPLAY_ROTATION_xxx)` where ``xxx`` is +0, 90, 180 or 270. This will swap the horizontal and vertical resolutions internally +according to the set degree, however it will not perform the actual rotation. +When changing the rotation, the :cpp:enumerator:`LV_EVENT_SIZE_CHANGED` event is +emitted to allow for hardware reconfiguration. If your display panel and/or its +driver chip(s) do not support rotation, :cpp:func:`lv_draw_sw_rotate` can be used to +rotate the buffer in the :ref:`flush_callback` function. :cpp:expr:`lv_display_rotate_area(display, &area)` rotates the rendered area according to the current rotation settings of the display. @@ -411,6 +408,7 @@ Below is an example for rotating when the rendering mode is **display controller**. .. code-block:: c + /*Rotate a partially rendered area to another buffer and send it*/ void flush_cb(lv_display_t * disp, const lv_area_t * area, uint8_t * px_map) { @@ -443,6 +441,7 @@ Below is an example for rotating when the rendering mode is into a **frame buffer of the LCD peripheral**. .. code-block:: c + /*Rotate a partially rendered area to the frame buffer*/ void flush_cb(lv_display_t * disp, const lv_area_t * area, uint8_t * px_map) { @@ -741,11 +740,14 @@ You can manually trigger an activity using :cpp:expr:`lv_display_trigger_activity(display1)`. If ``display1`` is ``NULL``, the :ref:`default_display` will be used (**not all displays**). + .. admonition:: Further Reading - `lv_port_disp_template.c `__ for a template for your own driver. - :ref:`Drawing ` to learn more about how rendering works in LVGL. + + API *** diff --git a/docs/details/main-components/font.rst b/docs/details/main-components/font.rst index 60272690a..b13a25835 100644 --- a/docs/details/main-components/font.rst +++ b/docs/details/main-components/font.rst @@ -171,7 +171,7 @@ bidirectional, BiDi) text rendering as well. Some examples: BiDi support is enabled by :c:macro:`LV_USE_BIDI` in *lv_conf.h* -All texts have a base direction (LTR or RTL) which determines some +All text has a base direction (LTR or RTL) which determines some rendering rules and the default alignment of the text (Left or Right). However, in LVGL, the base direction is not only applied to labels. It's a general property which can be set for every Widget. If not set then it @@ -197,7 +197,7 @@ This list summarizes the effect of RTL base direction on Widgets: - ``lv_buttonmatrix``: Shows buttons from right to left - ``lv_list``: Shows icons on the right - ``lv_dropdown``: Aligns options to the right -- The texts in ``lv_table``, ``lv_buttonmatrix``, ``lv_keyboard``, ``lv_tabview``, ``lv_dropdown``, ``lv_roller`` are "BiDi processed" to be displayed correctly +- The text strings in ``lv_table``, ``lv_buttonmatrix``, ``lv_keyboard``, ``lv_tabview``, ``lv_dropdown``, ``lv_roller`` are "BiDi processed" to be displayed correctly Arabic and Persian support -------------------------- @@ -213,7 +213,7 @@ LVGL supports these rules if :c:macro:`LV_USE_ARABIC_PERSIAN_CHARS` is enabled. However, there are some limitations: - Only displaying text is supported (e.g. on labels), text inputs (e.g. text area) don't support this feature. -- Static text (i.e. const) is not processed. E.g. texts set by :cpp:func:`lv_label_set_text` will be "Arabic processed" but :cpp:func:`lv_label_set_text_static` won't. +- Static text (i.e. const) is not processed. E.g. text set by :cpp:func:`lv_label_set_text` will be "Arabic processed" but :cpp:func:`lv_label_set_text_static` won't. - Text get functions (e.g. :cpp:func:`lv_label_get_text`) will return the processed text. .. _fonts_compressed: diff --git a/docs/details/widgets/animimg.rst b/docs/details/widgets/animimg.rst index 26ed0fed4..d45239718 100644 --- a/docs/details/widgets/animimg.rst +++ b/docs/details/widgets/animimg.rst @@ -18,8 +18,8 @@ You can specify a duration and repeat count. 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 +- :cpp:enumerator:`LV_PART_MAIN` A background rectangle that uses the :ref:`typical + background style properties ` and the image itself using the image style properties. .. _lv_animimg_usage: diff --git a/docs/details/widgets/arc.rst b/docs/details/widgets/arc.rst index b7905ed94..b20f3fe71 100644 --- a/docs/details/widgets/arc.rst +++ b/docs/details/widgets/arc.rst @@ -17,11 +17,11 @@ Parts and Styles **************** - :cpp:enumerator:`LV_PART_MAIN` Draws a background using the typical background - style properties and an arc using the arc style properties. The arc's + style properties and an arc using the Arc style properties. The Arc's size and position will respect the *padding* style properties. -- :cpp:enumerator:`LV_PART_INDICATOR` Draws another arc using the *arc* style +- :cpp:enumerator:`LV_PART_INDICATOR` Draws another Arc using the *Arc* style properties. Its padding values are interpreted relative to the - background arc. + background Arc. - :cpp:enumerator:`LV_PART_KNOB` Draws a handle on the end of the indicator using all background properties and padding values. With zero padding the knob size is the same as the indicator's width. Larger padding makes it @@ -41,9 +41,9 @@ value is interpreted in a range (minimum and maximum values) which can be modified with :cpp:expr:`lv_arc_set_range(arc, min, max)`. The default range is 0..100. -The indicator arc is drawn on the main part's arc. This if the value is -set to maximum the indicator arc will cover the entire "background" arc. -To set the start and end angle of the background arc use any of these functions: +The indicator Arc is drawn on the main part's Arc. This if the value is +set to maximum the indicator Arc will cover the entire "background" Arc. +To set the start and end angle of the background Arc use any of these functions: - :cpp:expr:`lv_arc_set_bg_start_angle(arc, angle)` - :cpp:expr:`lv_arc_set_bg_end_angle(arc, angle)` @@ -62,21 +62,21 @@ An offset to the 0-degree position can be added with Mode ---- -The arc can be one of the following modes: +The Arc can be one of the following modes: -- :cpp:enumerator:`LV_ARC_MODE_NORMAL` Indicator arc is drawn clockwise from minimum to current value. -- :cpp:enumerator:`LV_ARC_MODE_REVERSE` Indicator arc is drawn counter-clockwise +- :cpp:enumerator:`LV_ARC_MODE_NORMAL` Indicator Arc is drawn clockwise from minimum to current value. +- :cpp:enumerator:`LV_ARC_MODE_REVERSE` Indicator Arc is drawn counter-clockwise from maximum to current value. -- :cpp:enumerator:`LV_ARC_MODE_SYMMETRICAL` Indicator arc is drawn from middle point to current value. +- :cpp:enumerator:`LV_ARC_MODE_SYMMETRICAL` Indicator Arc is drawn from middle point to current value. The mode can be set by :cpp:expr:`lv_arc_set_mode(arc, LV_ARC_MODE_...)` and -has no effect until angle is set by :cpp:func:`lv_arc_set_value` or value of the arc +has no effect until angle is set by :cpp:func:`lv_arc_set_value` or value of the Arc is changed by pointer input (finger, mouse, etc.). Change rate ----------- -When the arc's value is changed by pointer input (finger, mouse, etc.), the rate of +When the Arc's value is changed by pointer input (finger, mouse, etc.), the rate of its change is limited according to its *change rate*. Change rate is defined in degrees/second units and can be set with :cpp:expr:`lv_arc_set_change_rate(arc, rate)` @@ -85,7 +85,7 @@ Knob offset ----------- Changing the knob offset allows the location of the knob to be moved -relative to the end of the arc. The knob offset can be set by +relative to the end of the Arc. The knob offset can be set by :cpp:expr:`lv_arc_set_knob_offset(arc, offset_angle)`, and will only be visible if :cpp:enumerator:`LV_PART_KNOB` is visible. @@ -104,7 +104,7 @@ In other words, the angle and value settings are independent. You should exclusively use one or the other of the two methods. Mixing the two could result in unintended behavior. -To make the arc non-adjustable by external input, remove the style of the knob and +To make the arc non-adjustable, remove the style of the knob and make the Widget non-clickable: .. code-block:: c @@ -116,30 +116,30 @@ Interactive area ---------------- By default :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is disabled which -means the arc's whole area is interactive. +means the Arc's whole area is interactive. As usual :cpp:func:`lv_obj_set_ext_click_area` can be used to increase -the area that will respond to pointer input (touch, mouse, etc.) outside the arc by a +the area that will respond to pointer input (touch, mouse, etc.) outside the Arc by a specified number of pixels. -If :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is enabled the arc will be sensitive only -in the range between start and end background angles and on the arc itself (not inside the arc). +If :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is enabled the Arc will be sensitive only +in the range between start and end background angles and on the Arc itself (not inside the Arc). In this case ``ext_click_area`` makes the sensitive area ticker both inward and outward. Additionally, a tolerance of :cpp:expr:`lv_dpx(50)` pixels is applied to each angle, extending the -hit-test range along the arc's length. +hit-test range along the Arc's length. Place another Widget on the knob -------------------------------- Another Widget can be positioned according to the current position of -the arc in order to follow the arc's current value (angle). To do this +the Arc in order to follow the Arc's current value (angle). To do this use :cpp:expr:`lv_arc_align_obj_to_angle(arc, widget_to_align, radius_offset)`. Similarly :cpp:expr:`lv_arc_rotate_obj_to_angle(arc, widget_to_rotate, radius_offset)` can be -used to rotate the Widget to the current value of the arc. +used to rotate the Widget to the current value of the Arc. A typical use case is to call these functions in the ``VALUE_CHANGED`` -event of the arc. +event of the Arc. .. _lv_arc_events: @@ -147,30 +147,8 @@ event of the arc. Events ****** -- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when arc is pressed/dragged to +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when Arc is pressed/dragged to a new value. -- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent - with the following types: - - - :cpp:enumerator:`LV_ARC_DRAW_PART_BACKGROUND` The background arc. - - - ``part``: :cpp:enumerator:`LV_PART_MAIN` - - ``p1``: center of arc - - ``radius``: radius of arc - - ``arc_dsc`` - - - :cpp:enumerator:`LV_ARC_DRAW_PART_FOREGROUND` The foreground arc. - - - ``part``: :cpp:enumerator:`LV_PART_INDICATOR` - - ``p1``: center of arc - - ``radius``: radius of arc - - ``arc_dsc`` - - - LV_ARC_DRAW_PART_KNOB The knob - - - ``part``: :cpp:enumerator:`LV_PART_KNOB` - - ``draw_area``: the area of the knob - - ``rect_dsc``: .. admonition:: Further Reading diff --git a/docs/details/widgets/bar.rst b/docs/details/widgets/bar.rst index 92c67cf08..215d9b2c6 100644 --- a/docs/details/widgets/bar.rst +++ b/docs/details/widgets/bar.rst @@ -8,10 +8,10 @@ Bar (lv_bar) Overview ******** -The bar Widget has a background and an indicator. The length of the -indicator against the background indicates the bar's current value. +The Bar Widget has a background and an indicator. The length of the +indicator against the background indicates the Bar's current value. -Both the start and end values of the bar can be set. Changing the start value to a +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. @@ -21,12 +21,12 @@ value other than the minimum value in its range changes the start position of th Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` The bar's background. It uses the typical - background style properties. Adding padding makes the indicator +- :cpp:enumerator:`LV_PART_MAIN` The Bar's background. It uses the :ref:`typical + background style properties `. Adding padding makes the indicator smaller or larger. The ``anim_time`` style property sets the animation time if the values set with :cpp:enumerator:`LV_ANIM_ON`. -- :cpp:enumerator:`LV_PART_INDICATOR` The bar's indicator; also uses all the typical - background properties. +- :cpp:enumerator:`LV_PART_INDICATOR` The Bar's indicator; also uses the :ref:`typical + background style properties `. .. _lv_bar_usage: @@ -37,7 +37,7 @@ Usage Orientation and size -------------------- -- for orientation, width and height, simply set width and height properties; +- for orientation, width and height, simply set width and height style properties; - :cpp:expr:`lv_bar_set_orientation(bar, orientation)` to override orientation caused by ``width`` and ``height``. Valid values for ``orientation`` are: @@ -60,12 +60,13 @@ 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 ----- -The bar can be one of the following modes: +The Bar can be one of the following modes: -- :cpp:enumerator:`LV_BAR_MODE_NORMAL` A normal bar as described above +- :cpp:enumerator:`LV_BAR_MODE_NORMAL` A normal Bar as described above - :cpp:enumerator:`LV_BAR_MODE_SYMMETRICAL` Draws indicator from zero value to current value. Requires a negative minimum value and positive maximum value, e.g. [-100..100]. - :cpp:enumerator:`LV_BAR_MODE_RANGE` Allows setting the start value as well with diff --git a/docs/details/widgets/button.rst b/docs/details/widgets/button.rst index ed6cb6531..92db56026 100644 --- a/docs/details/widgets/button.rst +++ b/docs/details/widgets/button.rst @@ -21,8 +21,8 @@ Buttons, by default, differ from Base Widget in the following ways: Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` The background of the button; uses the typical - background style properties. +- :cpp:enumerator:`LV_PART_MAIN` The background of the button; uses the :ref:`typical + background style properties `. .. _lv_button_usage: diff --git a/docs/details/widgets/calendar.rst b/docs/details/widgets/calendar.rst index cc4f3c1e8..7f849d955 100644 --- a/docs/details/widgets/calendar.rst +++ b/docs/details/widgets/calendar.rst @@ -31,9 +31,11 @@ Parts and Styles The calendar Widget uses the :ref:`Button Matrix ` Widget under the hood to arrange the days into a matrix. -- :cpp:enumerator:`LV_PART_MAIN` Calendar background. Uses all the background-related style properties. -- :cpp:enumerator:`LV_PART_ITEMS` Refers to dates and day names. Button matrix control flags are set to differentiate the - buttons and a custom drawer event is added modify the properties of the buttons as follows: +- :cpp:enumerator:`LV_PART_MAIN` Calendar background. Uses the :ref:`typical + background style properties `. +- :cpp:enumerator:`LV_PART_ITEMS` Refers to dates and day names. Button matrix + control flags are set to differentiate the buttons and a custom drawer event is + added to modify the properties of the buttons as follows: - day names have no border, no background and are drawn with a gray color - days of the previous and next month have the :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_DISABLED` flag diff --git a/docs/details/widgets/canvas.rst b/docs/details/widgets/canvas.rst index 97c7be5c9..eb9f03e44 100644 --- a/docs/details/widgets/canvas.rst +++ b/docs/details/widgets/canvas.rst @@ -18,8 +18,8 @@ LVGL's extensive drawing engine. Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle and image style - properties. +- :cpp:enumerator:`LV_PART_MAIN` Uses the :ref:`typical background ` + and image style properties. .. _lv_canvas_usage: diff --git a/docs/details/widgets/chart.rst b/docs/details/widgets/chart.rst index 88353536c..96d180687 100644 --- a/docs/details/widgets/chart.rst +++ b/docs/details/widgets/chart.rst @@ -112,10 +112,10 @@ oder, from back to front: Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` The background of the chart. Uses all the typical - background and *line* (for division lines) related style - properties. *Padding* makes the series area smaller. For BAR - charts ``pad_column`` sets the space between bars in the same data series. +- :cpp:enumerator:`LV_PART_MAIN` The background of the chart. Uses the :ref:`typical + background ` and line style properties (for division lines). + *Padding* makes the series area smaller. For BAR charts ``pad_column`` sets the + space between bars in the same data series. - :cpp:enumerator:`LV_PART_SCROLLBAR` A scrollbar used if the chart is zoomed. See :ref:`base_widget`'s documentation for details. - :cpp:enumerator:`LV_PART_ITEMS` Refers to the LINE or BAR data series. @@ -220,7 +220,7 @@ Modifying data You have several options to set the Y-values for a data series: 1. Set the values programmatically in the array like ``ser1->points[3] = 7`` and refresh the - chart with :cpp:enumerator:`lv_chart_refresh(chart)`. + chart with :cpp:expr:`lv_chart_refresh(chart)`. 2. Use :cpp:expr:`lv_chart_set_value_by_id(chart, series, id, value)` where ``id`` is the zero-based index of the point you wish to update. 3. Use :cpp:expr:`lv_chart_set_next_value(chart, series, value)`. diff --git a/docs/details/widgets/checkbox.rst b/docs/details/widgets/checkbox.rst index 5098726ff..4571cecf8 100644 --- a/docs/details/widgets/checkbox.rst +++ b/docs/details/widgets/checkbox.rst @@ -17,12 +17,12 @@ Parts and Styles **************** - :cpp:enumerator:`LV_PART_MAIN` Background of Checkbox and it uses - the text- and all the typical background-style properties. + the text and the :ref:`typical background style properties `. ``pad_column`` adjusts spacing between tickbox and label -- :cpp:enumerator:`LV_PART_INDICATOR` The "tick box" is a square that uses all the - typical background style properties. By default, its size is equal to - the height of the main part's font. Padding properties make the tick - box larger in the respective directions. +- :cpp:enumerator:`LV_PART_INDICATOR` The "tick box" is a square that uses the + :ref:`typical background style properties `. By default, its + size is equal to the height of the main part's font. Padding properties make the + tick box larger in the respective directions. The Checkbox is added to the default group (if one is set). diff --git a/docs/details/widgets/dropdown.rst b/docs/details/widgets/dropdown.rst index b41d0a21a..9e22874d2 100644 --- a/docs/details/widgets/dropdown.rst +++ b/docs/details/widgets/dropdown.rst @@ -30,8 +30,8 @@ The Drop-Down List Widget is built from the elements: "button" and "list" Button ------ -- :cpp:enumerator:`LV_PART_MAIN` Background of button, uses the typical - background- and text-properties for its text. +- :cpp:enumerator:`LV_PART_MAIN` Background of button, uses the :ref:`typical + background ` and text style properties for its text. - :cpp:enumerator:`LV_PART_INDICATOR` Typically an arrow symbol that can be an Image or text (e.g. :cpp:enumerator:`LV_SYMBOL`). @@ -40,14 +40,15 @@ The button goes to :cpp:enumerator:`LV_STATE_CHECKED` when it's opened. List ---- -- :cpp:enumerator:`LV_PART_MAIN` The list itself; uses the typical background - properties. ``max_height`` can be used to limit the height of the - list. +- :cpp:enumerator:`LV_PART_MAIN` The list itself; uses the :ref:`typical background + style properties `. ``max_height`` can be used to limit the + height of the list. - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar background, border, shadow properties and width (for its own width) and right padding for the spacing on the right. - :cpp:enumerator:`LV_PART_SELECTED` Refers to the currently pressed, checked or - pressed+checked option. Also uses the typical background properties. + pressed+checked option. Also uses the :ref:`typical background style properties + `. The list is shown/hidden on open/close. To add styles to it use :cpp:expr:`lv_dropdown_get_list(dropdown)` to get the list object. Example: diff --git a/docs/details/widgets/image.rst b/docs/details/widgets/image.rst index a7489e82c..9ede4c37b 100644 --- a/docs/details/widgets/image.rst +++ b/docs/details/widgets/image.rst @@ -18,9 +18,9 @@ can be supported as well. Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` A background rectangle that uses the typical - background style properties, and the image itself uses the image - style properties. +- :cpp:enumerator:`LV_PART_MAIN` A background rectangle that uses the :ref:`typical + background style properties `, and the image itself uses the image + style properties. .. _lv_image_usage: diff --git a/docs/details/widgets/index.rst b/docs/details/widgets/index.rst index 108a8b23d..2e5880494 100644 --- a/docs/details/widgets/index.rst +++ b/docs/details/widgets/index.rst @@ -30,7 +30,7 @@ Widgets roller scale slider - span + spangroup spinbox spinner switch diff --git a/docs/details/widgets/keyboard.rst b/docs/details/widgets/keyboard.rst index 1c666dc36..4fb5e5ca2 100644 --- a/docs/details/widgets/keyboard.rst +++ b/docs/details/widgets/keyboard.rst @@ -20,8 +20,10 @@ Parts and Styles 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 *text* properties. +- :cpp:enumerator:`LV_PART_MAIN` The main part. Uses the :ref:`typical background + style properties ` +- :cpp:enumerator:`LV_PART_ITEMS` The buttons. Also uses the :ref:`typical background + style properties ` as well as *text* properties. .. _lv_keyboard_usage: @@ -48,7 +50,7 @@ default mode is :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER`. Assign Text Area ---------------- -You can assign a :ref:`Text Area ` Widget to the Keyboard to +You can assign a :ref:`Text area ` to the Keyboard to automatically put the clicked characters there. To assign the Text Area, use :cpp:expr:`lv_keyboard_set_textarea(kb, text_area)`. diff --git a/docs/details/widgets/label.rst b/docs/details/widgets/label.rst index 4a0e6ae6b..4b49f9451 100644 --- a/docs/details/widgets/label.rst +++ b/docs/details/widgets/label.rst @@ -16,7 +16,7 @@ A Label is the Widget used to display text. Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` Uses all the typical background and +- :cpp:enumerator:`LV_PART_MAIN` Uses the :ref:`typical background ` and text properties. Padding values can be used to add space between the text and the edges of the Label's background. - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is @@ -125,7 +125,7 @@ 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 text. The whole mechanism (click and select the text as you drag your -finger/mouse) is implemented in :ref:`Text area ` and +finger/mouse) is implemented in :ref:`lv_textarea` and 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_end(label, end_char_index)`. diff --git a/docs/details/widgets/led.rst b/docs/details/widgets/led.rst index 0acb6ca1b..7d91454c7 100644 --- a/docs/details/widgets/led.rst +++ b/docs/details/widgets/led.rst @@ -15,7 +15,8 @@ adjusted. With lower brightness the color of the LED becomes darker. Parts and Styles **************** -- :cpp:enumerator:`LV_LED_PART_MAIN` uses all the typical background style properties. +- :cpp:enumerator:`LV_LED_PART_MAIN` uses the :ref:`typical background style + properties `. .. _lv_led_usage: diff --git a/docs/details/widgets/line.rst b/docs/details/widgets/line.rst index 8facc3a2d..c31f2845d 100644 --- a/docs/details/widgets/line.rst +++ b/docs/details/widgets/line.rst @@ -15,7 +15,8 @@ points. Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` uses all the typical background properties and line style properties. +- :cpp:enumerator:`LV_PART_MAIN` uses the :ref:`typical background ` + and line style properties. .. _lv_line_usage: diff --git a/docs/details/widgets/list.rst b/docs/details/widgets/list.rst index b009f9149..075b6630c 100644 --- a/docs/details/widgets/list.rst +++ b/docs/details/widgets/list.rst @@ -19,7 +19,8 @@ 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 the + :ref:`typical background style properties `. - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See :ref:`base_widget` documentation for details. diff --git a/docs/details/widgets/msgbox.rst b/docs/details/widgets/msgbox.rst index 60850e5f7..329e66290 100644 --- a/docs/details/widgets/msgbox.rst +++ b/docs/details/widgets/msgbox.rst @@ -5,7 +5,6 @@ Message Box (lv_msgbox) ======================= - Overview ******** @@ -107,8 +106,8 @@ the next call to ``lv_timer_handler`` instead of immediately. Events ****** -No special events are sent by this Widget, though its parts can send events. -See their documentation for details: :ref:`lv_button` and :ref:`lv_label`. +No special events are sent by Message Box Widgets. +See these Widgets' documentation for details: :ref:`lv_button` and :ref:`lv_label`. .. admonition:: Further Reading @@ -123,7 +122,7 @@ See their documentation for details: :ref:`lv_button` and :ref:`lv_label`. Keys **** -No *Keys* are processed by Msgbox Widgets. +No *Keys* are processed by Message Box Widgets. .. admonition:: Further Reading diff --git a/docs/details/widgets/roller.rst b/docs/details/widgets/roller.rst index 69fee3fd5..722e03a7c 100644 --- a/docs/details/widgets/roller.rst +++ b/docs/details/widgets/roller.rst @@ -9,6 +9,10 @@ Overview ******** Roller allows the end user to select an item from a list by scrolling it. +The item in the middle is the selected item and normally stands out from +the other items due to different styles applied to it. + + .. _lv_roller_parts_and_styles: @@ -16,8 +20,8 @@ Roller allows the end user to select an item from a list by scrolling it. Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` The background of the Roller uses the - background- and text-style properties. +- :cpp:enumerator:`LV_PART_MAIN` The background of the roller uses the :ref:`typical + background ` and text style properties. - Style ``text_line_space`` adjusts the space between list items. Use :cpp:func:`lv_obj_set_style_text_line_space` to set this value. @@ -32,6 +36,7 @@ Parts and Styles properties to change the appearance of the text of the selected item. + .. _lv_roller_usage: Usage diff --git a/docs/details/widgets/scale.rst b/docs/details/widgets/scale.rst index 0f05badb6..a79e372fa 100644 --- a/docs/details/widgets/scale.rst +++ b/docs/details/widgets/scale.rst @@ -5,7 +5,6 @@ Scale (lv_scale) ================ - Overview ******** diff --git a/docs/details/widgets/slider.rst b/docs/details/widgets/slider.rst index 6348bac12..4c0e9e209 100644 --- a/docs/details/widgets/slider.rst +++ b/docs/details/widgets/slider.rst @@ -49,7 +49,7 @@ Once a Slider is created, it has: - 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: +To set different values use: - :cpp:expr:`lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)` (animation time is set by the styles' ``anim_time`` property); diff --git a/docs/details/widgets/textarea.rst b/docs/details/widgets/textarea.rst index da74e5588..3c0355935 100644 --- a/docs/details/widgets/textarea.rst +++ b/docs/details/widgets/textarea.rst @@ -181,9 +181,12 @@ per label in RAM by setting that macro to equate to ``0``.) Any part of the text can be selected if enabled with :cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like -when you select text on your PC with your mouse. If you pass ``false`` to this -function to disable text-selection, any text selected at the time of the call will be -de-selected. +when you select text on your PC by clicking and dragging with your mouse or other +pointer input device. If you pass ``false`` to this function to disable text +selection, any text selected time of the call will be de-selected. + +Shift+click and keyboard-only text selection with Shift+Arrow keys is expected to +be added in the future. If you need to programmatically deal with selected text, in addition to the :cpp:expr:`lv_textarea_set_text_selection(textarea, enable)` function, the following diff --git a/examples/widgets/scale/index.rst b/examples/widgets/scale/index.rst index 1deffe5fd..621d7d19e 100644 --- a/examples/widgets/scale/index.rst +++ b/examples/widgets/scale/index.rst @@ -23,7 +23,7 @@ A round scale with section and custom styling :language: c A scale with section and custom styling -""""""""""""""""""""""""""""""""""""""" +--------------------------------------- .. lv_example:: widgets/scale/lv_example_scale_5 :language: c @@ -35,19 +35,19 @@ A round scale with multiple needles, resembling a clock :language: c Customizing scale major tick label color with `LV_EVENT_DRAW_TASK_ADDED` event -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +------------------------------------------------------------------------------ .. lv_example:: widgets/scale/lv_example_scale_7 :language: c A round scale with labels rotated and translated -"""""""""""""""""""""""""""""""""""""""""""""""" +------------------------------------------------ .. lv_example:: widgets/scale/lv_example_scale_8 :language: c A horizontal scale with labels rotated and translated -""""""""""""""""""""""""""""""""""""""""""""""""""""" +----------------------------------------------------- .. lv_example:: widgets/scale/lv_example_scale_9 :language: c diff --git a/scripts/style_api_gen.py b/scripts/style_api_gen.py index ff2cf87bf..a37ea4d27 100755 --- a/scripts/style_api_gen.py +++ b/scripts/style_api_gen.py @@ -221,7 +221,7 @@ props = [ {'section': 'Outline', 'dsc':'Properties to describe the outline. It\'s like a border but drawn outside of the rectangles.' }, {'name': 'OUTLINE_WIDTH', 'style_type': 'num', 'var_type': 'int32_t' , 'default':0, 'inherited': 0, 'layout': 0, 'ext_draw': 1, - 'dsc': "Set width of outline in pixels. "}, + 'dsc': "Set width of outline in pixels."}, {'name': 'OUTLINE_COLOR', 'style_type': 'color', 'var_type': 'lv_color_t' , 'default':'`0x000000`', 'inherited': 0, 'layout': 0, 'ext_draw': 0, 'filtered': 1, @@ -288,7 +288,7 @@ props = [ {'name': 'LINE_ROUNDED', 'style_type': 'num', 'var_type': 'bool' , 'default':0, 'inherited': 0, 'layout': 0, 'ext_draw': 0, - 'dsc': "Make end points of the lines rounded. `true`: rounded, `false`: perpendicular line ending "}, + 'dsc': "Make end points of the lines rounded. `true`: rounded, `false`: perpendicular line ending"}, {'name': 'LINE_COLOR', 'style_type': 'color', 'var_type': 'lv_color_t' , 'default':'`0x000000`', 'inherited': 0, 'layout': 0, 'ext_draw': 0, 'filtered': 1, @@ -305,7 +305,7 @@ props = [ {'name': 'ARC_ROUNDED', 'style_type': 'num', 'var_type': 'bool' , 'default':0, 'inherited': 0, 'layout': 0, 'ext_draw': 0, - 'dsc': "Make end points of arcs rounded. `true`: rounded, `false`: perpendicular line ending "}, + 'dsc': "Make end points of arcs rounded. `true`: rounded, `false`: perpendicular line ending"}, {'name': 'ARC_COLOR', 'style_type': 'color', 'var_type': 'lv_color_t', 'default':'`0x000000`', 'inherited': 0, 'layout': 0, 'ext_draw': 0, 'filtered': 1, @@ -330,7 +330,7 @@ props = [ {'name': 'TEXT_FONT', 'style_type': 'ptr', 'var_type': 'const lv_font_t *', 'default':'`LV_FONT_DEFAULT`', 'inherited': 1, 'layout': 1, 'ext_draw': 0, - 'dsc': "Set font of text (a pointer `lv_font_t *`). "}, + 'dsc': "Set font of text (a pointer `lv_font_t *`)."}, {'name': 'TEXT_LETTER_SPACE', 'style_type': 'num', 'var_type': 'int32_t' , 'default':0, 'inherited': 1, 'layout': 1, 'ext_draw': 0, @@ -379,11 +379,11 @@ props = [ {'name': 'ANIM', 'style_type': 'ptr', 'var_type': 'const lv_anim_t *', 'default':'`NULL`', 'inherited': 0, 'layout': 0, 'ext_draw': 0, - 'dsc': "Animation template for Widget's animation. Should be a pointer to `lv_anim_t`. The animation parameters are widget specific, e.g. animation time could be the E.g. blink time of the cursor on the text area or scroll time of a roller. See Widgets' documentation to learn more."}, + 'dsc': "Animation template for Widget's animation. Should be a pointer to `lv_anim_t`. The animation parameters are widget specific, e.g. animation time could be the E.g. blink time of the cursor on the Text Area or scroll time of a roller. See Widgets' documentation to learn more."}, {'name': 'ANIM_DURATION', 'style_type': 'num', 'var_type': 'uint32_t' , 'default':0, 'inherited': 0, 'layout': 0, 'ext_draw': 0, - 'dsc': "Animation duration in milliseconds. Its meaning is widget specific. E.g. blink time of the cursor on the text area or scroll time of a roller. See Widgets' documentation to learn more."}, + 'dsc': "Animation duration in milliseconds. Its meaning is widget specific. E.g. blink time of the cursor on the Text Area or scroll time of a roller. See Widgets' documentation to learn more."}, {'name': 'TRANSITION', 'style_type': 'ptr', 'var_type': 'const lv_style_transition_dsc_t *' , 'default':'`NULL`', 'inherited': 0, 'layout': 0, 'ext_draw': 0, diff --git a/src/widgets/chart/lv_chart_private.h b/src/widgets/chart/lv_chart_private.h index f22f093a7..7ccda787d 100644 --- a/src/widgets/chart/lv_chart_private.h +++ b/src/widgets/chart/lv_chart_private.h @@ -48,22 +48,22 @@ struct _lv_chart_cursor_t { lv_color_t color; lv_chart_series_t * ser; lv_dir_t dir; - uint32_t pos_set: 1; /**< 1: pos is set; 0: point_id is set*/ + uint32_t pos_set: 1; /**< 1: pos is set; 0: point_id is set */ }; struct _lv_chart_t { lv_obj_t obj; - lv_ll_t series_ll; /**< Linked list for the series (stores lv_chart_series_t)*/ - lv_ll_t cursor_ll; /**< Linked list for the cursors (stores lv_chart_cursor_t)*/ + lv_ll_t series_ll; /**< Linked list for series (stores lv_chart_series_t) */ + lv_ll_t cursor_ll; /**< Linked list for cursors (stores lv_chart_cursor_t) */ int32_t ymin[2]; int32_t ymax[2]; int32_t xmin[2]; int32_t xmax[2]; int32_t pressed_point_id; - uint32_t hdiv_cnt; /**< Number of horizontal division lines*/ - uint32_t vdiv_cnt; /**< Number of vertical division lines*/ - uint32_t point_cnt; /**< Point number in a data line*/ - lv_chart_type_t type : 3; /**< Line or column chart*/ + uint32_t hdiv_cnt; /**< Number of horizontal division lines */ + uint32_t vdiv_cnt; /**< Number of vertical division lines */ + uint32_t point_cnt; /**< Number of points in all series */ + lv_chart_type_t type : 3; /**< Chart type */ lv_chart_update_mode_t update_mode : 2; };