1.. _lv_imagebutton: 2 3============================= 4Image Button (lv_imagebutton) 5============================= 6 7 8Overview 9******** 10 11The Image Button is very similar to the simple 'Button' Widget. The only 12difference is that it displays user-defined images for each state instead 13of drawing a rectangle. The list of states is covered below. 14 15You can set a left, right and middle image, and the middle image will be 16repeated to match the width of the Widget. 17 18 19.. _lv_imagebutton_parts_and_styles: 20 21Parts and Styles 22**************** 23 24- :cpp:enumerator:`LV_PART_MAIN` Refers to the image(s). If background style 25 properties are used, a rectangle will be drawn behind the Image 26 Button. 27 28 29.. _lv_imagebutton_usage: 30 31Usage 32***** 33 34Image sources 35------------- 36 37To set the image in a state, use the 38:cpp:expr:`lv_imagebutton_set_src(imagebutton, LV_IMAGEBUTTON_STATE_..., src_left, src_mid, src_right)`. 39 40The image sources work the same as described in the :ref:`Image Widget <lv_image>` 41except that "Symbols" are not supported by the Image button. Any of the sources can ``NULL``. 42Typically the middle image should be one of the set image sources. 43 44If only ``src_mid`` is specified, the width of the widget will be set automatically to the 45width of the image. However, if all three sources are set, the width needs to be set by the user 46(using e.g. :cpp:expr:`lv_obj_set_width`) and the middle image will be tiled to fill the given size. 47 48The possible states are: 49 50- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_RELEASED` 51- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_PRESSED` 52- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_DISABLED` 53- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_CHECKED_RELEASED` 54- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_CHECKED_PRESSED` 55- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_CHECKED_DISABLED` 56 57The image sources set for state :cpp:enumerator:`LV_IMAGEBUTTON_STATE_RELEASED` are 58used for any state that has not had image sources set for it. If an image sources 59have been set for other states, e.g. :cpp:enumerator:`LV_IMAGEBUTTON_STATE_PRESSED`, 60they will be used instead when the Image Button is in that state. 61 62Setting State Programmatically 63------------------------------ 64 65Instead of the regular :cpp:func:`lv_obj_add_state` and :cpp:func:`lv_obj_remove_state` functions, 66use :cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` to 67set the state of Image Buttons. 68 69 70 71.. _lv_imagebutton_events: 72 73Events 74****** 75 76- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when Image Button's CHECKED state is toggled. 77 This requires the Image Button's :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` flag to be set. 78 79.. admonition:: Further Reading 80 81 Learn more about :ref:`lv_obj_events` emitted by all Widgets. 82 83 Learn more about :ref:`events`. 84 85 86 87.. _lv_imagebutton_keys: 88 89Keys 90**** 91 92- ``LV_KEY_RIGHT/UP`` Go to CHECKED state if :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` 93 is enabled. 94- ``LV_KEY_LEFT/DOWN`` Go to un-CHECKED state if 95 :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` is enabled. 96- :cpp:enumerator:`LV_KEY_ENTER` Clicks the Image Button 97 98.. admonition:: Further Reading 99 100 Learn more about :ref:`indev_keys`. 101 102 103 104.. _lv_imagebutton_example: 105 106Example 107******* 108 109.. include:: ../../examples/widgets/imagebutton/index.rst 110 111 112 113.. _lv_imagebutton_api: 114 115API 116*** 117