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. 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, as well as 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

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 ticks. Later indicators (needles, arcs, tick modifiers) can be added to the meter

Any number of scales 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 to specify 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.

All the indicator add functions return lv_meter_indicator_t *.

Needle line

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, indic, value) sets the value of the indicator.

Needle image

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--->. 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

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.

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.

Scale lines (ticks)

indic = lv_meter_add_scale_lines(meter, scale, color_start, color_end, 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 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. 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.

Keys

No keys are handled by the Meter widget.

Learn more about Keys.

Example

C

Simple meter

#include "../../lv_examples.h"
#if LV_USE_METER && LV_BUILD_EXAMPLES

static lv_obj_t * meter;

static void set_value(void * indic, int32_t v)
{
    lv_meter_set_indicator_value(meter, indic, v);
}

/**
 * A simple meter
 */
void lv_example_meter_1(void)
{
     meter = lv_meter_create(lv_scr_act());
    lv_obj_center(meter);
    lv_obj_set_size(meter, 200, 200);

    /*Add a scale first*/
    lv_meter_scale_t * scale = lv_meter_add_scale(meter);
    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;

    /*Add a blue arc to the start*/
    indic = lv_meter_add_arc(meter, scale, 3, lv_palette_main(LV_PALETTE_BLUE), 0);
    lv_meter_set_indicator_start_value(meter, indic, 0);
    lv_meter_set_indicator_end_value(meter, indic, 20);

    /*Make the tick lines blue at the start of the scale*/
    indic = lv_meter_add_scale_lines(meter, scale, lv_palette_main(LV_PALETTE_BLUE), lv_palette_main(LV_PALETTE_BLUE), false, 0);
    lv_meter_set_indicator_start_value(meter, indic, 0);
    lv_meter_set_indicator_end_value(meter, indic, 20);

    /*Add a red arc to the end*/
    indic = lv_meter_add_arc(meter, scale, 3, lv_palette_main(LV_PALETTE_RED), 0);
    lv_meter_set_indicator_start_value(meter, indic, 80);
    lv_meter_set_indicator_end_value(meter, indic, 100);

    /*Make the tick lines red at the end of the scale*/
    indic = lv_meter_add_scale_lines(meter, scale, lv_palette_main(LV_PALETTE_RED), lv_palette_main(LV_PALETTE_RED), false, 0);
    lv_meter_set_indicator_start_value(meter, indic, 80);
    lv_meter_set_indicator_end_value(meter, indic, 100);

    /*Add a needle line indicator*/
    indic = lv_meter_add_needle_line(meter, scale, 4, lv_palette_main(LV_PALETTE_GREY), -10);

    /*Create an animation to set the value*/
    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_exec_cb(&a, set_value);
    lv_anim_set_var(&a, indic);
    lv_anim_set_values(&a, 0, 100);
    lv_anim_set_time(&a, 2000);
    lv_anim_set_repeat_delay(&a, 100);
    lv_anim_set_playback_time(&a, 500);
    lv_anim_set_playback_delay(&a, 100);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
    lv_anim_start(&a);
}

#endif

A meter with multiple arcs

#include "../../lv_examples.h"
#if LV_USE_METER && LV_BUILD_EXAMPLES

static lv_obj_t * meter;

static void set_value(void * indic, int32_t v)
{
    lv_meter_set_indicator_end_value(meter, indic, v);
}


/**
 * A meter with multiple arcs
 */
void lv_example_meter_2(void)
{
    meter = lv_meter_create(lv_scr_act());
    lv_obj_center(meter);
    lv_obj_set_size(meter, 200, 200);

    /*Remove the circle from the middle*/
    lv_obj_remove_style(meter, NULL, LV_PART_INDICATOR);

    /*Add a scale first*/
    lv_meter_scale_t * scale = lv_meter_add_scale(meter);
    lv_meter_set_scale_ticks(meter, scale, 11, 2, 10, lv_palette_main(LV_PALETTE_GREY));
    lv_meter_set_scale_major_ticks(meter, scale, 1, 2, 30, lv_color_hex3(0xeee), 10);
    lv_meter_set_scale_range(meter, scale, 0, 100, 270, 90);

    /*Add a three arc indicator*/
    lv_meter_indicator_t * indic1 = lv_meter_add_arc(meter, scale, 10, lv_palette_main(LV_PALETTE_RED), 0);
    lv_meter_indicator_t * indic2 = lv_meter_add_arc(meter, scale, 10, lv_palette_main(LV_PALETTE_GREEN), -10);
    lv_meter_indicator_t * indic3 = lv_meter_add_arc(meter, scale, 10, lv_palette_main(LV_PALETTE_BLUE), -20);

    /*Create an animation to set the value*/
    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_exec_cb(&a, set_value);
    lv_anim_set_values(&a, 0, 100);
    lv_anim_set_repeat_delay(&a, 100);
    lv_anim_set_playback_delay(&a, 100);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);

    lv_anim_set_time(&a, 2000);
    lv_anim_set_playback_time(&a, 500);
    lv_anim_set_var(&a, indic1);
    lv_anim_start(&a);

    lv_anim_set_time(&a, 1000);
    lv_anim_set_playback_time(&a, 1000);
    lv_anim_set_var(&a, indic2);
    lv_anim_start(&a);

    lv_anim_set_time(&a, 1000);
    lv_anim_set_playback_time(&a, 2000);
    lv_anim_set_var(&a, indic3);
    lv_anim_start(&a);
}

#endif

A clock from a meter

#include "../../lv_examples.h"
#if LV_USE_METER && LV_BUILD_EXAMPLES

static lv_obj_t * meter;

static void set_value(void * indic, int32_t v)
{
    lv_meter_set_indicator_end_value(meter, indic, v);
}

/**
 * A clock from a meter
 */
void lv_example_meter_3(void)
{
    meter = lv_meter_create(lv_scr_act());
    lv_obj_set_size(meter, 220, 220);
    lv_obj_center(meter);

    /*Create a scale for the minutes*/
    /*61 ticks in a 360 degrees range (the last and the first line overlaps)*/
    lv_meter_scale_t * scale_min = lv_meter_add_scale(meter);
    lv_meter_set_scale_ticks(meter, scale_min, 61, 1, 10, lv_palette_main(LV_PALETTE_GREY));
    lv_meter_set_scale_range(meter, scale_min, 0, 60, 360, 270);

    /*Create an other scale for the hours. It's only visual and contains only major ticks*/
    lv_meter_scale_t * scale_hour = lv_meter_add_scale(meter);
    lv_meter_set_scale_ticks(meter, scale_hour, 12, 0, 0, lv_palette_main(LV_PALETTE_GREY));               /*12 ticks*/
    lv_meter_set_scale_major_ticks(meter, scale_hour, 1, 2, 20, lv_color_black(), 10);    /*Every tick is major*/
    lv_meter_set_scale_range(meter, scale_hour, 1, 12, 330, 300);       /*[1..12] values in an almost full circle*/

    LV_IMG_DECLARE(img_hand)

    /*Add a the hands from images*/
    lv_meter_indicator_t * indic_min = lv_meter_add_needle_img(meter, scale_min, &img_hand, 5, 5);
    lv_meter_indicator_t * indic_hour = lv_meter_add_needle_img(meter, scale_min, &img_hand, 5, 5);

    /*Create an animation to set the value*/
    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_exec_cb(&a, set_value);
    lv_anim_set_values(&a, 0, 60);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
    lv_anim_set_time(&a, 2000);     /*2 sec for 1 turn of the minute hand (1 hour)*/
    lv_anim_set_var(&a, indic_min);
    lv_anim_start(&a);

    lv_anim_set_var(&a, indic_hour);
    lv_anim_set_time(&a, 24000);    /*24 sec for 1 turn of the hour hand*/
    lv_anim_set_values(&a, 0, 60);
    lv_anim_start(&a);
}

#endif

Pie chart

#include "../../lv_examples.h"
#if LV_USE_METER && LV_BUILD_EXAMPLES

/**
 * Create a pie chart
 */
void lv_example_meter_4(void)
{
    lv_obj_t * meter = lv_meter_create(lv_scr_act());

    /*Remove the background and the circle from the middle*/
    lv_obj_remove_style(meter, NULL, LV_PART_MAIN);
    lv_obj_remove_style(meter, NULL, LV_PART_INDICATOR);

    lv_obj_set_size(meter, 200, 200);
    lv_obj_center(meter);

    /*Add a scale first with no ticks.*/
    lv_meter_scale_t * scale = lv_meter_add_scale(meter);
    lv_meter_set_scale_ticks(meter, scale, 0, 0, 0, lv_color_black());
    lv_meter_set_scale_range(meter, scale, 0, 100, 360, 0);

    /*Add a three arc indicator*/
    lv_coord_t indic_w = 100;
    lv_meter_indicator_t * indic1 = lv_meter_add_arc(meter, scale, indic_w,lv_palette_main(LV_PALETTE_ORANGE), 0);
    lv_meter_set_indicator_start_value(meter, indic1, 0);
    lv_meter_set_indicator_end_value(meter, indic1, 40);

    lv_meter_indicator_t * indic2 = lv_meter_add_arc(meter, scale, indic_w, lv_palette_main(LV_PALETTE_YELLOW), 0);
    lv_meter_set_indicator_start_value(meter, indic2, 40);  /*Start from the previous*/
    lv_meter_set_indicator_end_value(meter, indic2, 80);

    lv_meter_indicator_t * indic3 = lv_meter_add_arc(meter, scale, indic_w, lv_palette_main(LV_PALETTE_DEEP_ORANGE), 0);
    lv_meter_set_indicator_start_value(meter, indic3, 80);  /*Start from the previous*/
    lv_meter_set_indicator_end_value(meter, indic3, 100);
}

#endif

MicroPython

No examples yet.

API

Enums

enum lv_meter_indicator_type_t

Values:

enumerator LV_METER_INDICATOR_TYPE_NEEDLE_IMG
enumerator LV_METER_INDICATOR_TYPE_NEEDLE_LINE
enumerator LV_METER_INDICATOR_TYPE_SCALE_LINES
enumerator LV_METER_INDICATOR_TYPE_ARC

Functions

lv_obj_t *lv_meter_create(lv_obj_t *parent)

Create a meter objects

Parameters

parent -- pointer to an object, it will be the parent of the new bar.

Returns

pointer to the created meter

lv_meter_scale_t *lv_meter_add_scale(lv_obj_t *obj)

Add a new scale to the meter.

Note

Indicators can be attached to scales.

Parameters

obj -- pointer to a meter object

Returns

the new scale

void lv_meter_set_scale_ticks(lv_obj_t *obj, lv_meter_scale_t *scale, uint16_t cnt, uint16_t width, uint16_t len, lv_color_t color)

Set the properties of the ticks of a scale

Parameters
  • obj -- pointer to a meter object

  • scale -- pointer to scale (added to meter)

  • cnt -- number of tick lines

  • width -- width of tick lines

  • len -- length of tick lines

  • color -- color of tick lines

void lv_meter_set_scale_major_ticks(lv_obj_t *obj, lv_meter_scale_t *scale, uint16_t nth, uint16_t width, uint16_t len, lv_color_t color, int16_t label_gap)

Make some "normal" ticks major ticks and set their attributes. Texts with the current value are also added to the major ticks.

Parameters
  • obj -- pointer to a meter object

  • scale -- pointer to scale (added to meter)

  • nth -- make every Nth normal tick major tick. (start from the first on the left)

  • width -- width of the major ticks

  • len -- length of the major ticks

  • color -- color of the major ticks

  • label_gap -- gap between the major ticks and the labels

void lv_meter_set_scale_range(lv_obj_t *obj, lv_meter_scale_t *scale, int32_t min, int32_t max, uint32_t angle_range, uint32_t rotation)

Set the value and angular range of a scale.

Parameters
  • obj -- pointer to a meter object

  • scale -- pointer to scale (added to meter)

  • min -- the minimum value

  • max -- the maximal value

  • angle_range -- the angular range of the scale

  • rotation -- the angular offset from the 3 o'clock position (clock-wise)

lv_meter_indicator_t *lv_meter_add_needle_line(lv_obj_t *obj, lv_meter_scale_t *scale, uint16_t width, lv_color_t color, int16_t r_mod)

Add a needle line indicator the scale

Parameters
  • obj -- pointer to a meter object

  • scale -- pointer to scale (added to meter)

  • width -- width of the line

  • color -- color of the line

  • r_mod -- the radius modifier (added to the scale's radius) to get the lines length

Returns

the new indicator

lv_meter_indicator_t *lv_meter_add_needle_img(lv_obj_t *obj, lv_meter_scale_t *scale, const void *src, lv_coord_t pivot_x, lv_coord_t pivot_y)

Add a needle image indicator the scale

Note

the needle image should point to the right, like -O-->

Parameters
  • obj -- pointer to a meter object

  • scale -- pointer to scale (added to meter)

  • src -- the image source of the indicator. path or pointer to lv_img_dsc_t

  • pivot_x -- the X pivot point of the needle

  • pivot_y -- the Y pivot point of the needle

Returns

the new indicator

lv_meter_indicator_t *lv_meter_add_arc(lv_obj_t *obj, lv_meter_scale_t *scale, uint16_t width, lv_color_t color, int16_t r_mod)

Add an arc indicator the scale

Parameters
  • obj -- pointer to a meter object

  • scale -- pointer to scale (added to meter)

  • width -- width of the arc

  • color -- color of the arc

  • r_mod -- the radius modifier (added to the scale's radius) to get the outer radius of the arc

Returns

the new indicator

lv_meter_indicator_t *lv_meter_add_scale_lines(lv_obj_t *obj, lv_meter_scale_t *scale, lv_color_t color_start, lv_color_t color_end, bool local, int16_t width_mod)

Add a scale line indicator the scale. It will modify the ticks.

Parameters
  • obj -- pointer to a meter object

  • scale -- pointer to scale (added to meter)

  • color_start -- the start color

  • color_end -- the end color

  • local -- tell how to map start and end color. true: the indicator's start and end_value; false: the scale's min max value

  • width_mod -- add this the affected tick's width

Returns

the new indicator

void lv_meter_set_indicator_value(lv_obj_t *obj, lv_meter_indicator_t *indic, int32_t value)

Set the value of the indicator. It will set start and and value to the same value

Parameters
  • obj -- pointer to a meter object

  • indic -- pointer to an indicator

  • value -- the new value

void lv_meter_set_indicator_start_value(lv_obj_t *obj, lv_meter_indicator_t *indic, int32_t value)

Set the start value of the indicator.

Parameters
  • obj -- pointer to a meter object

  • indic -- pointer to an indicator

  • value -- the new value

void lv_meter_set_indicator_end_value(lv_obj_t *obj, lv_meter_indicator_t *indic, int32_t value)

Set the start value of the indicator.

Parameters
  • obj -- pointer to a meter object

  • indic -- pointer to an indicator

  • value -- the new value

Variables

const lv_obj_class_t lv_meter_class
struct lv_meter_scale_t

Public Members

lv_color_t tick_color
uint16_t tick_cnt
uint16_t tick_length
uint16_t tick_width
lv_color_t tick_major_color
uint16_t tick_major_nth
uint16_t tick_major_length
uint16_t tick_major_width
int16_t label_gap
int16_t label_color
int32_t min
int32_t max
int16_t r_mod
uint16_t angle_range
int16_t rotation
struct lv_meter_indicator_t

Public Members

lv_meter_scale_t *scale
lv_meter_indicator_type_t type
lv_opa_t opa
int32_t start_value
int32_t end_value
const void *src
lv_point_t pivot
struct lv_meter_indicator_t::[anonymous]::[anonymous] needle_img
uint16_t width
int16_t r_mod
lv_color_t color
struct lv_meter_indicator_t::[anonymous]::[anonymous] needle_line
struct lv_meter_indicator_t::[anonymous]::[anonymous] arc
int16_t width_mod
lv_color_t color_start
lv_color_t color_end
uint8_t local_grad
struct lv_meter_indicator_t::[anonymous]::[anonymous] scale_lines
union lv_meter_indicator_t::[anonymous] type_data
struct lv_meter_t

Public Members

lv_obj_t obj
lv_ll_t scale_ll
lv_ll_t indicator_ll