1.. _lv_bar:
2
3============
4Bar (lv_bar)
5============
6
7
8Overview
9********
10
11The Bar Widget has a background and an indicator. The length of the
12indicator against the background indicates the Bar's current value.
13
14Both the start and end values of the Bar can be set.  Changing the start value to a
15value other than the minimum value in its range changes the start position of the indicator.
16
17
18
19.. _lv_bar_parts_and_styles:
20
21Parts and Styles
22****************
23
24-  :cpp:enumerator:`LV_PART_MAIN` The Bar's background.  It uses the :ref:`typical
25   background style properties <typical bg props>`. Adding padding makes the indicator
26   smaller or larger. The ``anim_time`` style property sets the
27   animation time if the values set with :cpp:enumerator:`LV_ANIM_ON`.
28-  :cpp:enumerator:`LV_PART_INDICATOR` The Bar's indicator; also uses the :ref:`typical
29   background style properties <typical bg props>`.
30
31.. _lv_bar_usage:
32
33Usage
34*****
35
36
37Orientation and size
38--------------------
39
40- for orientation, width and height, simply set width and height style properties;
41- :cpp:expr:`lv_bar_set_orientation(bar, orientation)` to override orientation
42  caused by ``width`` and ``height``.  Valid values for ``orientation`` are:
43
44  - :cpp:enumerator:`LV_BAR_ORIENTATION_AUTO`
45  - :cpp:enumerator:`LV_BAR_ORIENTATION_HORIZONTAL`
46  - :cpp:enumerator:`LV_BAR_ORIENTATION_VERTICAL`
47
48
49Value and range
50---------------
51
52A new value can be set with
53:cpp:expr:`lv_bar_set_value(bar, new_value, LV_ANIM_ON/OFF)`. The value is
54interpreted in a range (minimum and maximum values) which can be
55modified with :cpp:expr:`lv_bar_set_range(bar, min, max)`. The default range is
560..100, and the default drawing direction is from left to right in horizontal mode and
57bottom to top in vertical mode. If the minimum value is greater than the maximum value, like
58100..0, the drawing direction is reversed.
59
60The new value in :cpp:func:`lv_bar_set_value` can be set with or without an
61animation depending on the last parameter (``LV_ANIM_ON/OFF``).
62
63
64Modes
65-----
66
67The Bar can be one of the following modes:
68
69- :cpp:enumerator:`LV_BAR_MODE_NORMAL` A normal Bar as described above
70- :cpp:enumerator:`LV_BAR_MODE_SYMMETRICAL` Draws indicator from zero value to current value. Requires a negative
71  minimum value and positive maximum value, e.g. [-100..100].
72- :cpp:enumerator:`LV_BAR_MODE_RANGE` Allows setting the start value as well with
73  :cpp:expr:`lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start
74  value must be smaller than the end value.
75
76
77
78.. _lv_bar_events:
79
80Events
81******
82
83No special events are sent by Bar Widgets.
84
85.. admonition::  Further Reading
86
87    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
88
89    Learn more about :ref:`events`.
90
91
92
93.. _lv_bar_keys:
94
95Keys
96****
97
98No *Keys* are processed by Bar Widgets.
99
100.. admonition::  Further Reading
101
102    Learn more about :ref:`indev_keys`.
103
104
105
106.. _lv_bar_example:
107
108Example
109*******
110
111.. include:: ../../examples/widgets/bar/index.rst
112
113
114
115.. _lv_bar_api:
116
117API
118***
119