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