Image Button (lv_imagebutton)

Like Button, but draws user-defined images per state instead of a plain rectangle.

Overview

The Image Button behaves like a regular Button, but draws user-defined images for each state instead of a plain rectangle.

You can set a left, middle, and right image. The middle image is tiled to fill the widget's width.

Image sources

To set the images for a state, use 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. Any of the sources can be NULL. If only src_mid is set, the widget width is set automatically to the image width. If all three are set, width must be set explicitly with lv_obj_set_width.

The possible states are:

• LV_IMAGEBUTTON_STATE_RELEASED
• LV_IMAGEBUTTON_STATE_PRESSED
• LV_IMAGEBUTTON_STATE_DISABLED
• LV_IMAGEBUTTON_STATE_CHECKED_RELEASED
• LV_IMAGEBUTTON_STATE_CHECKED_PRESSED
• LV_IMAGEBUTTON_STATE_CHECKED_DISABLED

Images set for LV_IMAGEBUTTON_STATE_RELEASED are used as fallback for any state that has no sources assigned.

Setting state programmatically

Use lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...) instead of the regular lv_obj_add_state / lv_obj_remove_state.

Styling

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

Events

LV_EVENT_VALUE_CHANGED is sent when the CHECKED state is toggled. Requires the LV_OBJ_FLAG_CHECKABLE flag to be set.

Learn more about Events emitted by all Widgets.

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.

Learn more about Keys.