Chart (lv_chart)

Overview

Charts are a basic object to visualize data points. Currently Line charts (connect points with lines and/or draw points on them) and Bar charts are supported.

Charts can have:

  • division lines

  • 2 y axis

  • axis ticks and texts on ticks

  • cursors

  • scrolling and zooming

Parts and Styles

  • LV_PART_MAIN The background of the chart. Uses all the typical background and line (for the division lines) related style properties. Padding makes the series area smaller. For column charts pad_column sets the space between the columns of the adjacent indices.

  • LV_PART_SCROLLBAR The scrollbar used if the chart is zoomed. See the Base object's documentation for details.

  • LV_PART_ITEMS Refers to the line or bar series.

    • Line chart: The line properties are used by the lines. width, height, bg_color and radius is used to set the appearance of points.

    • Bar chart: The typical background properties are used to style the bars. pad_column sets the space between the columns on the same index.

  • LV_PART_INDICATOR Refers to the points on line and scatter chart (small circles or squares).

  • LV_PART_CURSOR Line properties are used to style the cursors. width, height, bg_color and radius are used to set the appearance of points.

  • LV_PART_TICKS Line and Text style properties are used to style the ticks

Usage

Chart type

The following data display types exist:

  • LV_CHART_TYPE_NONE Do not display any data. Can be used to hide the series.

  • LV_CHART_TYPE_LINE Draw lines between the data points and/or points (rectangles or circles) on the data points.

  • LV_CHART_TYPE_BAR - Draw bars.

  • LV_CHART_TYPE_SCATTER - X/Y chart drawing point's and lines between the points. .

You can specify the display type with lv_chart_set_type(chart, LV_CHART_TYPE_...).

Data series

You can add any number of series to the charts by lv_chart_add_series(chart, color, axis). This allocates an lv_chart_series_t structure which contains the chosen color and an array for the data points. axis can have the following values:

  • LV_CHART_AXIS_PRIMARY_Y Left axis

  • LV_CHART_AXIS_SECONDARY_Y Right axis

  • LV_CHART_AXIS_PRIMARY_X Bottom axis

  • LV_CHART_AXIS_SECONDARY_X Top axis

axis tells which axis's range should be used te scale the values.

lv_chart_set_ext_y_array(chart, ser, value_array) makes the chart use an external array for the given series. value_array should look like this: lv_coord_t * value_array[num_points]. The array size needs to be large enough to hold all the points of that series. The array's pointer will be saved in the chart so it needs to be global, static or dynamically allocated. Note: you should call lv_chart_refresh(chart) after the external data source has been updated to update the chart.

The value array of a series can be obtained with lv_chart_get_y_array(chart, ser), which can be used with ext_array or normal arrays.

For LV_CHART_TYPE_SCATTER type lv_chart_set_ext_x_array(chart, ser, value_array) and lv_chart_get_x_array(chart, ser) can be used as well.

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 lv_chart_set_value_by_id(chart, ser, id, value) where id is the index of the point you wish to update.

  3. Use the lv_chart_set_next_value(chart, ser, value).

  4. Initialize all points to a given value with: lv_chart_set_all_value(chart, ser, value).

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

For LV_CHART_TYPE_SCATTER type lv_chart_set_value_by_id2(chart, ser, id, value) and lv_chart_set_next_value2(chart, ser, x_valuem y_value) can be used as well.

Update modes

lv_chart_set_next_value 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 to the right.

  • LV_CHART_UPDATE_MODE_CIRCULAR - Add the new data in circular fashion, 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. Note: this also affects the number of points processed when an external buffer is assigned to a series, so you need to be sure the external array is large enough.

Handling large number of points

On line charts, if the number of points is greater than the pixels horizontally, the Chart will draw only vertical lines to make the drawing of large amount of data effective. If there are, let's say, 10 points to a pixel, LVGL searches the smallest and the largest value and draws a vertical lines between them to ensure no peaks are missed.

Vertical range

You can specify the minimum and maximum values in y-direction with lv_chart_set_range(chart, axis, min, max). axis can be LV_CHART_AXIS_PRIMARY (left axis) or LV_CHART_AXIS_SECONDARY (right axis).

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. If there is a visible border on a side and no padding on that side, the division line would be drawn on top of the border and therefore it won't be drawn.

Override default start point for series

If you want a plot to start from a point other than the default which is point[0] of the series, you can set an alternative index with the function lv_chart_set_x_start_point(chart, ser, id) where id is the new index position to start plotting from.

Note that LV_CHART_UPDATE_MODE_SHIFT also changes the start_point.

Tick marks and labels

Ticks and labels can be added to the axis with lv_chart_set_axis_tick(chart, axis, major_len, minor_len, major_cnt, minor_cnt, label_en, draw_size).

  • axis can be LV_CHART_AXIS_X/PRIMARY_Y/SECONDARY_Y

  • major_len is the length of major ticks

  • minor_len is the length of minor ticks

  • major_cnt is the number of major ticks on the axis

  • minor_cnt in the number of minor ticks between two major ticks

  • label_en true: enable label drawing on major ticks

  • draw_size extra size required to draw the tick and labels (start with 20 px and increase if the ticks/labels are clipped)

Zoom

The chart can be zoomed independently in x and y directions with lv_chart_set_zoom_x(chart, factor) and lv_chart_set_zoom_y(chart, factor). If factor is 256 there is no zoom. 512 means double zoom, etc. Fractional values are also possible but < 256 value is not allowed.

Cursor

A cursor can be added with lv_chart_cursor_t * c1 = lv_chart_add_cursor(chart, color, dir);. The possible values of dir LV_DIR_NONE/RIGHT/UP/LEFT/DOWN/HOR/VER/ALL or their OR-ed values to tell in which direction(s) should the cursor be drawn.

lv_chart_set_cursor_pos(chart, cursor, &point) sets the position of the cursor. pos is a pointer to an lv_point_t variable. E.g. lv_point_t point = {10, 20};. If the chart is scrolled the cursor will remain in the same place.

lv_chart_get_point_pos_by_id(chart, series, id, &point_out) gets the coordinate of a given point. It's useful to place the cursor at a given point.

lv_chart_set_cursor_point(chart, cursor, series, point_id) sticks the cursor at a point. If the point's position changes (new value or scrolling) the cursor will move with the point.

Events

  • LV_EVENT_VALUE_CHANGED Sent when a new point is clicked pressed. lv_chart_get_pressed_point(chart) returns the zero-based index of the pressed point.

  • LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END are sent with the following types:

    • LV_CHART_DRAW_PART_DIV_LINE_INIT Used before/after drawn the div lines to add masks to any extra drawings. The following fields are set:

      • part: LV_PART_MAIN

      • line_dsc

    • LV_CHART_DRAW_PART_DIV_LINE_HOR, LV_CHART_DRAW_PART_DIV_LINE_VER Used for each horizontal and vertical division lines.

      • part: LV_PART_MAIN

      • id: index of the line

      • p1, p2: points of the line

      • line_dsc

    • LV_CHART_DRAW_PART_LINE_AND_POINT Used on line and scatter charts for lines and points.

      • part: LV_PART_ITEMS

      • id: index of the point

      • value: value of idth point

      • p1, p2: points of the line

      • draw_area: area of the point

      • line_dsc

      • rect_dsc

      • sub_part_ptr: pointer to the series

    • LV_CHART_DRAW_PART_BAR Used on bar charts for the rectangles.

      • part: LV_PART_ITEMS

      • id: index of the point

      • value: value of idth point

      • draw_area: area of the point

      • rect_dsc:

      • sub_part_ptr: pointer to the series

    • LV_CHART_DRAW_PART_CURSOR Used on cursor lines and points.

      • part: LV_PART_CURSOR

      • p1, p2: points of the line

      • line_dsc

      • rect_dsc

      • draw_area: area of the points

    • LV_CHART_DRAW_PART_TICK_LABEL Used on tick lines and labels.

      • part: LV_PART_TICKS

      • id: axis

      • value: value of the tick

      • text: value converted to decimal or NULL for minor ticks

      • line_dsc,

      • label_dsc,

See the events of the Base object too.

Learn more about Events.

Keys

No Keys are processed by the object type.

Learn more about Keys.

Example

Line Chart

C code  

 GitHub

MicroPython code  

 GitHub Simulator

Faded area line chart with custom division lines

C code  

 GitHub

MicroPython code  

 GitHub Simulator

Axis ticks and labels with scrolling

C code  

 GitHub

MicroPython code  

 GitHub Simulator

Show the value of the pressed points

C code  

 GitHub

MicroPython code  

 GitHub Simulator

Display 1000 data points with zooming and scrolling

C code  

 GitHub

MicroPython code  

 GitHub Simulator

Show cursor on the clicked point

C code  

 GitHub

MicroPython code  

 GitHub Simulator

Scatter chart

C code  

 GitHub

MicroPython code  

 GitHub Simulator

Stacked area chart

C code  

 GitHub

MicroPython code  

 GitHub Simulator

API

Typedefs

typedef uint8_t lv_chart_type_t
typedef uint8_t lv_chart_update_mode_t
typedef uint8_t lv_chart_axis_t

Enums

enum [anonymous]

Chart types

Values:

enumerator LV_CHART_TYPE_NONE

Don't draw the series

enumerator LV_CHART_TYPE_LINE

Connect the points with lines

enumerator LV_CHART_TYPE_BAR

Draw columns

enumerator LV_CHART_TYPE_SCATTER

Draw points and lines in 2D (x,y coordinates)

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 the right

enumerator LV_CHART_UPDATE_MODE_CIRCULAR

Add the new data in a circular way

enum [anonymous]

Enumeration of the axis'

Values:

enumerator LV_CHART_AXIS_PRIMARY_Y
enumerator LV_CHART_AXIS_SECONDARY_Y
enumerator LV_CHART_AXIS_PRIMARY_X
enumerator LV_CHART_AXIS_SECONDARY_X
enumerator _LV_CHART_AXIS_LAST
enum lv_chart_draw_part_type_t

type field in lv_obj_draw_part_dsc_t if class_p = lv_chart_class Used in LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END

Values:

enumerator LV_CHART_DRAW_PART_DIV_LINE_INIT

Used before/after drawn the div lines

enumerator LV_CHART_DRAW_PART_DIV_LINE_HOR

Used for each horizontal division lines

enumerator LV_CHART_DRAW_PART_DIV_LINE_VER

Used for each vertical division lines

enumerator LV_CHART_DRAW_PART_LINE_AND_POINT

Used on line and scatter charts for lines and points

enumerator LV_CHART_DRAW_PART_BAR

Used on bar charts for the rectangles

enumerator LV_CHART_DRAW_PART_CURSOR

Used on cursor lines and points

enumerator LV_CHART_DRAW_PART_TICK_LABEL

Used on tick lines and labels

Functions

LV_EXPORT_CONST_INT(LV_CHART_POINT_NONE)
lv_obj_t *lv_chart_create(lv_obj_t *parent)

Create a chart object

Parameters

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

Returns

pointer to the created chart

void lv_chart_set_type(lv_obj_t *obj, lv_chart_type_t type)

Set a new type for a chart

Parameters

  • obj -- 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 *obj, uint16_t cnt)

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

Parameters

  • obj -- pointer to a chart object

  • cnt -- new number of points on the data lines

void lv_chart_set_range(lv_obj_t *obj, lv_chart_axis_t axis, lv_coord_t min, lv_coord_t max)

Set the minimal and maximal y values on an axis

Parameters

  • obj -- pointer to a chart object

  • axis -- LV_CHART_AXIS_PRIMARY_Y or LV_CHART_AXIS_SECONDARY_Y

  • min -- minimum value of the y axis

  • max -- maximum value of the y axis

void lv_chart_set_update_mode(lv_obj_t *obj, lv_chart_update_mode_t update_mode)

Set update mode of the chart object. Affects

Parameters

  • obj -- pointer to a chart object

  • mode -- the update mode

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

Set the number of horizontal and vertical division lines

Parameters

  • obj -- pointer to a chart object

  • hdiv -- number of horizontal division lines

  • vdiv -- number of vertical division lines

void lv_chart_set_zoom_x(lv_obj_t *obj, uint16_t zoom_x)

Zoom into the chart in X direction

Parameters

  • obj -- pointer to a chart object

  • zoom_x -- zoom in x direction. LV_ZOOM_NONE or 256 for no zoom, 512 double zoom

void lv_chart_set_zoom_y(lv_obj_t *obj, uint16_t zoom_y)

Zoom into the chart in Y direction

Parameters

  • obj -- pointer to a chart object

  • zoom_y -- zoom in y direction. LV_ZOOM_NONE or 256 for no zoom, 512 double zoom

uint16_t lv_chart_get_zoom_x(const lv_obj_t *obj)

Get X zoom of a chart

Parameters

obj -- pointer to a chart object

Returns

the X zoom value

uint16_t lv_chart_get_zoom_y(const lv_obj_t *obj)

Get Y zoom of a chart

Parameters

obj -- pointer to a chart object

Returns

the Y zoom value

void lv_chart_set_axis_tick(lv_obj_t *obj, lv_chart_axis_t axis, lv_coord_t major_len, lv_coord_t minor_len, lv_coord_t major_cnt, lv_coord_t minor_cnt, bool label_en, lv_coord_t draw_size)

Set the number of tick lines on an axis

Parameters

  • obj -- pointer to a chart object

  • axis -- an axis which ticks count should be set

  • major_len -- length of major ticks

  • minor_len -- length of minor ticks

  • major_cnt -- number of major ticks on the axis

  • minor_cnt -- number of minor ticks between two major ticks

  • label_en -- true: enable label drawing on major ticks

  • draw_size -- extra size required to draw the tick and labels (start with 20 px and increase if the ticks/labels are clipped)

lv_chart_type_t lv_chart_get_type(const lv_obj_t *obj)

Get the type of a chart

Parameters

obj -- pointer to chart object

Returns

type of the chart (from 'lv_chart_t' enum)

uint16_t lv_chart_get_point_count(const lv_obj_t *obj)

Get the data point number per data line on chart

Parameters

chart -- pointer to chart object

Returns

point number on each data line

uint16_t lv_chart_get_x_start_point(const lv_obj_t *obj, lv_chart_series_t *ser)

Get the current index of the x-axis start point in the data array

Parameters

  • chart -- pointer to a chart object

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

Returns

the index of the current x start point in the data array

void lv_chart_get_point_pos_by_id(lv_obj_t *obj, lv_chart_series_t *ser, uint16_t id, lv_point_t *p_out)

Get the position of a point to the chart.

Parameters

  • chart -- pointer to a chart object

  • ser -- pointer to series

  • id -- the index.

  • p_out -- store the result position here

void lv_chart_refresh(lv_obj_t *obj)

Refresh a chart if its data line has changed

Parameters

chart -- pointer to chart object

lv_chart_series_t *lv_chart_add_series(lv_obj_t *obj, lv_color_t color, lv_chart_axis_t axis)

Allocate and add a data series to the chart

Parameters

  • obj -- pointer to a chart object

  • color -- color of the data series

  • axis -- the y axis to which the series should be attached (::LV_CHART_AXIS_PRIMARY_Y or ::LV_CHART_AXIS_SECONDARY_Y)

Returns

pointer to the allocated data series

void lv_chart_remove_series(lv_obj_t *obj, lv_chart_series_t *series)

Deallocate and remove a data series from a chart

Parameters

  • chart -- pointer to a chart object

  • series -- pointer to a data series on 'chart'

void lv_chart_hide_series(lv_obj_t *chart, lv_chart_series_t *series, bool hide)

Hide/Unhide a single series of a chart.

Parameters

  • obj -- pointer to a chart object.

  • series -- pointer to a series object

  • hide -- true: hide the series

void lv_chart_set_series_color(lv_obj_t *chart, lv_chart_series_t *series, lv_color_t color)

Change the color of a series

Parameters

  • obj -- pointer to a chart object.

  • series -- pointer to a series object

  • color -- the new color of the series

void lv_chart_set_x_start_point(lv_obj_t *obj, lv_chart_series_t *ser, uint16_t id)

Set the index of the x-axis start point in the data array. This point will be considers the first (left) point and the other points will be drawn after it.

Parameters

  • obj -- pointer to a chart object

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

  • id -- the index of the x point in the data array

lv_chart_series_t *lv_chart_get_series_next(const lv_obj_t *chart, const lv_chart_series_t *ser)

Get the next series.

Parameters

  • chart -- pointer to a chart

  • ser -- the previous series or NULL to get the first

Returns

the next series or NULL if there is no more.

lv_chart_cursor_t *lv_chart_add_cursor(lv_obj_t *obj, lv_color_t color, lv_dir_t dir)

Add a cursor with a given color

Parameters

  • obj -- pointer to chart object

  • color -- color of the cursor

  • dir -- direction of the cursor. LV_DIR_RIGHT/LEFT/TOP/DOWN/HOR/VER/ALL. OR-ed values are possible

Returns

pointer to the created cursor

void lv_chart_set_cursor_pos(lv_obj_t *chart, lv_chart_cursor_t *cursor, lv_point_t *pos)

Set the coordinate of the cursor with respect to the paddings

Parameters

  • obj -- pointer to a chart object

  • cursor -- pointer to the cursor

  • pos -- the new coordinate of cursor relative to the chart

void lv_chart_set_cursor_point(lv_obj_t *chart, lv_chart_cursor_t *cursor, lv_chart_series_t *ser, uint16_t point_id)

Stick the cursor to a point

Parameters

  • obj -- pointer to a chart object

  • cursor -- pointer to the cursor

  • ser -- pointer to a series

  • point_id -- the point's index or LV_CHART_POINT_NONE to not assign to any points.

lv_point_t lv_chart_get_cursor_point(lv_obj_t *chart, lv_chart_cursor_t *cursor)

Get the coordinate of the cursor with respect to the paddings

Parameters

  • obj -- pointer to a chart object

  • cursor -- pointer to cursor

Returns

coordinate of the cursor as lv_point_t

void lv_chart_set_all_value(lv_obj_t *obj, lv_chart_series_t *ser, lv_coord_t value)

Initialize all data points of a series with a value

Parameters

  • obj -- pointer to chart object

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

  • value -- the new value for all points. LV_CHART_POINT_NONE can be used to hide the points.

void lv_chart_set_next_value(lv_obj_t *obj, lv_chart_series_t *ser, lv_coord_t value)

Set the next point's Y value according to the update mode policy.

Parameters

  • obj -- pointer to chart object

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

  • value -- the new value of the next data

void lv_chart_set_next_value2(lv_obj_t *obj, lv_chart_series_t *ser, lv_coord_t x_value, lv_coord_t y_value)

Set the next point's X and Y value according to the update mode policy.

Parameters

  • obj -- pointer to chart object

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

  • x_value -- the new X value of the next data

  • y_value -- the new Y value of the next data

void lv_chart_set_value_by_id(lv_obj_t *obj, lv_chart_series_t *ser, uint16_t id, lv_coord_t value)

Set an individual point's y value of a chart's series directly based on its index

Parameters

  • obj -- pointer to a chart object

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

  • id -- the index of the x point in the array

  • value -- value to assign to array point

void lv_chart_set_value_by_id2(lv_obj_t *obj, lv_chart_series_t *ser, uint16_t id, lv_coord_t x_value, lv_coord_t y_value)

Set an individual point's x and y value of a chart's series directly based on its index Can be used only with LV_CHART_TYPE_SCATTER.

Parameters

  • obj -- pointer to chart object

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

  • id -- the index of the x point in the array

  • x_value -- the new X value of the next data

  • y_value -- the new Y value of the next data

void lv_chart_set_ext_y_array(lv_obj_t *obj, lv_chart_series_t *ser, lv_coord_t array[])

Set an external array for the y data points to use for the chart NOTE: It is the users responsibility to make sure the point_cnt matches the external array size.

Parameters

  • obj -- pointer to a chart object

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

  • array -- external array of points for chart

void lv_chart_set_ext_x_array(lv_obj_t *obj, lv_chart_series_t *ser, lv_coord_t array[])

Set an external array for the x data points to use for the chart NOTE: It is the users responsibility to make sure the point_cnt matches the external array size.

Parameters

  • obj -- pointer to a chart object

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

  • array -- external array of points for chart

lv_coord_t *lv_chart_get_y_array(const lv_obj_t *obj, lv_chart_series_t *ser)

Get the array of y values of a series

Parameters

  • obj -- pointer to a chart object

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

Returns

the array of values with 'point_count' elements

lv_coord_t *lv_chart_get_x_array(const lv_obj_t *obj, lv_chart_series_t *ser)

Get the array of x values of a series

Parameters

  • obj -- pointer to a chart object

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

Returns

the array of values with 'point_count' elements

uint32_t lv_chart_get_pressed_point(const lv_obj_t *obj)

Get the index of the currently pressed point. It's the same for every series.

Parameters

obj -- pointer to a chart object

Returns

the index of the point [0 .. point count] or LV_CHART_POINT_ID_NONE if no point is being pressed

Variables

const lv_obj_class_t lv_chart_class
struct lv_chart_series_t
#include <lv_chart.h>

Descriptor a chart series

Public Members

lv_coord_t *x_points
lv_coord_t *y_points
lv_color_t color
uint16_t start_point
uint8_t hidden
uint8_t x_ext_buf_assigned
uint8_t y_ext_buf_assigned
uint8_t x_axis_sec
uint8_t y_axis_sec
struct lv_chart_cursor_t

Public Members

lv_point_t pos
lv_coord_t point_id
lv_color_t color
lv_chart_series_t *ser
lv_dir_t dir
uint8_t pos_set
struct lv_chart_tick_dsc_t

Public Members

lv_coord_t major_len
lv_coord_t minor_len
lv_coord_t draw_size
uint32_t minor_cnt
uint32_t major_cnt
uint32_t label_en
struct lv_chart_t

Public Members

lv_obj_t obj
lv_ll_t series_ll

Linked list for the series (stores lv_chart_series_t)

lv_ll_t cursor_ll

Linked list for the cursors (stores lv_chart_cursor_t)

lv_chart_tick_dsc_t tick[4]
lv_coord_t ymin[2]
lv_coord_t ymax[2]
lv_coord_t xmin[2]
lv_coord_t xmax[2]
lv_coord_t pressed_point_id
uint16_t hdiv_cnt

Number of horizontal division lines

uint16_t vdiv_cnt

Number of vertical division lines

uint16_t point_cnt

Point number in a data line

uint16_t zoom_x
uint16_t zoom_y
lv_chart_type_t type

Line or column chart

lv_chart_update_mode_t update_mode