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¶