Chart (lv_chart)

Overview

Charts are basic object to visualize data points. It support Line charts (connect points with lines and/or draw points on them) and Column chart.

Chart also support division lines, 2 y axis, axis ticks, and texts on ticks.

Parts and Styles

The Chart's main part is called LV_CHART_PART_BG and it uses all the typical background properties. The text style properties determine the style of the axis texts and the line properties determine ticks' style. Padding values add some space on the sides thus it makes series area smaller. Padding also can be used to make space for axis texts and ticks.

The background of the series is called LV_CHART_PART_SERIES_BG and it's placed on the main background. The division lines, and series data is drawn on this part. Besides the typical background style properties the line style properties are used by the division lines. The padding values tells the space between the this part and the axis texts.

The style of the series can be referenced by LV_CHART_PART_SERIES. In case of column type the following properties are used:

  • radius: radius of the bars

  • padding_inner: space between the columns of the same x coordinate

In case of Line type these properties are used:

  • line properties to describe the lines

  • size radius of the points

  • bg_opa: the overall opacity of the area below the lines

  • bg_main_stop: % of bg_opa at the top to create an alpha fade (0: transparent at the top, 255: bg_opa at the top)

  • bg_grad_stop: % of bg_opa at the bottom to create an alpha fade (0: transparent at the bottom, 255: bg_opa at the top)

  • bg_drag_dir: should be LV_GRAD_DIR_VER to allow alpha fading with bg_main_stop and bg_grad_stop

Usage

Data series

You can add any number of series to the charts by lv_chart_add_series(chart, color). It allocates data for a lv_chart_series_t structure which contains the chosen color and an array for the data points.

Series' type

The following data display types exist:

  • LV_CHART_TYPE_NONE - Do not display any data. It can be used to hide a series.

  • LV_CHART_TYPE_LINE - Draw lines between the points.

  • LV_CHART_TYPE_COLUMN - Draw columns.

You can specify the display type with lv_chart_set_type(chart, LV_CHART_TYPE_...). The types can be 'OR'ed (like LV_CHART_TYPE_LINE).

Modify the data

You have several options to set the data of series:

  1. Set the values manually in the array like ser1->points[3] = 7 and refresh the chart with lv_chart_refresh(chart).

  2. Use the lv_chart_set_next(chart, ser, value).

  3. Initialize all points to a given value with: lv_chart_init_points(chart, ser, value).

  4. Set all points from an array with: lv_chart_set_points(chart, ser, value_array).

Use LV_CHART_POINT_DEF as value to make the library skip drawing that point, column, or line segment.

Update modes

lv_chart_set_next can behave in two ways depending on update mode:

  • LV_CHART_UPDATE_MODE_SHIFT - Shift old data to the left and add the new one o the right.

  • LV_CHART_UPDATE_MODE_CIRCULAR - Circularly add the new data (Like an ECG diagram).

The update mode can be changed with lv_chart_set_update_mode(chart, LV_CHART_UPDATE_MODE_...).

Number of points

The number of points in the series can be modified by lv_chart_set_point_count(chart, point_num). The default value is 10.

Vertical range

You can specify the minimum and maximum values in y-direction with lv_chart_set_range(chart, y_min, y_max). The value of the points will be scaled proportionally. The default range is: 0..100.

Division lines

The number of horizontal and vertical division lines can be modified by lv_chart_set_div_line_count(chart, hdiv_num, vdiv_num). The default settings are 3 horizontal and 5 vertical division lines.

Tick marks and labels

Ticks and labels can be added to the axis.

lv_chart_set_x_tick_text(chart, list_of_values, num_tick_marks, LV_CHART_AXIS_...) set the ticks and texts on x axis. list_of_values is a string with '\n' terminated text (expect the last) with text for the ticks. E.g. const char * list_of_values = "first\nsec\nthird". list_of_values can be NULL. If list_of_values is set then num_tick_marks tells the number of ticks between two labels. If list_of_values is NULL then it specifies the total number of ticks.

Major tick lines are drawn where text is placed, and minor tick lines are drawn elsewhere. lv_chart_set_x_tick_length(chart, major_tick_len, minor_tick_len) sets the length of tick lines on the x-axis.

The same functions exists for the y axis too: lv_chart_set_y_tick_text and lv_chart_set_y_tick_length.

Events

Only the Generic events are sent by the object type.

Learn more about Events.

Keys

No Keys are processed by the object type.

Learn more about Keys.

Example

C

Line Chart

Simple Chart example in LittlevGL

code

#include "../../../lv_examples.h"
#if LV_USE_CHART

void lv_ex_chart_1(void)
{
    /*Create a chart*/
    lv_obj_t * chart;
    chart = lv_chart_create(lv_scr_act(), NULL);
    lv_obj_set_size(chart, 200, 150);
    lv_obj_align(chart, NULL, LV_ALIGN_CENTER, 0, 0);
    lv_chart_set_type(chart, LV_CHART_TYPE_LINE);   /*Show lines and points too*/

    /*Add two data series*/
    lv_chart_series_t * ser1 = lv_chart_add_series(chart, LV_COLOR_RED);
    lv_chart_series_t * ser2 = lv_chart_add_series(chart, LV_COLOR_GREEN);

    /*Set the next points on 'ser1'*/
    lv_chart_set_next(chart, ser1, 10);
    lv_chart_set_next(chart, ser1, 10);
    lv_chart_set_next(chart, ser1, 10);
    lv_chart_set_next(chart, ser1, 10);
    lv_chart_set_next(chart, ser1, 10);
    lv_chart_set_next(chart, ser1, 10);
    lv_chart_set_next(chart, ser1, 10);
    lv_chart_set_next(chart, ser1, 30);
    lv_chart_set_next(chart, ser1, 70);
    lv_chart_set_next(chart, ser1, 90);

    /*Directly set points on 'ser2'*/
    ser2->points[0] = 90;
    ser2->points[1] = 70;
    ser2->points[2] = 65;
    ser2->points[3] = 65;
    ser2->points[4] = 65;
    ser2->points[5] = 65;
    ser2->points[6] = 65;
    ser2->points[7] = 65;
    ser2->points[8] = 65;
    ser2->points[9] = 65;

    lv_chart_refresh(chart); /*Required after direct set*/
}

#endif
Add a faded area effect to the line chart

code

#include "../../../lv_examples.h"
#if LV_USE_CHART

/**
 * Add a faded area effect to the line chart
 */
void lv_ex_chart_2(void)
{
    /*Create a chart*/
    lv_obj_t * chart;
    chart = lv_chart_create(lv_scr_act(), NULL);
    lv_obj_set_size(chart, 200, 150);
    lv_obj_align(chart, NULL, LV_ALIGN_CENTER, 0, 0);
    lv_chart_set_type(chart, LV_CHART_TYPE_LINE);   /*Show lines and points too*/

    /*Add a faded are effect*/
    lv_obj_set_style_local_bg_opa(chart, LV_CHART_PART_SERIES, LV_STATE_DEFAULT, LV_OPA_50); /*Max. opa.*/
    lv_obj_set_style_local_bg_grad_dir(chart, LV_CHART_PART_SERIES, LV_STATE_DEFAULT, LV_GRAD_DIR_VER);
    lv_obj_set_style_local_bg_main_stop(chart, LV_CHART_PART_SERIES, LV_STATE_DEFAULT, 255);    /*Max opa on the top*/
    lv_obj_set_style_local_bg_grad_stop(chart, LV_CHART_PART_SERIES, LV_STATE_DEFAULT, 0);      /*Transparent on the bottom*/


    /*Add two data series*/
    lv_chart_series_t * ser1 = lv_chart_add_series(chart, LV_COLOR_RED);
    lv_chart_series_t * ser2 = lv_chart_add_series(chart, LV_COLOR_GREEN);

    /*Set the next points on 'ser1'*/
    lv_chart_set_next(chart, ser1, 31);
    lv_chart_set_next(chart, ser1, 66);
    lv_chart_set_next(chart, ser1, 10);
    lv_chart_set_next(chart, ser1, 89);
    lv_chart_set_next(chart, ser1, 63);
    lv_chart_set_next(chart, ser1, 56);
    lv_chart_set_next(chart, ser1, 32);
    lv_chart_set_next(chart, ser1, 35);
    lv_chart_set_next(chart, ser1, 57);
    lv_chart_set_next(chart, ser1, 85);

    /*Directly set points on 'ser2'*/
    ser2->points[0] = 92;
    ser2->points[1] = 71;
    ser2->points[2] = 61;
    ser2->points[3] = 15;
    ser2->points[4] = 21;
    ser2->points[5] = 35;
    ser2->points[6] = 35;
    ser2->points[7] = 58;
    ser2->points[8] = 31;
    ser2->points[9] = 53;

    lv_chart_refresh(chart); /*Required after direct set*/
}

#endif

MicroPython

No examples yet.

API

Typedefs

typedef uint8_t lv_chart_type_t
typedef uint8_t lv_chart_update_mode_t
typedef uint8_t lv_chart_axis_options_t

Enums

enum [anonymous]

Chart types

Values:

enumerator LV_CHART_TYPE_NONE = 0x00

Don't draw the series

enumerator LV_CHART_TYPE_LINE = 0x01

Connect the points with lines

enumerator LV_CHART_TYPE_COLUMN = 0x02

Draw columns

enum [anonymous]

Chart update mode for lv_chart_set_next

Values:

enumerator LV_CHART_UPDATE_MODE_SHIFT

Shift old data to the left and add the new one o the right

enumerator LV_CHART_UPDATE_MODE_CIRCULAR

Add the new data in a circular way

enum [anonymous]

Data of axis

Values:

enumerator LV_CHART_AXIS_SKIP_LAST_TICK = 0x00

don't draw the last tick

enumerator LV_CHART_AXIS_DRAW_LAST_TICK = 0x01

draw the last tick

enumerator LV_CHART_AXIS_INVERSE_LABELS_ORDER = 0x02

draw tick labels in an inversed order

enum [anonymous]

Values:

enumerator LV_CHART_PART_BG = LV_OBJ_PART_MAIN
enumerator LV_CHART_PART_SERIES_BG = _LV_OBJ_PART_VIRTUAL_LAST
enumerator LV_CHART_PART_SERIES

Functions

LV_EXPORT_CONST_INT(LV_CHART_POINT_DEF)
LV_EXPORT_CONST_INT(LV_CHART_TICK_LENGTH_AUTO)
lv_obj_t *lv_chart_create(lv_obj_t *par, const lv_obj_t *copy)

Create a chart background objects

Return

pointer to the created chart background

Parameters
  • par: pointer to an object, it will be the parent of the new chart background

  • copy: pointer to a chart background object, if not NULL then the new object will be copied from it

lv_chart_series_t *lv_chart_add_series(lv_obj_t *chart, lv_color_t color)

Allocate and add a data series to the chart

Return

pointer to the allocated data series

Parameters
  • chart: pointer to a chart object

  • color: color of the data series

void lv_chart_clear_serie(lv_obj_t *chart, lv_chart_series_t *serie)

Clear the point of a series

Parameters
  • chart: pointer to a chart object

  • serie: pointer to the chart's series to clear

void lv_chart_set_div_line_count(lv_obj_t *chart, uint8_t hdiv, uint8_t vdiv)

Set the number of horizontal and vertical division lines

Parameters
  • chart: pointer to a graph background object

  • hdiv: number of horizontal division lines

  • vdiv: number of vertical division lines

void lv_chart_set_range(lv_obj_t *chart, lv_coord_t ymin, lv_coord_t ymax)

Set the minimal and maximal y values

Parameters
  • chart: pointer to a graph background object

  • ymin: y minimum value

  • ymax: y maximum value

void lv_chart_set_type(lv_obj_t *chart, lv_chart_type_t type)

Set a new type for a chart

Parameters
  • chart: pointer to a chart object

  • type: new type of the chart (from 'lv_chart_type_t' enum)

void lv_chart_set_point_count(lv_obj_t *chart, uint16_t point_cnt)

Set the number of points on a data line on a chart

Parameters
  • chart: pointer r to chart object

  • point_cnt: new number of points on the data lines

void lv_chart_init_points(lv_obj_t *chart, lv_chart_series_t *ser, lv_coord_t y)

Initialize all data points with a value

Parameters
  • chart: pointer to chart object

  • ser: pointer to a data series on 'chart'

  • y: the new value for all points

void lv_chart_set_points(lv_obj_t *chart, lv_chart_series_t *ser, lv_coord_t y_array[])

Set the value of points from an array

Parameters
  • chart: pointer to chart object

  • ser: pointer to a data series on 'chart'

  • y_array: array of 'lv_coord_t' points (with 'points count' elements )

void lv_chart_set_next(lv_obj_t *chart, lv_chart_series_t *ser, lv_coord_t y)

Shift all data right and set the most right data on a data line

Parameters
  • chart: pointer to chart object

  • ser: pointer to a data series on 'chart'

  • y: the new value of the most right data

void lv_chart_set_update_mode(lv_obj_t *chart, lv_chart_update_mode_t update_mode)

Set update mode of the chart object.

Parameters
  • chart: pointer to a chart object

  • update: mode

void lv_chart_set_x_tick_length(lv_obj_t *chart, uint8_t major_tick_len, uint8_t minor_tick_len)

Set the length of the tick marks on the x axis

Parameters
  • chart: pointer to the chart

  • major_tick_len: the length of the major tick or LV_CHART_TICK_LENGTH_AUTO to set automatically (where labels are added)

  • minor_tick_len: the length of the minor tick, LV_CHART_TICK_LENGTH_AUTO to set automatically (where no labels are added)

void lv_chart_set_y_tick_length(lv_obj_t *chart, uint8_t major_tick_len, uint8_t minor_tick_len)

Set the length of the tick marks on the y axis

Parameters
  • chart: pointer to the chart

  • major_tick_len: the length of the major tick or LV_CHART_TICK_LENGTH_AUTO to set automatically (where labels are added)

  • minor_tick_len: the length of the minor tick, LV_CHART_TICK_LENGTH_AUTO to set automatically (where no labels are added)

void lv_chart_set_secondary_y_tick_length(lv_obj_t *chart, uint8_t major_tick_len, uint8_t minor_tick_len)

Set the length of the tick marks on the secondary y axis

Parameters
  • chart: pointer to the chart

  • major_tick_len: the length of the major tick or LV_CHART_TICK_LENGTH_AUTO to set automatically (where labels are added)

  • minor_tick_len: the length of the minor tick, LV_CHART_TICK_LENGTH_AUTO to set automatically (where no labels are added)

void lv_chart_set_x_tick_texts(lv_obj_t *chart, const char *list_of_values, uint8_t num_tick_marks, lv_chart_axis_options_t options)

Set the x-axis tick count and labels of a chart

Parameters
  • chart: pointer to a chart object

  • list_of_values: list of string values, terminated with

    , except the last

  • num_tick_marks: if list_of_values is NULL: total number of ticks per axis else number of ticks between two value labels

  • options: extra options

void lv_chart_set_secondary_y_tick_texts(lv_obj_t *chart, const char *list_of_values, uint8_t num_tick_marks, lv_chart_axis_options_t options)

Set the secondary y-axis tick count and labels of a chart

Parameters
  • chart: pointer to a chart object

  • list_of_values: list of string values, terminated with

    , except the last

  • num_tick_marks: if list_of_values is NULL: total number of ticks per axis else number of ticks between two value labels

  • options: extra options

void lv_chart_set_y_tick_texts(lv_obj_t *chart, const char *list_of_values, uint8_t num_tick_marks, lv_chart_axis_options_t options)

Set the y-axis tick count and labels of a chart

Parameters
  • chart: pointer to a chart object

  • list_of_values: list of string values, terminated with

    , except the last

  • num_tick_marks: if list_of_values is NULL: total number of ticks per axis else number of ticks between two value labels

  • options: extra options

lv_chart_type_t lv_chart_get_type(const lv_obj_t *chart)

Get the type of a chart

Return

type of the chart (from 'lv_chart_t' enum)

Parameters
  • chart: pointer to chart object

uint16_t lv_chart_get_point_count(const lv_obj_t *chart)

Get the data point number per data line on chart

Return

point number on each data line

Parameters
  • chart: pointer to chart object

void lv_chart_refresh(lv_obj_t *chart)

Refresh a chart if its data line has changed

Parameters
  • chart: pointer to chart object

struct lv_chart_series_t

Public Members

lv_coord_t *points
lv_color_t color
uint16_t start_point
struct lv_chart_axis_cfg_t

Public Members

const char *list_of_values
lv_chart_axis_options_t options
uint8_t num_tick_marks
uint8_t major_tick_len
uint8_t minor_tick_len
struct lv_chart_ext_t

Public Members

lv_ll_t series_ll
lv_coord_t ymin
lv_coord_t ymax
uint8_t hdiv_cnt
uint8_t vdiv_cnt
uint16_t point_cnt
lv_style_list_t style_series_bg
lv_style_list_t style_series
lv_chart_type_t type
lv_chart_axis_cfg_t y_axis
lv_chart_axis_cfg_t x_axis
lv_chart_axis_cfg_t secondary_y_axis
uint8_t update_mode