1 /**
2 * @file lv_chart.h
3 *
4 */
5
6 #ifndef LV_CHART_H
7 #define LV_CHART_H
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /*********************
14 * INCLUDES
15 *********************/
16 #ifdef LV_CONF_INCLUDE_SIMPLE
17 #include "lv_conf.h"
18 #else
19 #include "../../lv_conf.h"
20 #endif
21
22 #if LV_USE_CHART != 0
23
24 #include "../lv_core/lv_obj.h"
25 #include "lv_line.h"
26
27 /*********************
28 * DEFINES
29 *********************/
30
31 /**Default value of points. Can be used to not draw a point*/
32 #define LV_CHART_POINT_DEF (LV_COORD_MIN)
33
34 /**Automatically calculate the tick length*/
35 #define LV_CHART_TICK_LENGTH_AUTO 255
36
37 /**********************
38 * TYPEDEFS
39 **********************/
40
41 /** Chart types*/
42 enum {
43 LV_CHART_TYPE_NONE = 0x00, /**< Don't draw the series*/
44 LV_CHART_TYPE_LINE = 0x01, /**< Connect the points with lines*/
45 LV_CHART_TYPE_COLUMN = 0x02, /**< Draw columns*/
46 LV_CHART_TYPE_POINT = 0x04, /**< Draw circles on the points*/
47 LV_CHART_TYPE_VERTICAL_LINE = 0x08, /**< Draw vertical lines on points (useful when chart width == point count)*/
48 LV_CHART_TYPE_AREA = 0x10, /**< Draw area chart*/
49 };
50 typedef uint8_t lv_chart_type_t;
51
52 /** Chart update mode for `lv_chart_set_next`*/
53 enum {
54 LV_CHART_UPDATE_MODE_SHIFT, /**< Shift old data to the left and add the new one o the right*/
55 LV_CHART_UPDATE_MODE_CIRCULAR, /**< Add the new data in a circular way*/
56 };
57 typedef uint8_t lv_chart_update_mode_t;
58
59 typedef struct
60 {
61 lv_coord_t * points;
62 lv_color_t color;
63 uint16_t start_point;
64 } lv_chart_series_t;
65
66 /** Data of axis */
67 enum {
68 LV_CHART_AXIS_SKIP_LAST_TICK = 0x00, /**< don't draw the last tick */
69 LV_CHART_AXIS_DRAW_LAST_TICK = 0x01 /**< draw the last tick */
70 };
71 typedef uint8_t lv_chart_axis_options_t;
72
73 typedef struct
74 {
75 const char * list_of_values;
76 lv_chart_axis_options_t options;
77 uint8_t num_tick_marks;
78 uint8_t major_tick_len;
79 uint8_t minor_tick_len;
80 } lv_chart_axis_cfg_t;
81
82 /*Data of chart */
83 typedef struct
84 {
85 /*No inherited ext*/ /*Ext. of ancestor*/
86 /*New data for this type */
87 lv_ll_t series_ll; /*Linked list for the data line pointers (stores lv_chart_dl_t)*/
88 lv_coord_t ymin; /*y min value (used to scale the data)*/
89 lv_coord_t ymax; /*y max value (used to scale the data)*/
90 uint8_t hdiv_cnt; /*Number of horizontal division lines*/
91 uint8_t vdiv_cnt; /*Number of vertical division lines*/
92 uint16_t point_cnt; /*Point number in a data line*/
93 lv_chart_type_t type; /*Line, column or point chart (from 'lv_chart_type_t')*/
94 lv_chart_axis_cfg_t y_axis;
95 lv_chart_axis_cfg_t x_axis;
96 uint16_t margin;
97 uint8_t update_mode : 1;
98 struct
99 {
100 lv_coord_t width; /*Line width or point radius*/
101 uint8_t num; /*Number of data lines in dl_ll*/
102 lv_opa_t opa; /*Opacity of data lines*/
103 lv_opa_t dark; /*Dark level of the point/column bottoms*/
104 } series;
105 } lv_chart_ext_t;
106
107 enum {
108 LV_CHART_STYLE_MAIN,
109 };
110 typedef uint8_t lv_chart_style_t;
111
112 /**********************
113 * GLOBAL PROTOTYPES
114 **********************/
115
116 /**
117 * Create a chart background objects
118 * @param par pointer to an object, it will be the parent of the new chart background
119 * @param copy pointer to a chart background object, if not NULL then the new object will be copied
120 * from it
121 * @return pointer to the created chart background
122 */
123 lv_obj_t * lv_chart_create(lv_obj_t * par, const lv_obj_t * copy);
124
125 /*======================
126 * Add/remove functions
127 *=====================*/
128
129 /**
130 * Allocate and add a data series to the chart
131 * @param chart pointer to a chart object
132 * @param color color of the data series
133 * @return pointer to the allocated data series
134 */
135 lv_chart_series_t * lv_chart_add_series(lv_obj_t * chart, lv_color_t color);
136
137 /**
138 * Clear the point of a serie
139 * @param chart pointer to a chart object
140 * @param serie pointer to the chart's serie to clear
141 */
142 void lv_chart_clear_serie(lv_obj_t * chart, lv_chart_series_t * serie);
143
144 /*=====================
145 * Setter functions
146 *====================*/
147
148 /**
149 * Set the number of horizontal and vertical division lines
150 * @param chart pointer to a graph background object
151 * @param hdiv number of horizontal division lines
152 * @param vdiv number of vertical division lines
153 */
154 void lv_chart_set_div_line_count(lv_obj_t * chart, uint8_t hdiv, uint8_t vdiv);
155
156 /**
157 * Set the minimal and maximal y values
158 * @param chart pointer to a graph background object
159 * @param ymin y minimum value
160 * @param ymax y maximum value
161 */
162 void lv_chart_set_range(lv_obj_t * chart, lv_coord_t ymin, lv_coord_t ymax);
163
164 /**
165 * Set a new type for a chart
166 * @param chart pointer to a chart object
167 * @param type new type of the chart (from 'lv_chart_type_t' enum)
168 */
169 void lv_chart_set_type(lv_obj_t * chart, lv_chart_type_t type);
170
171 /**
172 * Set the number of points on a data line on a chart
173 * @param chart pointer r to chart object
174 * @param point_cnt new number of points on the data lines
175 */
176 void lv_chart_set_point_count(lv_obj_t * chart, uint16_t point_cnt);
177
178 /**
179 * Set the opacity of the data series
180 * @param chart pointer to a chart object
181 * @param opa opacity of the data series
182 */
183 void lv_chart_set_series_opa(lv_obj_t * chart, lv_opa_t opa);
184
185 /**
186 * Set the line width or point radius of the data series
187 * @param chart pointer to a chart object
188 * @param width the new width
189 */
190 void lv_chart_set_series_width(lv_obj_t * chart, lv_coord_t width);
191
192 /**
193 * Set the dark effect on the bottom of the points or columns
194 * @param chart pointer to a chart object
195 * @param dark_eff dark effect level (LV_OPA_TRANSP to turn off)
196 */
197 void lv_chart_set_series_darking(lv_obj_t * chart, lv_opa_t dark_eff);
198
199 /**
200 * Initialize all data points with a value
201 * @param chart pointer to chart object
202 * @param ser pointer to a data series on 'chart'
203 * @param y the new value for all points
204 */
205 void lv_chart_init_points(lv_obj_t * chart, lv_chart_series_t * ser, lv_coord_t y);
206
207 /**
208 * Set the value of points from an array
209 * @param chart pointer to chart object
210 * @param ser pointer to a data series on 'chart'
211 * @param y_array array of 'lv_coord_t' points (with 'points count' elements )
212 */
213 void lv_chart_set_points(lv_obj_t * chart, lv_chart_series_t * ser, lv_coord_t y_array[]);
214
215 /**
216 * Shift all data right and set the most right data on a data line
217 * @param chart pointer to chart object
218 * @param ser pointer to a data series on 'chart'
219 * @param y the new value of the most right data
220 */
221 void lv_chart_set_next(lv_obj_t * chart, lv_chart_series_t * ser, lv_coord_t y);
222
223 /**
224 * Set update mode of the chart object.
225 * @param chart pointer to a chart object
226 * @param update mode
227 */
228 void lv_chart_set_update_mode(lv_obj_t * chart, lv_chart_update_mode_t update_mode);
229
230 /**
231 * Set the style of a chart
232 * @param chart pointer to a chart object
233 * @param type which style should be set (can be only `LV_CHART_STYLE_MAIN`)
234 * @param style pointer to a style
235 */
lv_chart_set_style(lv_obj_t * chart,lv_chart_style_t type,const lv_style_t * style)236 static inline void lv_chart_set_style(lv_obj_t * chart, lv_chart_style_t type, const lv_style_t * style)
237 {
238 (void)type; /*Unused*/
239 lv_obj_set_style(chart, style);
240 }
241
242 /**
243 * Set the length of the tick marks on the x axis
244 * @param chart pointer to the chart
245 * @param major_tick_len the length of the major tick or `LV_CHART_TICK_LENGTH_AUTO` to set automatically
246 * (where labels are added)
247 * @param minor_tick_len the length of the minor tick, `LV_CHART_TICK_LENGTH_AUTO` to set automatically
248 * (where no labels are added)
249 */
250 void lv_chart_set_x_tick_length(lv_obj_t * chart, uint8_t major_tick_len, uint8_t minor_tick_len);
251
252 /**
253 * Set the length of the tick marks on the y axis
254 * @param chart pointer to the chart
255 * @param major_tick_len the length of the major tick or `LV_CHART_TICK_LENGTH_AUTO` to set automatically
256 * (where labels are added)
257 * @param minor_tick_len the length of the minor tick, `LV_CHART_TICK_LENGTH_AUTO` to set automatically
258 * (where no labels are added)
259 */
260 void lv_chart_set_y_tick_length(lv_obj_t * chart, uint8_t major_tick_len, uint8_t minor_tick_len);
261
262 /**
263 * Set the x-axis tick count and labels of a chart
264 * @param chart pointer to a chart object
265 * @param list_of_values list of string values, terminated with \n, except the last
266 * @param num_tick_marks if list_of_values is NULL: total number of ticks per axis
267 * else number of ticks between two value labels
268 * @param options extra options
269 */
270 void lv_chart_set_x_tick_texts(lv_obj_t * chart, const char * list_of_values, uint8_t num_tick_marks,
271 lv_chart_axis_options_t options);
272
273 /**
274 * Set the y-axis tick count and labels of a chart
275 * @param chart pointer to a chart object
276 * @param list_of_values list of string values, terminated with \n, except the last
277 * @param num_tick_marks if list_of_values is NULL: total number of ticks per axis
278 * else number of ticks between two value labels
279 * @param options extra options
280 */
281 void lv_chart_set_y_tick_texts(lv_obj_t * chart, const char * list_of_values, uint8_t num_tick_marks,
282 lv_chart_axis_options_t options);
283
284 /**
285 * Set the margin around the chart, used for axes value and ticks
286 * @param chart pointer to an chart object
287 * @param margin value of the margin [px]
288 */
289 void lv_chart_set_margin(lv_obj_t * chart, uint16_t margin);
290
291 /*=====================
292 * Getter functions
293 *====================*/
294
295 /**
296 * Get the type of a chart
297 * @param chart pointer to chart object
298 * @return type of the chart (from 'lv_chart_t' enum)
299 */
300 lv_chart_type_t lv_chart_get_type(const lv_obj_t * chart);
301
302 /**
303 * Get the data point number per data line on chart
304 * @param chart pointer to chart object
305 * @return point number on each data line
306 */
307 uint16_t lv_chart_get_point_cnt(const lv_obj_t * chart);
308
309 /**
310 * Get the opacity of the data series
311 * @param chart pointer to chart object
312 * @return the opacity of the data series
313 */
314 lv_opa_t lv_chart_get_series_opa(const lv_obj_t * chart);
315
316 /**
317 * Get the data series width
318 * @param chart pointer to chart object
319 * @return the width the data series (lines or points)
320 */
321 lv_coord_t lv_chart_get_series_width(const lv_obj_t * chart);
322
323 /**
324 * Get the dark effect level on the bottom of the points or columns
325 * @param chart pointer to chart object
326 * @return dark effect level (LV_OPA_TRANSP to turn off)
327 */
328 lv_opa_t lv_chart_get_series_darking(const lv_obj_t * chart);
329
330 /**
331 * Get the style of an chart object
332 * @param chart pointer to an chart object
333 * @param type which style should be get (can be only `LV_CHART_STYLE_MAIN`)
334 * @return pointer to the chart's style
335 */
lv_chart_get_style(const lv_obj_t * chart,lv_chart_style_t type)336 static inline const lv_style_t * lv_chart_get_style(const lv_obj_t * chart, lv_chart_style_t type)
337 {
338 (void)type; /*Unused*/
339 return lv_obj_get_style(chart);
340 }
341
342 /**
343 * Get the margin around the chart, used for axes value and labels
344 * @param chart pointer to an chart object
345 * @param return value of the margin
346 */
347 uint16_t lv_chart_get_margin(lv_obj_t * chart);
348
349 /*=====================
350 * Other functions
351 *====================*/
352
353 /**
354 * Refresh a chart if its data line has changed
355 * @param chart pointer to chart object
356 */
357 void lv_chart_refresh(lv_obj_t * chart);
358
359 /**********************
360 * MACROS
361 **********************/
362
363 #endif /*LV_USE_CHART*/
364
365 #ifdef __cplusplus
366 } /* extern "C" */
367 #endif
368
369 #endif /*LV_CHART_H*/
370