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