1.. _lv_switch:
2
3==================
4Switch (lv_switch)
5==================
6
7
8Overview
9********
10
11Switch Widgets look like little sliders and are used to display, and optionally
12modify, a value that can be "on" or "off".
13
14By default, a Switch is oriented horizontally.  It's orientation will be vertical
15if you set ``width`` < ``height``.
16
17
18
19.. _lv_switch_parts_and_styles:
20
21Parts and Styles
22****************
23
24-  :cpp:enumerator:`LV_PART_MAIN` Switch's background; uses the :ref:`typical
25   background style properties <typical bg props>`. ``padding`` makes the indicator smaller
26   in the respective direction.
27-  :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of
28   the Switch; also uses the :ref:`typical background style properties <typical bg props>`.
29-  :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the left or right
30   side of the indicator; also uses the :ref:`typical background style properties
31   <typical bg props>` to modify the knob's appearance. By default, the knob is round
32   (radius-style can modify this) with diameter slightly smaller than the smaller
33   side of the slider.  The knob can be made larger with the ``padding`` values.
34   Padding values can be asymmetric as well.
35
36
37
38.. _lv_switch_usage:
39
40Usage
41*****
42
43Change state
44------------
45
46The Switch uses the standard :cpp:enumerator:`LV_STATE_CHECKED` state.
47
48To get the current state of the Switch (with ``true`` being on), use
49:cpp:expr:`lv_obj_has_state(widget, LV_STATE_CHECKED)`.
50
51Call :cpp:expr:`lv_obj_add_state(widget, LV_STATE_CHECKED)` to turn it on, or
52:cpp:expr:`lv_obj_remove_state(widget, LV_STATE_CHECKED)` to turn it off
53programmatically.
54
55Change orientation
56------------------
57
58With a Switch is created, its default orientation is
59:cpp:enumerator:`LV_SWITCH_ORIENTATION_AUTO`, which causes it to be oriented based
60on ``width`` and ``height``.  You can change this behavior using
61:cpp:expr:`lv_switch_set_orientation(widget, orientation)`.  Possible values for
62``orientation`` are:
63
64- :cpp:enumerator:`LV_SWITCH_ORIENTATION_AUTO`
65- :cpp:enumerator:`LV_SWITCH_ORIENTATION_HORIZONTAL`
66- :cpp:enumerator:`LV_SWITCH_ORIENTATION_VERTICAL`
67
68
69
70.. _lv_switch_events:
71
72Events
73******
74
75-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when Switch changes state.
76
77.. admonition::  Further Reading
78
79    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
80
81    Learn more about :ref:`events`.
82
83
84
85.. _lv_switch_keys:
86
87Keys
88****
89
90-  ``LV_KEY_UP/RIGHT`` Turns Switch ON
91-  ``LV_KEY_DOWN/LEFT`` Turns Switch OFF
92-  :cpp:enumerator:`LV_KEY_ENTER` Toggles the Switch
93
94.. admonition::  Further Reading
95
96    Learn more about :ref:`indev_keys`.
97
98
99
100.. _lv_switch_example:
101
102Example
103*******
104
105.. include:: ../../examples/widgets/switch/index.rst
106
107
108
109.. _lv_switch_api:
110
111API
112***
113