acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
meter.md (5038B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/widgets/extra/meter.md
      4 ```
      5 # Meter (lv_meter)
      6 
      7 ## Overview
      8 The Meter widget can visualize data in very flexible ways. In can show arcs, needles, ticks lines and labels.
      9 
     10 ## Parts and Styles
     11 - `LV_PART_MAIN` The background of the Meter. Uses the typical background properties.
     12 - `LV_PART_TICK` The tick lines a labels using the *line* and *text* style properties.
     13 - `LV_PART_INDICATOR` The needle line or image using the *line* and *img* style properties, as well as the background properties to draw a square (or circle) on the pivot of the needles. Padding makes the square larger.
     14 - `LV_PART_ITEMS` The arcs using the *arc* properties.
     15 
     16 ## Usage
     17 
     18 ### Add a scale
     19 
     20 First a *Scale* needs to be added to the Meter with `lv_meter_scale_t * scale = lv_meter_add_scale(meter)`.
     21 The Scale has minor and major ticks and labels on the major ticks. Later indicators (needles, arcs, tick modifiers) can be added to the meter
     22 
     23 Any number of scales can be added to Meter.
     24 
     25 The minor tick lines can be configured with: `lv_meter_set_scale_ticks(meter, scale, tick_count, line_width, tick_length, ctick_olor)`.
     26 
     27 To add major tick lines use `lv_meter_set_scale_major_ticks(meter, scale, nth_major, tick_width, tick_length, tick_color, label_gap)`. `nth_major` to specify how many minor ticks to skip to draw a major tick.
     28 
     29 Labels are added automatically on major ticks with `label_gap` distance from the ticks with text proportionally to the values of the tick line.
     30 
     31 `lv_meter_set_scale_range(meter, scale, min, max, angle_range, rotation)` sets the value and angle range of the scale.
     32 
     33 ### Add indicators
     34 
     35 Indicators need to be added to a Scale and their value is interpreted in the range of the Scale.
     36 
     37 All the indicator add functions return `lv_meter_indicator_t *`.
     38 
     39 #### Needle line
     40 
     41 `indic = lv_meter_add_needle_line(meter, scale, line_width, line_color, r_mod)` adds a needle line to a Scale. By default, the length of the line is the same as the scale's radius but `r_mod` changes the length.
     42 
     43 `lv_meter_set_indicator_value(meter, indic, value)` sets the value of the indicator.
     44 
     45 #### Needle image
     46 
     47 `indic = lv_meter_add_needle_img(meter, scale, img_src, pivot_x, pivot_y)` sets an image that will be used as a needle. `img_src` should be a needle pointing to the right like this `-O--->`.
     48 `pivot_x` and `pivot_y` sets the pivot point of the rotation relative to the top left corner of the image.
     49 
     50 `lv_meter_set_indicator_value(meter, inidicator, value)` sets the value of the indicator.
     51 
     52 #### Arc
     53 `indic = lv_meter_add_arc(meter, scale, arc_width, arc_color, r_mod)` adds and arc indicator. . By default, the radius of the arc is the same as the scale's radius but `r_mod` changes the radius.
     54 
     55 `lv_meter_set_indicator_start_value(meter, indic, value)` and `lv_meter_set_indicator_end_value(meter, inidicator, value)` sets the value of the indicator.
     56 
     57 #### Scale lines (ticks)
     58 `indic = lv_meter_add_scale_lines(meter, scale, color_start, color_end, local, width_mod)` adds an indicator that modifies the ticks lines.
     59 If `local` is `true` the ticks' color will be faded from `color_start` to `color_end` in the indicator's  start and end value range.
     60 If `local` is `false` `color_start` and `color_end` will be mapped to the start and end value of the scale and only a "slice" of that color gradient will be visible in the indicator's start and end value range.
     61 `width_mod` modifies the width of the tick lines.
     62 
     63 `lv_meter_set_indicator_start_value(meter, inidicator, value)` and `lv_meter_set_indicator_end_value(meter, inidicator, value)` sets the value of the indicator.
     64 
     65 ## Events
     66 - `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` is sent for the following types:
     67     - `LV_METER_DRAW_PART_ARC` The arc indicator
     68        - `part`: `LV_PART_ITEMS`
     69        - `sub_part_ptr`: pointer to the indicator
     70        - `arc_dsc`
     71        - `radius`: radius of the arc
     72        - `p1` center of the arc
     73     - `LV_METER_DRAW_PART_NEEDLE_LINE` The needle lines
     74        - `part`: `LV_PART_ITEMS`
     75        - `p1`, `p2` points of the line
     76        - `line_dsc`
     77        - `sub_part_ptr`: pointer to the indicator
     78     - `LV_METER_DRAW_PART_NEEDLE_IMG`  The needle images
     79        - `part`: `LV_PART_ITEMS`
     80        - `p1`, `p2` points of the line
     81        - `img_dsc`
     82        - `sub_part_ptr`: pointer to the indicator
     83     - `LV_METER_DRAW_PART_TICK` The tick lines and labels
     84        - `part`: `LV_PART_TICKS`
     85        - `value`: the value of the line
     86        - `text`: `value` converted to decimal or `NULL` on minor lines
     87        - `label_dsc`: label draw descriptor or `NULL` on minor lines
     88        - `line_dsc`:
     89        - `id`: the index of the line
     90 
     91 
     92 See the events of the [Base object](/widgets/obj) too.
     93 
     94 Learn more about [Events](/overview/event).
     95 
     96 ## Keys
     97 No keys are handled by the Meter widget.
     98 
     99 Learn more about [Keys](/overview/indev).
    100 
    101 
    102 ## Example
    103 
    104 ```eval_rst
    105 
    106 .. include:: ../../../examples/widgets/meter/index.rst
    107 
    108 ```
    109 
    110 ## API
    111 
    112 ```eval_rst
    113 
    114 .. doxygenfile:: lv_meter.h
    115   :project: lvgl
    116 
    117 ```