Image Button (lv_imagebutton)

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.

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 be 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:

• 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

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

API