lvgl/docs/widgets/imgbtn.md

.. include:: /header.rst 
:github_url: |github_link_base|/widgets/imgbtn.md

Image button (lv_imgbtn)

Overview

The Image button is very similar to the simple 'Button' object. The only difference is that, it displays user-defined images in each state instead of drawing a rectangle. Before reading this section, please read the Button section for better understanding.

Parts and Styles

The Image button object has only a main part called LV_IMG_BTN_PART_MAIN from where all image style properties are used. It's possible to recolor the image in each state with image_recolor and image_recolor_opa proeprties. For example, to make the image darker if it is pressed.

Usage

Image sources

To set the image in a state, use the lv_imgbtn_set_src(imgbtn, LV_BTN_STATE_..., &img_src). The image sources works the same as described in the Image object except that, "Symbols" are not supported by the Image button.

If LV_IMGBTN_TILED is enabled in lv_conf.h, then lv_imgbtn_set_src_tiled(imgbtn, LV_BTN_STATE_..., &img_src_left, &img_src_mid, &img_src_right) becomes available. Using the tiled feature the middle image will be repeated to fill the width of the object. Therefore with LV_IMGBTN_TILED, you can set the width of the Image button using lv_obj_set_width(). However, without this option, the width will be always the same as the image source's width.

Button features

Similarly to normal Buttons lv_imgbtn_set_checkable(imgbtn, true/false), lv_imgbtn_toggle(imgbtn) and lv_imgbtn_set_state(imgbtn, LV_BTN_STATE_...) also works.

Events

Beside the Generic events, the following Special events are sent by the buttons:

• LV_EVENT_VALUE_CHANGED - Sent when the button is toggled.

Note that, the generic input device related events (like LV_EVENT_PRESSED) are sent in the inactive state too. You need to check the state with lv_btn_get_state(btn) to ignore the events from inactive buttons.

Learn more about Events.

Keys

The following Keys are processed by the Buttons:

• LV_KEY_RIGHT/UP - Go to toggled state if toggling is enabled.
• LV_KEY_LEFT/DOWN - Go to non-toggled state if toggling is enabled.

Note that, as usual, the state of LV_KEY_ENTER is translated to LV_EVENT_PRESSED/PRESSING/RELEASED etc.

Learn more about Keys.

Example

.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_imgbtn/index.rst

API

.. doxygenfile:: lv_imgbtn.h
  :project: lvgl