1.. _lv_arc:
2
3============
4Arc (lv_arc)
5============
6
7
8Overview
9********
10
11The Arc consists of a background and a foreground arc. The foreground
12(indicator) can be touch-adjusted.
13
14.. _lv_arc_parts_and_styles:
15
16Parts and Styles
17****************
18
19-  :cpp:enumerator:`LV_PART_MAIN` Draws a background using the typical background
20   style properties and an arc using the Arc style properties. The Arc's
21   size and position will respect the *padding* style properties.
22-  :cpp:enumerator:`LV_PART_INDICATOR` Draws another Arc using the *Arc* style
23   properties. Its padding values are interpreted relative to the
24   background Arc.
25-  :cpp:enumerator:`LV_PART_KNOB` Draws a handle on the end of the indicator using all
26   background properties and padding values. With zero padding the knob
27   size is the same as the indicator's width. Larger padding makes it
28   larger, smaller padding makes it smaller.
29
30
31.. _lv_arc_usage:
32
33Usage
34*****
35
36Value and range
37---------------
38
39A new value can be set using :cpp:expr:`lv_arc_set_value(arc, new_value)`. The
40value is interpreted in a range (minimum and maximum values) which can
41be modified with :cpp:expr:`lv_arc_set_range(arc, min, max)`. The default range
42is 0..100.
43
44The indicator Arc is drawn on the main part's Arc. This if the value is
45set to maximum the indicator Arc will cover the entire "background" Arc.
46To set the start and end angle of the background Arc use any of these functions:
47
48- :cpp:expr:`lv_arc_set_bg_start_angle(arc, angle)`
49- :cpp:expr:`lv_arc_set_bg_end_angle(arc, angle)`
50- :cpp:expr:`lv_arc_set_bg_angles(arc, start_angle, end_angle)`
51
52Zero degrees is at the middle right (3 o'clock) of the Widget and the
53degrees increasing in the clockwise direction.  The angle values should be in
54the range [0..360].
55
56Rotation
57--------
58
59An offset to the 0-degree position can be added with
60:cpp:expr:`lv_arc_set_rotation(arc, deg)`.
61
62Mode
63----
64
65The Arc can be one of the following modes:
66
67- :cpp:enumerator:`LV_ARC_MODE_NORMAL` Indicator Arc is drawn clockwise from minimum to current value.
68- :cpp:enumerator:`LV_ARC_MODE_REVERSE` Indicator Arc is drawn counter-clockwise
69  from maximum to current value.
70- :cpp:enumerator:`LV_ARC_MODE_SYMMETRICAL` Indicator Arc is drawn from middle point to current value.
71
72The mode can be set by :cpp:expr:`lv_arc_set_mode(arc, LV_ARC_MODE_...)` and
73has no effect until angle is set by :cpp:func:`lv_arc_set_value` or value of the Arc
74is changed by pointer input (finger, mouse, etc.).
75
76Change rate
77-----------
78
79When the Arc's value is changed by pointer input (finger, mouse, etc.), the rate of
80its change is limited according to its *change rate*.  Change rate is defined in
81degrees/second units and can be set with
82:cpp:expr:`lv_arc_set_change_rate(arc, rate)`
83
84Knob offset
85-----------
86
87Changing the knob offset allows the location of the knob to be moved
88relative to the end of the Arc.  The knob offset can be set by
89:cpp:expr:`lv_arc_set_knob_offset(arc, offset_angle)`, and will only be visible if
90:cpp:enumerator:`LV_PART_KNOB` is visible.
91
92Setting indicator programmatically
93----------------------------------
94
95It is possible to set indicator angle directly with any of these functions:
96
97- :cpp:expr:`lv_arc_set_start_angle(arc, start_angle)`
98- :cpp:expr:`lv_arc_set_end_angle(arc, end_angle)`
99- :cpp:expr:`lv_arc_set_angles(arc, start_angle, end_angle)`
100
101When used, "value" and "mode" are ignored.
102
103In other words, the angle and value settings are independent.  You should
104exclusively use one or the other of the two methods.  Mixing the two could
105result in unintended behavior.
106
107To make the arc non-adjustable, remove the style of the knob and
108make the Widget non-clickable:
109
110.. code-block:: c
111
112   lv_obj_remove_style(arc, NULL, LV_PART_KNOB);
113   lv_obj_remove_flag(arc, LV_OBJ_FLAG_CLICKABLE);
114
115Interactive area
116----------------
117
118By default :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is disabled which
119means the Arc's whole area is interactive.
120As usual :cpp:func:`lv_obj_set_ext_click_area` can be used to increase
121the area that will respond to pointer input (touch, mouse, etc.) outside the Arc by a
122specified number of pixels.
123
124If :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is enabled the Arc will be sensitive only
125in the range between start and end background angles and on the Arc itself (not inside the Arc).
126In this case ``ext_click_area`` makes the sensitive area ticker both inward and outward.
127Additionally, a tolerance of :cpp:expr:`lv_dpx(50)` pixels is applied to each angle, extending the
128hit-test range along the Arc's length.
129
130Place another Widget on the knob
131--------------------------------
132
133Another Widget can be positioned according to the current position of
134the Arc in order to follow the Arc's current value (angle). To do this
135use :cpp:expr:`lv_arc_align_obj_to_angle(arc, widget_to_align, radius_offset)`.
136
137Similarly
138:cpp:expr:`lv_arc_rotate_obj_to_angle(arc, widget_to_rotate, radius_offset)` can be
139used to rotate the Widget to the current value of the Arc.
140
141A typical use case is to call these functions in the ``VALUE_CHANGED``
142event of the Arc.
143
144
145.. _lv_arc_events:
146
147Events
148******
149
150-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when Arc is pressed/dragged to
151   a new value.
152
153
154.. admonition::  Further Reading
155
156    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
157
158    Learn more about :ref:`events`.
159
160
161
162.. _lv_arc_keys:
163
164Keys
165****
166
167-  ``LV_KEY_RIGHT/UP`` Increases value by one.
168-  ``LV_KEY_LEFT/DOWN`` Decreases value by one.
169
170.. admonition::  Further Reading
171
172    Learn more about :ref:`indev_keys`.
173
174
175
176.. _lv_arc_example:
177
178Example
179*******
180
181.. include:: ../../examples/widgets/arc/index.rst
182
183
184
185.. _lv_arc_api:
186
187API
188***
189