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