1.. _lv_slider:
2
3==================
4Slider (lv_slider)
5==================
6
7
8
9Overview
10********
11
12The Slider Widget looks like a :ref:`lv_bar` supplemented with
13a knob. The knob can be dragged to set the Slider's value. Like Bar, a Slider
14can be vertical or horizontal.
15
16
17
18.. _lv_slider_parts_and_styles:
19
20Parts and Styles
21****************
22
23-  :cpp:enumerator:`LV_PART_MAIN` The background of the Slider. Uses the
24   :ref:`typical background style properties <typical bg props>`. ``padding`` makes
25   the indicator smaller in the respective direction.
26-  :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of
27   the Slider; also uses the :ref:`typical background style properties <typical bg props>`.
28-  :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the current value;
29   also uses the :ref:`typical background style properties <typical bg props>` to
30   describe the knob(s).  By default, the knob is round (radius-style can modify this)
31   with side length equal to the smaller dimension of the Slider.  The knob can be
32   made larger with the ``padding`` values.  Padding values can be asymmetric as well.
33
34
35
36.. _lv_slider_usage:
37
38Usage
39*****
40
41Value, range and orientation
42----------------------------
43
44Once a Slider is created, it has:
45
46- value == 0
47- default range of [0..100],
48- horizontal orientation, with
49- default width of approximately 2 inches (according to configured value of :c:macro:`LV_DPI_DEF`),
50- default height of approximately 1/10 inch (according to configured value of :c:macro:`LV_DPI_DEF`).
51
52To set different values use:
53
54- :cpp:expr:`lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)` (animation time
55  is set by the styles' ``anim_time`` property);
56- :cpp:expr:`lv_slider_set_range(slider, min , max)`; and
57- for orientation, width and height, simply set width and height properties;
58- :cpp:expr:`lv_slider_set_orientation(slider, orientation)` to override orientation
59  caused by ``width`` and ``height``.  Valid values for ``orientation`` are:
60
61  - :cpp:enumerator:`LV_SLIDER_ORIENTATION_AUTO`
62  - :cpp:enumerator:`LV_SLIDER_ORIENTATION_HORIZONTAL`
63  - :cpp:enumerator:`LV_SLIDER_ORIENTATION_VERTICAL`
64
65The default drawing direction is from left to right in horizontal orientation and
66bottom to top in vertical orientation.  If the minimum value is set to be greater
67than the maximum value (e.g. [100..0]), the drawing direction is reversed.
68
69Modes
70-----
71
72The Slider can be in one of the following modes:
73
74- :cpp:enumerator:`LV_SLIDER_MODE_NORMAL` A normal Slider as described above (default)
75- :cpp:enumerator:`LV_SLIDER_SYMMETRICAL` Draw the indicator from the zero value to
76  current value. Requires negative minimum range and positive maximum range.
77- :cpp:enumerator:`LV_SLIDER_RANGE` Allows setting the start value as well by
78  :cpp:expr:`lv_bar_set_start_value(slider, new_value, LV_ANIM_ON/OFF)`. The start
79  value must always be smaller than the end value.
80
81The mode can be changed with :cpp:expr:`lv_slider_set_mode(slider, LV_SLIDER_MODE_...)`
82
83Knob-only mode
84--------------
85
86Normally, the Slider can be adjusted either by dragging the knob, or by
87clicking on the Slider bar. In the latter case the knob moves to the
88point clicked and the Slider value changes accordingly. In some cases it is
89desirable to set the Slider to react on dragging the knob only. This
90feature is enabled by adding the :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` flag:
91:cpp:expr:`lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST)`.
92
93Any extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, value)`)
94increases the knob's click area.
95
96
97
98.. _lv_slider_events:
99
100Events
101******
102
103-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent while the Slider is being dragged or
104   changed with keys. The event is sent continuously while the Slider is
105   being dragged.
106-  :cpp:enumerator:`LV_EVENT_RELEASED` Sent once when Slider is released.
107
108.. admonition::  Further Reading
109
110    :ref:`Bar Events <lv_bar_events>`.
111
112    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
113
114    Learn more about :ref:`events`.
115
116
117
118.. _lv_slider_keys:
119
120Keys
121****
122
123-  ``LV_KEY_UP/RIGHT`` Increment Slider's value by 1.
124-  ``LV_KEY_DOWN/LEFT`` Decrement Slider's value by 1.
125
126.. admonition::  Further Reading
127
128    Learn more about :ref:`indev_keys`.
129
130
131
132.. _lv_slider_example:
133
134Example
135*******
136
137.. include:: ../../examples/widgets/slider/index.rst
138
139
140
141.. _lv_slider_api:
142
143API
144***
145