diff --git a/docs/widgets/extra/meter.md b/docs/widgets/extra/meter.md index a0a151e3e..98212569b 100644 --- a/docs/widgets/extra/meter.md +++ b/docs/widgets/extra/meter.md @@ -1 +1,90 @@ +```eval_rst +.. include:: /header.rst +:github_url: |github_link_base|/widgets/extra/meter.md +``` # Meter (lv_meter) + +## Overview +The Meter widget can visualize data in very flexible ways. In can show arcs, needles, ticks lines and labels. + +## Parts and Styles +- `LV_PART_MAIN` The background of the Meter and it uses the typical background properties. +- `LV_PART_TICK` The tick lines a labels using the *line* and *text* style properties. +- `LV_PART_INDICATOR` The needle line or image using the *line* and *img* style properties, plus the background properties to draw a square (or circle) on the pivot of the needles. Padding makes the square larger. +- `LV_PART_ITEMS` The arcs using the *arc* properties. + +## Usage + +### Add a scale + +For first a *Scale* needs to be added to the Meter with `lv_meter_scale_t * scale = lv_meter_add_scale(meter)`. +The Scale has minor and major ticks and labels on the major tick. Later indicators (needles, arcs, tick modifiers) can be added to the meter + +Any number of scaled can be added to Meter. + +The minor tick lines can be configured with: `lv_meter_set_scale_ticks(meter, scale, tick_count, line_width, tick_length, ctick_olor)`. + +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` tells how many minor ticks to skip to draw a major tick. + +Labels are added automatically on major ticks with `label_gap` distance from the ticks with text proportionally to the values of the tick line. + +`lv_meter_set_scale_range(meter, scale, min, max, angle_range, rotation)` sets the value and angle range of the scale. + +### Add indicators + +Indicators needs to be added to a Scale and their value is interpreted in the range of the Scale. + +#### Needle line + +`lv_meter_indicator_t * 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. + +`lv_meter_set_indicator_value(meter, inidicator, value)` sets the value of the indicator. + +#### Needle image + +`lv_meter_indicator_t * indicator = 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--->`. +`pivot_x` and `pivot_y` sets the pivot point of the rotation relative to the top left corner of the image. + +`lv_meter_set_indicator_value(meter, inidicator, value)` sets the value of the indicator. + +#### Arc +`lv_meter_indicator_t * indicator = 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. + +`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. + +#### Scale lines (ticks) +`lv_meter_indicator_t * indicator = lv_meter_add_scale_lines(meter, scale, color_start, color_end, bool local, width_mod)` adds an indicator that modifies the ticks lines. +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. +If `local` is `false` `color_start` and `color_end` is 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. +`width_mod` modifies the width of the tick lines. + +`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. + +## Events +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` is sent for the tick labels to allow overwriting the texts. The following fields of `lv_obj_draw_part_dsc_t` is set: +`clip_area`, `part` (to `LV_PART_TICK`), `id` (the index of the major tick line), `value` (the value of the tick line), `label_dsc`, `text` (value converted to decimal) + +Learn more about [Events](/overview/event). + +## Keys +Keys have effect on the close button and button matrix. You can add them manually to a group if required. + +Learn more about [Keys](/overview/indev). + + +## Example + +```eval_rst + +.. include:: ../../../examples/widgets/meter/index.rst + +``` + +## API + +```eval_rst + +.. doxygenfile:: lv_meter.h + :project: lvgl + +``` diff --git a/examples/widgets/btnmatrix/lv_example_btnmatrix_2.c b/examples/widgets/btnmatrix/lv_example_btnmatrix_2.c index 620156207..3c1102d56 100644 --- a/examples/widgets/btnmatrix/lv_example_btnmatrix_2.c +++ b/examples/widgets/btnmatrix/lv_example_btnmatrix_2.c @@ -12,7 +12,7 @@ static void event_cb(lv_event_t * e) /*Change the draw descriptor the 2nd button*/ if(dsc->id == 1) { dsc->rect_dsc->radius = 0; - if(lv_btnmatrix_get_selected_btn(obj) == dsc->id) dsc->rect_dsc->bg_color = lv_palette_darken(LV_PALETTE_GREY, 3); + if(lv_btnmatrix_get_selected_btn(obj) == dsc->id) dsc->rect_dsc->bg_color = lv_palette_darken(LV_PALETTE_BLUE, 3); else dsc->rect_dsc->bg_color = lv_palette_main(LV_PALETTE_BLUE); dsc->rect_dsc->shadow_width = 6; diff --git a/examples/widgets/meter/index.rst b/examples/widgets/meter/index.rst index ed0f7f5c1..ba06acec4 100644 --- a/examples/widgets/meter/index.rst +++ b/examples/widgets/meter/index.rst @@ -4,7 +4,28 @@ C Simple meter """"""""""""""""""""""" -.. lv_example:: lv_ex_widgets/lv_ex_meter/lv_ex_meter_1 +.. lv_example:: widgets/meter/lv_example_meter_1 + :language: c + + +A meter with multiple arcs +""""""""""""""""""""""""" + +.. lv_example:: widgets/meter/lv_example_meter_2 + :language: c + + + A clock from a meter +""""""""""""""""""""""" + +.. lv_example:: widgets/meter/lv_example_meter_3 + :language: c + + +Pie chart +""""""""""""""""""""""" + +.. lv_example:: widgets/meter/lv_example_meter_4 :language: c MicroPython diff --git a/examples/widgets/meter/lv_example_meter_1.c b/examples/widgets/meter/lv_example_meter_1.c index 9f47538a4..5592d7922 100644 --- a/examples/widgets/meter/lv_example_meter_1.c +++ b/examples/widgets/meter/lv_example_meter_1.c @@ -19,8 +19,8 @@ void lv_example_meter_1(void) /*Add a scale first*/ lv_meter_scale_t * scale = lv_meter_add_scale(meter); - lv_meter_set_scale_ticks(meter, scale, 51, 2, 10, lv_palette_main(LV_PALETTE_GREY)); - lv_meter_set_scale_major_ticks(meter, scale, 10, 4, 15, lv_color_black(), 10); + lv_meter_set_scale_ticks(meter, scale, 41, 2, 10, lv_palette_main(LV_PALETTE_GREY)); + lv_meter_set_scale_major_ticks(meter, scale, 8, 4, 15, lv_color_black(), 10); lv_meter_indicator_t * indic; diff --git a/src/extra/widgets/meter/lv_meter.c b/src/extra/widgets/meter/lv_meter.c index 36dfe7102..e17dc379e 100644 --- a/src/extra/widgets/meter/lv_meter.c +++ b/src/extra/widgets/meter/lv_meter.c @@ -499,7 +499,8 @@ static void draw_ticks_and_labels(lv_obj_t * obj, const lv_area_t * clip_area, c lv_draw_label_dsc_t label_dsc_tmp; lv_memcpy(&label_dsc_tmp, &label_dsc, sizeof(label_dsc_tmp)); - dsc.id = value_of_line; + dsc.id = i / scale->tick_major_nth; + dsc.value = value_of_line; dsc.label_dsc = &label_dsc_tmp; lv_snprintf(dsc.text, sizeof(dsc.text), "%d", value_of_line); lv_event_send(obj, LV_EVENT_DRAW_PART_BEGIN, &dsc); @@ -515,6 +516,7 @@ static void draw_ticks_and_labels(lv_obj_t * obj, const lv_area_t * clip_area, c label_cord.y2 = label_cord.y1 + label_size.y; lv_draw_label(&label_cord, clip_area, &label_dsc, dsc.text, NULL); + lv_event_send(obj, LV_EVENT_DRAW_PART_END, &dsc); #if LV_DRAW_COMPLEX outer_mask_id = lv_draw_mask_add(&outer_mask, NULL);