acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
arc.md (4427B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/widgets/core/arc.md
      4 ```
      5 # Arc (lv_arc)
      6 
      7 ## Overview
      8 
      9 The Arc consists of a background and a foreground arc. The foreground (indicator) can be touch-adjusted.
     10 
     11 ## Parts and Styles
     12 - `LV_PART_MAIN`  Draws a background using the typical background style properties and an arc using the arc style properties. The arc's size and position will respect the *padding* style properties.
     13 - `LV_PART_INDICATOR` Draws another arc using the *arc* style properties. Its padding values are interpreted relative to the background arc.
     14 - `LV_PART_KNOB` Draws a handle on the end of the indicator using all background properties and padding values. With zero padding the knob size is the same as the indicator's width.
     15 Larger padding makes it larger, smaller padding makes it smaller.
     16 
     17 ## Usage
     18 
     19 ### Value and range
     20 
     21 A new value can be set using `lv_arc_set_value(arc, new_value)`.
     22 The value is interpreted in a range (minimum and maximum values) which can be modified with `lv_arc_set_range(arc, min, max)`.
     23 The default range is 0..100.
     24 
     25 The indicator arc is drawn on the main part's arc. This if the value is set to maximum the indicator arc will cover the entire "background" arc.
     26 To set the start and end angle of the background arc use the `lv_arc_set_bg_angles(arc, start_angle, end_angle)` functions or `lv_arc_set_bg_start/end_angle(arc, angle)`.
     27 
     28 Zero degrees is at the middle right (3 o'clock) of the object and the degrees are increasing in clockwise direction.
     29 The angles should be in the [0;360] range.
     30 
     31 ### Rotation
     32 
     33 An offset to the 0 degree position can be added with `lv_arc_set_rotation(arc, deg)`.
     34 
     35 ### Mode
     36 
     37 The arc can be one of the following modes:
     38 - `LV_ARC_MODE_NORMAL` The indicator arc is drawn from the minimum value to the current.
     39 - `LV_ARC_MODE_REVERSE` The indicator arc is drawn counter-clockwise from the maximum value to the current.
     40 - `LV_ARC_MODE_SYMMETRICAL` The indicator arc is drawn from the middle point to the current value.
     41 
     42 The mode can be set by `lv_arc_set_mode(arc, LV_ARC_MODE_...)` and used only if the angle is set by `lv_arc_set_value()` or the arc is adjusted by finger.
     43 
     44 ### Change rate
     45 If the arc is pressed the current value will set with a limited speed according to the set *change rate*.
     46 The change rate is defined in degree/second unit and can be set with `lv_arc_set_change_rage(arc, rate)`
     47 
     48 
     49 ### Setting the indicator manually
     50 It's also possible to set the angles of the indicator arc directly with `lv_arc_set_angles(arc, start_angle, end_angle)` function or `lv_arc_set_start/end_angle(arc, start_angle)`.
     51 In this case the set "value" and "mode" are ignored.
     52 
     53 In other words, the angle and value settings are independent. You should exclusively use one or the other. Mixing the two might result in unintended behavior.
     54 
     55 To make the arc non-adjustable, remove the style of the knob and make the object non-clickable:
     56 ```c
     57 lv_obj_remove_style(arc, NULL, LV_PART_KNOB);
     58 lv_obj_clear_flag(arc, LV_OBJ_FLAG_CLICKABLE);
     59 ```
     60 
     61 ### Advanced hit test
     62 
     63 If the `LV_OBJ_FLAG_ADV_HITTEST` flag is enabled the arc can be clicked through in the middle. Clicks are recognized only on the ring of the background arc. `lv_obj_set_ext_click_size()` makes the sensitive area larger inside and outside with the given number of pixels.
     64 
     65 
     66 
     67 
     68 ## Events
     69 - `LV_EVENT_VALUE_CHANGED` sent when the arc is pressed/dragged to set a new value.
     70 - `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent with the following types:
     71     - `LV_ARC_DRAW_PART_BACKGROUND` The background arc.
     72         - `part`: `LV_PART_MAIN`
     73         - `p1`: center of the arc
     74         - `radius`: radius of the arc
     75         - `arc_dsc`
     76     - `LV_ARC_DRAW_PART_FOREGROUND` The foreground arc.
     77         - `part`: `LV_PART_INDICATOR`
     78         - `p1`: center of the arc
     79         - `radius`: radius of the arc
     80         - `arc_dsc`
     81     - LV_ARC_DRAW_PART_KNOB The knob
     82         - `part`: `LV_PART_KNOB`
     83         - `draw_area`: the area of the knob
     84         - `rect_dsc`:
     85 
     86 See the events of the [Base object](/widgets/obj) too.
     87 
     88 Learn more about [Events](/overview/event).
     89 
     90 ## Keys
     91 - `LV_KEY_RIGHT/UP` Increases the value by one.
     92 - `LV_KEY_LEFT/DOWN` Decreases the value by one.
     93 
     94 
     95 Learn more about [Keys](/overview/indev).
     96 
     97 
     98 ## Example
     99 
    100 ```eval_rst
    101 
    102 .. include:: ../../../examples/widgets/arc/index.rst
    103 
    104 ```
    105 
    106 ## API
    107 
    108 ```eval_rst
    109 
    110 .. doxygenfile:: lv_arc.h
    111   :project: lvgl
    112 
    113 ```