docs/src/widgets/image.rst
.. include:: /include/substitutions.txt .. include:: /include/external_links.txt .. _lv_image:
Overview
Images are Widgets that display images from flash (as arrays) or
from files. Images can also display symbols (LV_SYMBOL_...).
Using the :ref:Image decoder interface <image_decoders>, custom image formats
can be supported as well.
.. _lv_image_parts_and_styles:
Parts and Styles
LV_PART_MAIN A background rectangle that uses the :ref:typical background style properties <typical bg props>, and the image itself uses the image
style properties... _lv_image_usage:
Usage
To provide maximum flexibility, the source of the image can be:
Symbol <font_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 LVGL Online Image Converter_
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 select the binary output
format. You also need to use LVGL's file system module and register a
driver with some functions for basic file operations. See
:ref:File system <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 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 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).
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").
The internal (pixel array) and external images support 2 transparency handling methods:
Besides RGB888 and ARGB8888 color formats, the following formats are supported:
These options can be selected in the LVGL Online Image Converter_. Learn more
about color formats in the :ref:images_color_formats section.
A color can be mixed with every pixel of an image with a given
intensity. This can be useful to show different states (checked,
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 causing this feature to be disabled.
The color to mix is set by img_recolor.
With :cpp:expr:lv_image_set_offset_x(img, x_ofs) and
:cpp:expr:lv_image_set_offset_y(img, y_ofs), you can add some offset to the
displayed image. Useful if the Widget size is smaller than the image
source size. Using the offset parameter a Texture atlas <https://en.wikipedia.org/wiki/Texture_atlas>__
or a "running image" effect can be created by :ref:Animating <animation> the x or y offset.
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 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) 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_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\ |deg|\ .
By default, the pivot point of the rotation is the center of the image.
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). Enabling anti-aliasing
causes the transformations to be of higher quality, but slower.
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:image_decoders
that returns the whole image.
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 :ref:coming from styles <style_opacity_blend_modes_transformations>.
The main differences are that pure Image Widget transformations:
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 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.
align can be any of these values:
LV_IMAGE_ALIGN_DEFAULT: Meaning top leftLV_IMAGE_ALIGN_TOP_LEFTLV_IMAGE_ALIGN_TOP_MIDLV_IMAGE_ALIGN_TOP_RIGHTLV_IMAGE_ALIGN_BOTTOM_LEFTLV_IMAGE_ALIGN_BOTTOM_MIDLV_IMAGE_ALIGN_BOTTOM_RIGHTLV_IMAGE_ALIGN_LEFT_MIDLV_IMAGE_ALIGN_RIGHT_MIDLV_IMAGE_ALIGN_CENTERLV_IMAGE_ALIGN_STRETCHLV_IMAGE_ALIGN_TILELV_IMAGE_ALIGN_CONTAINLV_IMAGE_ALIGN_COVERAny 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.
To automatically scale or tile the image, pass one of these align values:
LV_IMAGE_ALIGN_STRETCH Set X and Y scale to fill the Widget's areaLV_IMAGE_ALIGN_TILE Tile image to fill Widget's area. Offset is applied to shift the tiling.LV_IMAGE_ALIGN_CONTAIN The image keeps its aspect ratio, but is resized to the maximum size that fits within the Widget's area.LV_IMAGE_ALIGN_COVER The image keeps its aspect ratio and fills the Widget's area.To get familiar with observers, subjects, and data bindings in general visit the
:ref:Observer <observer_how_to_use> page.
This method of subscribing to a pointer Subject affects a Image Widget's source (src)
value directly. Note that this is a one-way binding (Subject ==> Widget) so when
the subject changes, the Image will be updated too.
It supports only pointer subjects.
lv_image_bind_src(img, &subject).. _lv_image_events:
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 an Image Widget detect and emit LV_EVENT_CLICKED events if desired.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_image_keys:
Keys
No Keys are processed by Image Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_image_example:
Examples
.. include:: /examples/widgets/image/index.rst
.. _lv_image_api:
API