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