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 for each state instead of drawing a rectangle. The list of states is covered below.

You can set a left, right and middle image, and the middle image will be repeated to match the width of the Widget.

Parts and Styles

LV_PART_MAIN Refers to the image(s). If background style properties are used, a rectangle will be drawn behind the Image Button.

Usage

Image sources

To set the image in a state, use the lv_imagebutton_set_src(imagebutton, LV_IMAGEBUTTON_STATE_..., src_left, src_mid, src_right).

The image sources work the same as described in the Image Widget except that "Symbols" are not supported by the Image button. Any of the sources can NULL. Typically the middle image should be one of the set image sources.

If only src_mid 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. lv_obj_set_width) and the middle image will be tiled to fill the given size.

The possible states are:

The image sources set for state 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. LV_IMAGEBUTTON_STATE_PRESSED, they will be used instead when the Image Button is in that state.

Setting State Programmatically

Instead of the regular lv_obj_add_state() and lv_obj_remove_state() functions, use lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...) to set the state of Image Buttons.

Events

LV_EVENT_VALUE_CHANGED Sent when Image Button's CHECKED state is toggled. This requires the Image Button's LV_OBJ_FLAG_CHECKABLE flag to be set.

Keys

LV_KEY_RIGHT/UP Go to CHECKED state if LV_OBJ_FLAG_CHECKABLE is enabled.
LV_KEY_LEFT/DOWN Go to un-CHECKED state if LV_OBJ_FLAG_CHECKABLE is enabled.
LV_KEY_ENTER Clicks the Image Button

Example

Simple Image button

#include "../../lv_examples.h"
#if LV_USE_IMAGEBUTTON && LV_BUILD_EXAMPLES

void lv_example_imagebutton_1(void)
{
    LV_IMAGE_DECLARE(imagebutton_left);
    LV_IMAGE_DECLARE(imagebutton_right);
    LV_IMAGE_DECLARE(imagebutton_mid);

    /*Create a transition animation on width transformation and recolor.*/
    static lv_style_prop_t tr_prop[] = {LV_STYLE_TRANSFORM_WIDTH, LV_STYLE_IMAGE_RECOLOR_OPA, 0};
    static lv_style_transition_dsc_t tr;
    lv_style_transition_dsc_init(&tr, tr_prop, lv_anim_path_linear, 200, 0, NULL);

    static lv_style_t style_def;
    lv_style_init(&style_def);
    lv_style_set_text_color(&style_def, lv_color_white());
    lv_style_set_transition(&style_def, &tr);

    /*Darken the button when pressed and make it wider*/
    static lv_style_t style_pr;
    lv_style_init(&style_pr);
    lv_style_set_image_recolor_opa(&style_pr, LV_OPA_30);
    lv_style_set_image_recolor(&style_pr, lv_color_black());
    lv_style_set_transform_width(&style_pr, 20);

    /*Create an image button*/
    lv_obj_t * imagebutton1 = lv_imagebutton_create(lv_screen_active());
    lv_imagebutton_set_src(imagebutton1, LV_IMAGEBUTTON_STATE_RELEASED, &imagebutton_left, &imagebutton_mid,
                           &imagebutton_right);
    lv_obj_add_style(imagebutton1, &style_def, 0);
    lv_obj_add_style(imagebutton1, &style_pr, LV_STATE_PRESSED);

    lv_obj_set_width(imagebutton1, 100);
    lv_obj_align(imagebutton1, LV_ALIGN_CENTER, 0, 0);

    /*Create a label on the image button*/
    lv_obj_t * label = lv_label_create(imagebutton1);
    lv_label_set_text(label, "Button");
    lv_obj_align(label, LV_ALIGN_CENTER, 0, -4);
}

#endif

API

lv_imagebutton.h

lv_types.h