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¶

C¶

Simple Image button¶

#include "../../../lv_examples.h"
#if LV_USE_IMGBTN

void lv_ex_imgbtn_1(void)
{
    LV_IMG_DECLARE(imgbtn_green);
    LV_IMG_DECLARE(imgbtn_blue);

    /*Darken the button when pressed*/
    static lv_style_t style;
    lv_style_init(&style);
    lv_style_set_image_recolor_opa(&style, LV_STATE_PRESSED, LV_OPA_30);
    lv_style_set_image_recolor(&style, LV_STATE_PRESSED, LV_COLOR_BLACK);
    lv_style_set_text_color(&style, LV_STATE_DEFAULT, LV_COLOR_WHITE);

    /*Create an Image button*/
    lv_obj_t * imgbtn1 = lv_imgbtn_create(lv_scr_act(), NULL);
    lv_imgbtn_set_src(imgbtn1, LV_BTN_STATE_RELEASED, &imgbtn_green);
    lv_imgbtn_set_src(imgbtn1, LV_BTN_STATE_PRESSED, &imgbtn_green);
    lv_imgbtn_set_src(imgbtn1, LV_BTN_STATE_CHECKED_RELEASED, &imgbtn_blue);
    lv_imgbtn_set_src(imgbtn1, LV_BTN_STATE_CHECKED_PRESSED, &imgbtn_blue);
    lv_imgbtn_set_checkable(imgbtn1, true);
    lv_obj_add_style(imgbtn1, LV_IMGBTN_PART_MAIN, &style);
    lv_obj_align(imgbtn1, NULL, LV_ALIGN_CENTER, 0, -40);

    /*Create a label on the Image button*/
    lv_obj_t * label = lv_label_create(imgbtn1, NULL);
    lv_label_set_text(label, "Button");
}

#endif

MicroPython¶

No examples yet.

API¶

Typedefs

typedef uint8_t lv_imgbtn_part_t¶

Enums

enum [anonymous]¶

Values:

enumerator LV_IMGBTN_PART_MAIN¶

Functions

lv_obj_t *lv_imgbtn_create(lv_obj_t *par, const lv_obj_t *copy)¶

Create a image button objects

Return

pointer to the created image button

Parameters

par: pointer to an object, it will be the parent of the new image button
copy: pointer to a image button object, if not NULL then the new object will be copied from it

void lv_imgbtn_set_src(lv_obj_t *imgbtn, lv_btn_state_t state, const void *src)¶

Set images for a state of the image button

Parameters

imgbtn: pointer to an image button object
state: for which state set the new image (from lv_btn_state_t) `
src: pointer to an image source (a C array or path to a file)

void lv_imgbtn_set_src_tiled(lv_obj_t *imgbtn, lv_btn_state_t state, const void *src_left, const void *src_mid, const void *src_right)¶

Set images for a state of the image button

Parameters

imgbtn: pointer to an image button object
state: for which state set the new image (from lv_btn_state_t) `
src_left: pointer to an image source for the left side of the button (a C array or path to a file)
src_mid: pointer to an image source for the middle of the button (ideally 1px wide) (a C array or path to a file)
src_right: pointer to an image source for the right side of the button (a C array or path to a file)

void lv_imgbtn_set_state(lv_obj_t *imgbtn, lv_btn_state_t state)¶

Set the state of the image button

Parameters

imgbtn: pointer to an image button object
state: the new state of the button (from lv_btn_state_t enum)

void lv_imgbtn_toggle(lv_obj_t *imgbtn)¶

Toggle the state of the image button (ON->OFF, OFF->ON)

Parameters

imgbtn: pointer to a image button object

static inline void lv_imgbtn_set_checkable(lv_obj_t *imgbtn, bool tgl)¶

Enable the toggled states. On release the button will change from/to toggled state.

Parameters

imgbtn: pointer to an image button object
tgl: true: enable toggled states, false: disable

const void *lv_imgbtn_get_src(lv_obj_t *imgbtn, lv_btn_state_t state)¶

Get the images in a given state

Return

pointer to an image source (a C array or path to a file)

Parameters

imgbtn: pointer to an image button object
state: the state where to get the image (from lv_btn_state_t) `

const void *lv_imgbtn_get_src_left(lv_obj_t *imgbtn, lv_btn_state_t state)¶

Get the left image in a given state

Return

pointer to the left image source (a C array or path to a file)

Parameters

imgbtn: pointer to an image button object
state: the state where to get the image (from lv_btn_state_t) `

const void *lv_imgbtn_get_src_middle(lv_obj_t *imgbtn, lv_btn_state_t state)¶

Get the middle image in a given state

Return

pointer to the middle image source (a C array or path to a file)

Parameters

imgbtn: pointer to an image button object
state: the state where to get the image (from lv_btn_state_t) `

const void *lv_imgbtn_get_src_right(lv_obj_t *imgbtn, lv_btn_state_t state)¶

Get the right image in a given state

Return

pointer to the left image source (a C array or path to a file)

Parameters

imgbtn: pointer to an image button object
state: the state where to get the image (from lv_btn_state_t) `

static inline lv_btn_state_t lv_imgbtn_get_state(const lv_obj_t *imgbtn)¶

Get the current state of the image button

Return

the state of the button (from lv_btn_state_t enum)

Parameters

imgbtn: pointer to a image button object

static inline bool lv_imgbtn_get_checkable(const lv_obj_t *imgbtn)¶

Get the toggle enable attribute of the image button

Return

true: toggle enabled, false: disabled

Parameters

imgbtn: pointer to a image button object

struct lv_imgbtn_ext_t¶

Public Members

lv_btn_ext_t btn¶

const void *img_src_mid[_LV_BTN_STATE_LAST]¶

const void *img_src_left[_LV_BTN_STATE_LAST]¶

const void *img_src_right[_LV_BTN_STATE_LAST]¶

lv_img_cf_t act_cf¶

uint8_t tiled¶