diff --git a/docs/details/widgets/canvas.rst b/docs/details/widgets/canvas.rst index eb3deca440..97c7be5c93 100644 --- a/docs/details/widgets/canvas.rst +++ b/docs/details/widgets/canvas.rst @@ -4,20 +4,23 @@ Canvas (lv_canvas) ================== + Overview ******** -A Canvas inherits from :ref:`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 ` 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 ` 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 diff --git a/docs/details/widgets/image.rst b/docs/details/widgets/image.rst index de0faf2ad3..a7489e82ca 100644 --- a/docs/details/widgets/image.rst +++ b/docs/details/widgets/image.rst @@ -7,10 +7,10 @@ Image (lv_image) Overview ******** -Images are the basic Widget to display images from flash (as arrays) or +Images are Widgets that display images from flash (as arrays) or from files. Images can display symbols (``LV_SYMBOL_...``) as well. -Using the :ref:`Image decoder interface ` custom image formats +Using the :ref:`Image decoder interface `, 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 `. +- a :ref:`Symbol ` 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 `__ -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 ` 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 ` 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 `. In +You can also set a symbol as an image source similar to a :ref:`Labels `. 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 ` 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 ` 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 `). 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 `. +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 diff --git a/docs/details/widgets/imagebutton.rst b/docs/details/widgets/imagebutton.rst index c025d09daa..1506506dbb 100644 --- a/docs/details/widgets/imagebutton.rst +++ b/docs/details/widgets/imagebutton.rst @@ -4,24 +4,27 @@ Image Button (lv_imagebutton) ============================= + Overview ******** -The Image button is very similar to the simple 'Button' Widget. The only -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 ` -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 ` +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 diff --git a/docs/details/widgets/keyboard.rst b/docs/details/widgets/keyboard.rst index cc6df35bbb..1c666dc36b 100644 --- a/docs/details/widgets/keyboard.rst +++ b/docs/details/widgets/keyboard.rst @@ -4,22 +4,25 @@ Keyboard (lv_keyboard) ====================== + Overview ******** -The Keyboard Widget is a special :ref:`Button matrix ` -with predefined keymaps and other features to realize a virtual keyboard -to write texts into a :ref:`Text area `. +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 ` 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 ` 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 ` 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 diff --git a/docs/details/widgets/label.rst b/docs/details/widgets/label.rst index 678e54970e..4a0e6ae6b3 100644 --- a/docs/details/widgets/label.rst +++ b/docs/details/widgets/label.rst @@ -4,25 +4,28 @@ Label (lv_label) ================ + Overview ******** -A label is the basic Widget type that is used to display text. +A Label is the Widget used to display text. + .. _lv_label_parts_and_styles: Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` Uses all the typical background properties and the - 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 `. 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 ` 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. diff --git a/docs/details/widgets/led.rst b/docs/details/widgets/led.rst index 91083e5712..0acb6ca1bd 100644 --- a/docs/details/widgets/led.rst +++ b/docs/details/widgets/led.rst @@ -7,8 +7,8 @@ LED (lv_led) Overview ******** -The LEDs are rectangle-like (or circle) Widget whose brightness can be -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: diff --git a/docs/details/widgets/line.rst b/docs/details/widgets/line.rst index 5dd272d4ac..8facc3a2dc 100644 --- a/docs/details/widgets/line.rst +++ b/docs/details/widgets/line.rst @@ -25,22 +25,22 @@ Usage Set points ---------- -The points have to be stored in an :cpp:struct:`lv_point_precise_t` array and passed to +A Line's points have to be stored in an :cpp:struct:`lv_point_precise_t` array and passed to the Widget by the :cpp:expr:`lv_line_set_points(lines, point_array, point_cnt)` function. Their coordinates can either be specified as raw pixel coordinates -(e.g. ``{5, 10}``), or as a percentage of the line's bounding box using -: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 ` are sent by Line Widgets. +Only :ref:`generic events ` are sent by Line Widgets. .. admonition:: Further Reading diff --git a/docs/details/widgets/list.rst b/docs/details/widgets/list.rst index f1f580c6ef..b009f91492 100644 --- a/docs/details/widgets/list.rst +++ b/docs/details/widgets/list.rst @@ -4,11 +4,13 @@ List (lv_list) ============== + Overview ******** -The List is basically a rectangle with vertical layout to which Buttons -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 `\ 's and :ref:`Label `\ 's documentation. +**Buttons and Text** + +- See the :ref:`Button `'s and :ref:`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 diff --git a/docs/details/widgets/lottie.rst b/docs/details/widgets/lottie.rst index 1dbbb72fb7..264d31d50d 100644 --- a/docs/details/widgets/lottie.rst +++ b/docs/details/widgets/lottie.rst @@ -7,15 +7,15 @@ Lottie (lv_lottie) Overview ******** -The Lottie widget is capable of parsing, rasterizing, and playing `Lottie animations `__. +The Lottie Widget is capable of parsing, rasterizing, and playing `Lottie animations `__. 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/ `__ -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 `__ library which is `integrated into LVGL `__. +The Lottie Widget uses the `ThorVG `__ library which is `integrated into LVGL `__. 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