mirror of
https://github.com/lvgl/lvgl.git
synced 2024-11-23 01:33:59 +08:00
feat(docs): batch 5 of proofread/edited docs (#7218)
This commit is contained in:
Victor Wheeler
GitHub
parent
7bccca027a
commit
63a06e86b0
@ -4,20 +4,23 @@
|
||||
Canvas (lv_canvas)
|
||||
==================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
A Canvas inherits from :ref:`Image <lv_image>` where the user can draw
|
||||
anything. Rectangles, texts, images, lines, arcs can be drawn here using
|
||||
lvgl's drawing engine.
|
||||
A Canvas inherits from :ref:`Image <lv_image>` and extends it, enabling the user to draw
|
||||
anything. Rectangles, text, images, lines, arcs, etc. can be drawn here using
|
||||
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
|
||||
style properties.
|
||||
- :cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle and image style
|
||||
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
|
||||
initialized with :cpp:expr:`lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000))`. It
|
||||
sets pixels with *index=3* to red.
|
||||
For indexed color formats (``LV_COLOR_FORMAT_I1/2/4/8``), the palette needs to be
|
||||
populated for all palette indices that will be used using
|
||||
: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
|
||||
:cpp:expr:`lv_canvas_set_px_color(canvas, x, y, color, opa)`. With
|
||||
``LV_COLOR_FORMAT_I1/2/4/8`` the index of the color needs to be passed as
|
||||
color like this ``lv_color_from_int(13);``. It passes index 13 as a color.
|
||||
|
||||
To set an individual pixel's color on the Canvas, use
|
||||
:cpp:expr:`lv_canvas_set_px(canvas, x, y, color, opa)`. With indexed color formats
|
||||
(``LV_COLOR_FORMAT_I1/2/4/8``) pass the color index as the ``color`` argument.
|
||||
|
||||
: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
|
||||
as for the
|
||||
No special events are sent by Canvas Widgets.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -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)`
|
||||
To make the variable visible in the C file, you need to declare it with
|
||||
and set the converted image as the image source with its pointer 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
|
||||
:ref:`File system <overview_file_system>` to learn more. To set an image sourced
|
||||
from a file, use :cpp:expr:`lv_image_set_src(img, "S:folder1/my_img.bin")`.
|
||||
driver with some functions for basic file operations. See
|
||||
:ref:`File system <overview_file_system>` to learn more. Then set the translated
|
||||
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
|
||||
"letters" instead of real images. You can set symbol like
|
||||
specified in the style. It enables the use of light-weight monochrome
|
||||
"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
|
||||
example, to describe what a button does. Therefore, images and labels
|
||||
are somewhat interchangeable, that is the images can display texts by
|
||||
using :c:macro:`LV_SYMBOL_DUMMY` as the prefix of the text. For example,
|
||||
:cpp:expr:`lv_image_set_src(img, LV_SYMBOL_DUMMY, "Some text")`.
|
||||
Images and labels are sometimes used to convey the same thing, such as
|
||||
describing what a button does. In this context, images and labels
|
||||
are somewhat interchangeable: images can display text by
|
||||
using the macro :c:macro:`LV_SYMBOL_DUMMY` (which equates to a 3-byte C string
|
||||
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
|
||||
the pixel's opacity
|
||||
- **Alpha byte**: An alpha channel is added to every pixel that contains
|
||||
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.
|
||||
- **Alpha indexed**: Only alpha values are stored.
|
||||
- **Indexed**: Image has a color palette, and each pixel is an index into that palette.
|
||||
- **Alpha indexed**: The values stored at pixel positions are alpha (opacity) values.
|
||||
|
||||
These options can be selected in the image converter. To learn more
|
||||
about the color formats, read the :ref:`Images <overview_image>` section.
|
||||
These options can be selected in the image converter. Learn more
|
||||
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
|
||||
well. E.g. ``281`` for 10% enlargement.
|
||||
value shrinks it (e.g. ``128`` half size). Fractional scaling works using a value
|
||||
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
|
||||
the scale independently horizontally and vertically (non-uniform scale).
|
||||
:cpp:expr:`lv_image_set_scale_y(img, factor)` can also be used to
|
||||
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
|
||||
degree precision, so for 45.8° set 458.
|
||||
To rotate the image use :cpp:expr:`lv_image_set_rotation(img, angle_x10)`.
|
||||
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)`.
|
||||
``0;0`` is the top left corner.
|
||||
This can be changed with :cpp:expr:`lv_image_set_pivot(img, pivot_x, pivot_y)` where
|
||||
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
|
||||
the transformations are higher quality but slower.
|
||||
:cpp:expr:`lv_image_set_antialias(img, true)`. Enabling anti-aliasing
|
||||
causes the transformations to be of higher quality, but slower.
|
||||
|
||||
The transformations require the whole image to be available. Therefore
|
||||
indexed images (``LV_COLOR_FORMAT_I1/2/4/8_...``), alpha only images cannot be transformed.
|
||||
In other words transformations work only on normal (A)RGB or A8 images stored as
|
||||
C array, or if a custom :ref:`overview_image_decoder`
|
||||
returns the whole image.
|
||||
Transformations require the whole image to be available. Therefore
|
||||
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 a
|
||||
C array, or on images provided by a custom :ref:`overview_image_decoder`
|
||||
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
|
||||
transformation properties coming from styles. (See
|
||||
:ref:`here <style_opacity_blend_modes_transformations>`). The main
|
||||
differences are that pure image widget transformation
|
||||
**IMPORTANT**: The transformation of the image is independent of the transformation
|
||||
properties :ref:`coming from styles <style_opacity_blend_modes_transformations>`.
|
||||
The main differences are that pure Image Widget transformations:
|
||||
|
||||
- doesn't transform the children of the image widget
|
||||
- image is transformed directly without creating an intermediate layer (buffer) to snapshot the widget
|
||||
- do not transform the children of the Image Widget, and
|
||||
- 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`.
|
||||
It means that the widget will be sized automatically according to the image source.
|
||||
By default the image Widget's width and height are :cpp:enumerator:`LV_SIZE_CONTENT`,
|
||||
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
|
||||
how to align the image source inside the widget.
|
||||
If the Widget's width or height is set to a different value, the value of the ``inner_align``
|
||||
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``
|
||||
and :cpp:enumerator:`LV_IMAGE_ALIGN_CENTER` will move the image source up a little bit
|
||||
from the center of the widget.
|
||||
Any ``offset`` value is applied after the image source is aligned. For example setting
|
||||
an offset of ``y=-10`` with ``align`` == :cpp:enumerator:`LV_IMAGE_ALIGN_CENTER` will
|
||||
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_TILE` Tile the image to will the widget area. Offset is applied to shift the tiling.
|
||||
|
||||
The alignment can be set by :cpp:func:`lv_image_set_inner_align`
|
||||
- :cpp:enumerator:`LV_IMAGE_ALIGN_STRETCH` Set X and Y scale to fill the Widget's area
|
||||
- :cpp:enumerator:`LV_IMAGE_ALIGN_TILE` Tile image to fill Widget's area. Offset is applied to shift the tiling.
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
emit LV_EVENT_CLICKED events if desired.
|
||||
without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make an Image Widget
|
||||
detect and emit LV_EVENT_CLICKED events if desired.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -4,24 +4,27 @@
|
||||
Image Button (lv_imagebutton)
|
||||
=============================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
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
|
||||
of drawing a rectangle.
|
||||
The Image Button is very similar to the simple 'Button' Widget. The only
|
||||
difference is that it displays user-defined images for each state instead
|
||||
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
|
||||
button.
|
||||
properties are used, a rectangle will be drawn behind the Image
|
||||
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>`
|
||||
except that "Symbols" are not supported by the Image button. Any of the sources can ``NULL``.
|
||||
The image sources work the same as described in :ref:`Image Widget <lv_image>`
|
||||
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
|
||||
will be used in other states as well. If you set e.g. :cpp:enumerator:`LV_IMAGEBUTTON_STATE_PRESSED`
|
||||
they will be used in pressed state instead of the released images.
|
||||
The image sources set for state :cpp:enumerator:`LV_IMAGEBUTTON_STATE_RELEASED` are
|
||||
used for any state that has not had image sources set for it. If an image sources
|
||||
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
|
||||
used to manually set a state.
|
||||
use :cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` to
|
||||
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
|
||||
|
||||
|
||||
@ -4,22 +4,25 @@
|
||||
Keyboard (lv_keyboard)
|
||||
======================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Keyboard Widget is a special :ref:`Button matrix <lv_buttonmatrix>`
|
||||
with predefined keymaps and other features to realize a virtual keyboard
|
||||
to write texts into a :ref:`Text area <lv_textarea>`.
|
||||
The Keyboard Widget is a special :ref:`lv_buttonmatrix`
|
||||
with predefined keymaps and other features to provide an on-screen virtual keyboard
|
||||
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
|
||||
automatically put the clicked characters there. To assign the text area,
|
||||
use :cpp:expr:`lv_keyboard_set_textarea(kb, ta)`.
|
||||
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,
|
||||
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
|
||||
keyboards, use :cpp:expr:`lv_keyboard_set_popovers(kb, true)`. The default
|
||||
control maps are preconfigured to only show the popovers on keys that
|
||||
produce a symbol and not on e.g. space. If you use a custom keymap, set
|
||||
the :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER` flag for all keys that you want to
|
||||
show a popover.
|
||||
To enable key pop-overs on press, like on common Android and iOS
|
||||
keyboards, use :cpp:expr:`lv_keyboard_set_popovers(kb, true)`. Default
|
||||
control maps are preconfigured to only show the pop-overs on keys that
|
||||
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 each key for which
|
||||
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
|
||||
adjacent to its top boundary so that the popovers can draw over those.
|
||||
Keyboard or ensure that the Keyboard is added *after* any Widgets
|
||||
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
|
||||
selecting additional characters such as accents yet.
|
||||
Pop-overs currently are merely a visual effect and don't allow
|
||||
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
|
||||
creating new maps and ctrls.
|
||||
Button Matrix's :ref:`button map` section for more information about
|
||||
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_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_LEFT` Move the cursor left.
|
||||
- :c:macro:`LV_SYMBOL_RIGHT` Move the cursor right.
|
||||
- :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_BACKSPACE` Delete character to the left.
|
||||
- :c:macro:`LV_SYMBOL_LEFT` Move cursor left.
|
||||
- :c:macro:`LV_SYMBOL_RIGHT` Move cursor right.
|
||||
- :c:macro:`LV_SYMBOL_NEW_LINE` New line.
|
||||
- ``"ABC"`` Load the uppercase map.
|
||||
- ``"abc"`` Load the lower case map.
|
||||
- ``"1#"`` Load the lower case map.
|
||||
- ``"ABC"`` Load upper-case map.
|
||||
- ``"abc"`` Load 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_CANCEL`: The *Close* button is clicked.
|
||||
- :cpp:enumerator:`LV_EVENT_READY`: The *Ok* button was 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
|
||||
with a custom event handler if you wish.
|
||||
changing, sending events to the assigned text area, etc. You can remove it and replace it
|
||||
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
|
||||
select one.
|
||||
- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons,
|
||||
selecting the one navigated to.
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
@ -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
|
||||
text properties. The padding values can be used to add space between
|
||||
the text and the background.
|
||||
- :cpp:enumerator:`LV_PART_MAIN` Uses all the 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
|
||||
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
|
||||
can be used to set the text.
|
||||
With :cpp:expr:`lv_label_set_text_fmt(label, fmt, ...)` printf formatting
|
||||
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
|
||||
the function exits.
|
||||
that the contents of the character buffer *must* remain valid for the life of the
|
||||
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
|
||||
RPM in a dashboard), and the length of those strings changes frequently, it is
|
||||
advisable to:
|
||||
If your Label is updated with new strings rapidly (e.g. > 30X / second, such as
|
||||
RPM in a dashboard, or an ADC value), and the length of those strings changes
|
||||
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
|
||||
:c:macro:`LV_SIZE_CONTENT`. Therefore, the size of the label is automatically
|
||||
expanded to the text size. Otherwise, if the width or height are
|
||||
By default, the width and height of the Label are set to
|
||||
:c:macro:`LV_SIZE_CONTENT`. Thus, the size of the Label is automatically expanded
|
||||
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_SCROLL` If the text is wider than the label scroll it horizontally back and forth. If it's
|
||||
- :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
|
||||
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
|
||||
: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
|
||||
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`,
|
||||
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 text has multiple lines with non equal line length
|
||||
- the Label Widget's width is larger than the width of the longest line of text, and
|
||||
- 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 :ref:`font` section to learn more about the symbols.
|
||||
The Labels can display symbols alongside letters (or on their own). Read
|
||||
the :ref:`font` section to learn more about symbols.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,8 +7,8 @@ LED (lv_led)
|
||||
Overview
|
||||
********
|
||||
|
||||
The LEDs are rectangle-like (or circle) Widget whose brightness can be
|
||||
adjusted. With lower brightness the colors of the LED become darker.
|
||||
LEDs are rectangle-like (or circle) Widgets whose brightness can be
|
||||
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
|
||||
:cpp:expr:`lv_led_set_color(led, lv_color_hex(0xff0080))`. This will be used as
|
||||
You set the color of the LED with
|
||||
: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)`.
|
||||
The brightness should be between 0 (darkest) and 255 (lightest).
|
||||
You can set their brightness with :cpp:expr:`lv_led_set_brightness(led, brightness)`.
|
||||
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:
|
||||
|
||||
@ -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
|
||||
: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
|
||||
values do not automatically expand the bounding box.
|
||||
(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
|
||||
be set explicitly using :cpp:func:`lv_obj_set_width` and :cpp:func:`lv_obj_set_height`,
|
||||
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
|
||||
|
||||
|
||||
@ -4,11 +4,13 @@
|
||||
List (lv_list)
|
||||
==============
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The List is basically a rectangle with vertical layout to which Buttons
|
||||
and Texts can be added
|
||||
The List Widget is basically a rectangle with vertical layout to which Buttons
|
||||
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_SCROLLBAR` The scrollbar. See the :ref:`base_widget`
|
||||
- :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 :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
|
||||
- and a text.
|
||||
The text is scrolled horizontally if it is longer than the button.
|
||||
|
||||
The text starts to scroll horizontally if it's too long.
|
||||
Text
|
||||
----
|
||||
|
||||
Texts
|
||||
-----
|
||||
|
||||
:cpp:expr:`lv_list_add_text(list, text)` adds a text.
|
||||
: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.
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 user needs to provide a buffer where the current frame is stored.
|
||||
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 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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user