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 "../../../lvgl.h" 17 18 #if LV_USE_CHART != 0 19 20 /********************* 21 * DEFINES 22 *********************/ 23 24 /**Default value of points. Can be used to not draw a point*/ 25 #define LV_CHART_POINT_NONE (INT16_MAX) 26 LV_EXPORT_CONST_INT(LV_CHART_POINT_NONE); 27 28 /********************** 29 * TYPEDEFS 30 **********************/ 31 32 /** 33 * Chart types 34 */ 35 enum { 36 LV_CHART_TYPE_NONE, /**< Don't draw the series*/ 37 LV_CHART_TYPE_LINE, /**< Connect the points with lines*/ 38 LV_CHART_TYPE_BAR, /**< Draw columns*/ 39 LV_CHART_TYPE_SCATTER, /**< Draw points and lines in 2D (x,y coordinates)*/ 40 }; 41 typedef uint8_t lv_chart_type_t; 42 43 /** 44 * Chart update mode for `lv_chart_set_next` 45 */ 46 enum { 47 LV_CHART_UPDATE_MODE_SHIFT, /**< Shift old data to the left and add the new one the right*/ 48 LV_CHART_UPDATE_MODE_CIRCULAR, /**< Add the new data in a circular way*/ 49 }; 50 typedef uint8_t lv_chart_update_mode_t; 51 52 /** 53 * Enumeration of the axis' 54 */ 55 enum { 56 LV_CHART_AXIS_PRIMARY_Y = 0x00, 57 LV_CHART_AXIS_SECONDARY_Y = 0x01, 58 LV_CHART_AXIS_PRIMARY_X = 0x02, 59 LV_CHART_AXIS_SECONDARY_X = 0x04, 60 _LV_CHART_AXIS_LAST 61 }; 62 typedef uint8_t lv_chart_axis_t; 63 64 /** 65 * Descriptor a chart series 66 */ 67 typedef struct { 68 lv_coord_t * x_points; 69 lv_coord_t * y_points; 70 lv_color_t color; 71 uint16_t start_point; 72 uint8_t hidden : 1; 73 uint8_t x_ext_buf_assigned : 1; 74 uint8_t y_ext_buf_assigned : 1; 75 uint8_t x_axis_sec : 1; 76 uint8_t y_axis_sec : 1; 77 } lv_chart_series_t; 78 79 typedef struct { 80 lv_point_t pos; 81 uint16_t point_id; 82 lv_color_t color; 83 lv_chart_series_t * ser; 84 lv_dir_t dir; 85 uint8_t pos_set: 1; /*1: pos is set; 0: point_id is set*/ 86 } lv_chart_cursor_t; 87 88 typedef struct { 89 lv_coord_t major_len; 90 lv_coord_t minor_len; 91 lv_coord_t draw_size; 92 uint32_t minor_cnt : 15; 93 uint32_t major_cnt : 15; 94 uint32_t label_en : 1; 95 } lv_chart_tick_dsc_t; 96 97 98 typedef struct { 99 lv_obj_t obj; 100 lv_ll_t series_ll; /**< Linked list for the series (stores lv_chart_series_t)*/ 101 lv_ll_t cursor_ll; /**< Linked list for the cursors (stores lv_chart_cursor_t)*/ 102 lv_chart_tick_dsc_t tick[4]; 103 lv_coord_t ymin[2]; 104 lv_coord_t ymax[2]; 105 lv_coord_t xmin[2]; 106 lv_coord_t xmax[2]; 107 uint16_t pressed_point_id; 108 uint16_t hdiv_cnt; /**< Number of horizontal division lines*/ 109 uint16_t vdiv_cnt; /**< Number of vertical division lines*/ 110 uint16_t point_cnt; /**< Point number in a data line*/ 111 uint16_t zoom_x; 112 uint16_t zoom_y; 113 lv_chart_type_t type : 3; /**< Line or column chart*/ 114 lv_chart_update_mode_t update_mode : 1; 115 } lv_chart_t; 116 117 extern const lv_obj_class_t lv_chart_class; 118 119 /** 120 * `type` field in `lv_obj_draw_part_dsc_t` if `class_p = lv_chart_class` 121 * Used in `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` 122 */ 123 typedef enum { 124 LV_CHART_DRAW_PART_DIV_LINE_INIT, /**< Used before/after drawn the div lines*/ 125 LV_CHART_DRAW_PART_DIV_LINE_HOR, /**< Used for each horizontal division lines*/ 126 LV_CHART_DRAW_PART_DIV_LINE_VER, /**< Used for each vertical division lines*/ 127 LV_CHART_DRAW_PART_LINE_AND_POINT, /**< Used on line and scatter charts for lines and points*/ 128 LV_CHART_DRAW_PART_BAR, /**< Used on bar charts for the rectangles*/ 129 LV_CHART_DRAW_PART_CURSOR, /**< Used on cursor lines and points*/ 130 LV_CHART_DRAW_PART_TICK_LABEL, /**< Used on tick lines and labels*/ 131 } lv_chart_draw_part_type_t; 132 133 /********************** 134 * GLOBAL PROTOTYPES 135 **********************/ 136 137 /** 138 * Create a chart object 139 * @param parent pointer to an object, it will be the parent of the new chart 140 * @return pointer to the created chart 141 */ 142 lv_obj_t * lv_chart_create(lv_obj_t * parent); 143 144 /** 145 * Set a new type for a chart 146 * @param obj pointer to a chart object 147 * @param type new type of the chart (from 'lv_chart_type_t' enum) 148 */ 149 void lv_chart_set_type(lv_obj_t * obj, lv_chart_type_t type); 150 /** 151 * Set the number of points on a data line on a chart 152 * @param obj pointer to a chart object 153 * @param cnt new number of points on the data lines 154 */ 155 void lv_chart_set_point_count(lv_obj_t * obj, uint16_t cnt); 156 157 /** 158 * Set the minimal and maximal y values on an axis 159 * @param obj pointer to a chart object 160 * @param axis `LV_CHART_AXIS_PRIMARY_Y` or `LV_CHART_AXIS_SECONDARY_Y` 161 * @param min minimum value of the y axis 162 * @param max maximum value of the y axis 163 */ 164 void lv_chart_set_range(lv_obj_t * obj, lv_chart_axis_t axis, lv_coord_t min, lv_coord_t max); 165 166 /** 167 * Set update mode of the chart object. Affects 168 * @param obj pointer to a chart object 169 * @param mode the update mode 170 */ 171 void lv_chart_set_update_mode(lv_obj_t * obj, lv_chart_update_mode_t update_mode); 172 173 /** 174 * Set the number of horizontal and vertical division lines 175 * @param obj pointer to a chart object 176 * @param hdiv number of horizontal division lines 177 * @param vdiv number of vertical division lines 178 */ 179 void lv_chart_set_div_line_count(lv_obj_t * obj, uint8_t hdiv, uint8_t vdiv); 180 181 /** 182 * Zoom into the chart in X direction 183 * @param obj pointer to a chart object 184 * @param zoom_x zoom in x direction. LV_ZOOM_NONE or 256 for no zoom, 512 double zoom 185 */ 186 void lv_chart_set_zoom_x(lv_obj_t * obj, uint16_t zoom_x); 187 188 /** 189 * Zoom into the chart in Y direction 190 * @param obj pointer to a chart object 191 * @param zoom_y zoom in y direction. LV_ZOOM_NONE or 256 for no zoom, 512 double zoom 192 */ 193 void lv_chart_set_zoom_y(lv_obj_t * obj, uint16_t zoom_y); 194 195 /** 196 * Get X zoom of a chart 197 * @param obj pointer to a chart object 198 * @return the X zoom value 199 */ 200 uint16_t lv_chart_get_zoom_x(const lv_obj_t * obj); 201 202 /** 203 * Get Y zoom of a chart 204 * @param obj pointer to a chart object 205 * @return the Y zoom value 206 */ 207 uint16_t lv_chart_get_zoom_y(const lv_obj_t * obj); 208 209 /** 210 * Set the number of tick lines on an axis 211 * @param obj pointer to a chart object 212 * @param axis an axis which ticks count should be set 213 * @param major_len length of major ticks 214 * @param minor_len length of minor ticks 215 * @param major_cnt number of major ticks on the axis 216 * @param minor_cnt number of minor ticks between two major ticks 217 * @param label_en true: enable label drawing on major ticks 218 * @param draw_size extra size required to draw the tick and labels 219 * (start with 20 px and increase if the ticks/labels are clipped) 220 */ 221 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, 222 lv_coord_t major_cnt, lv_coord_t minor_cnt, bool label_en, lv_coord_t draw_size); 223 224 /** 225 * Get the type of a chart 226 * @param obj pointer to chart object 227 * @return type of the chart (from 'lv_chart_t' enum) 228 */ 229 lv_chart_type_t lv_chart_get_type(const lv_obj_t * obj); 230 231 /** 232 * Get the data point number per data line on chart 233 * @param chart pointer to chart object 234 * @return point number on each data line 235 */ 236 uint16_t lv_chart_get_point_count(const lv_obj_t * obj); 237 238 /** 239 * Get the current index of the x-axis start point in the data array 240 * @param chart pointer to a chart object 241 * @param ser pointer to a data series on 'chart' 242 * @return the index of the current x start point in the data array 243 */ 244 uint16_t lv_chart_get_x_start_point(const lv_obj_t * obj, lv_chart_series_t * ser); 245 246 /** 247 * Get the position of a point to the chart. 248 * @param chart pointer to a chart object 249 * @param ser pointer to series 250 * @param id the index. 251 * @param p_out store the result position here 252 */ 253 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); 254 255 /** 256 * Refresh a chart if its data line has changed 257 * @param chart pointer to chart object 258 */ 259 void lv_chart_refresh(lv_obj_t * obj); 260 261 /*====================== 262 * Series 263 *=====================*/ 264 265 /** 266 * Allocate and add a data series to the chart 267 * @param obj pointer to a chart object 268 * @param color color of the data series 269 * @param axis the y axis to which the series should be attached (::LV_CHART_AXIS_PRIMARY_Y or ::LV_CHART_AXIS_SECONDARY_Y) 270 * @return pointer to the allocated data series 271 */ 272 lv_chart_series_t * lv_chart_add_series(lv_obj_t * obj, lv_color_t color, lv_chart_axis_t axis); 273 274 /** 275 * Deallocate and remove a data series from a chart 276 * @param chart pointer to a chart object 277 * @param series pointer to a data series on 'chart' 278 */ 279 void lv_chart_remove_series(lv_obj_t * obj, lv_chart_series_t * series); 280 281 /** 282 * Hide/Unhide a single series of a chart. 283 * @param obj pointer to a chart object. 284 * @param series pointer to a series object 285 * @param hide true: hide the series 286 */ 287 void lv_chart_hide_series(lv_obj_t * chart, lv_chart_series_t * series, bool hide); 288 289 /** 290 * Change the color of a series 291 * @param obj pointer to a chart object. 292 * @param series pointer to a series object 293 * @param color the new color of the series 294 */ 295 void lv_chart_set_series_color(lv_obj_t * chart, lv_chart_series_t * series, lv_color_t color); 296 297 /** 298 * Set the index of the x-axis start point in the data array. 299 * This point will be considers the first (left) point and the other points will be drawn after it. 300 * @param obj pointer to a chart object 301 * @param ser pointer to a data series on 'chart' 302 * @param id the index of the x point in the data array 303 */ 304 void lv_chart_set_x_start_point(lv_obj_t * obj, lv_chart_series_t * ser, uint16_t id); 305 306 /** 307 * Get the next series. 308 * @param chart pointer to a chart 309 * @param ser the previous series or NULL to get the first 310 * @return the next series or NULL if there is no more. 311 */ 312 lv_chart_series_t * lv_chart_get_series_next(const lv_obj_t * chart, const lv_chart_series_t * ser); 313 314 315 316 /*===================== 317 * Cursor 318 *====================*/ 319 320 /** 321 * Add a cursor with a given color 322 * @param obj pointer to chart object 323 * @param color color of the cursor 324 * @param dir direction of the cursor. `LV_DIR_RIGHT/LEFT/TOP/DOWN/HOR/VER/ALL`. OR-ed values are possible 325 * @return pointer to the created cursor 326 */ 327 lv_chart_cursor_t * lv_chart_add_cursor(lv_obj_t * obj, lv_color_t color, lv_dir_t dir); 328 329 /** 330 * Set the coordinate of the cursor with respect to the paddings 331 * @param obj pointer to a chart object 332 * @param cursor pointer to the cursor 333 * @param pos the new coordinate of cursor relative to the chart 334 */ 335 void lv_chart_set_cursor_pos(lv_obj_t * chart, lv_chart_cursor_t * cursor, lv_point_t * pos); 336 337 /** 338 * Stick the cursor to a point 339 * @param obj pointer to a chart object 340 * @param cursor pointer to the cursor 341 * @param ser pointer to a series 342 * @param point_id the point's index or `LV_CHART_POINT_NONE` to not assign to any points. 343 */ 344 void lv_chart_set_cursor_point(lv_obj_t * chart, lv_chart_cursor_t * cursor, lv_chart_series_t * ser, 345 uint16_t point_id); 346 347 /** 348 * Get the coordinate of the cursor with respect to the paddings 349 * @param obj pointer to a chart object 350 * @param cursor pointer to cursor 351 * @return coordinate of the cursor as lv_point_t 352 */ 353 lv_point_t lv_chart_get_cursor_point(lv_obj_t * chart, lv_chart_cursor_t * cursor); 354 355 /*===================== 356 * Set/Get value(s) 357 *====================*/ 358 359 /** 360 * Initialize all data points of a series with a value 361 * @param obj pointer to chart object 362 * @param ser pointer to a data series on 'chart' 363 * @param value the new value for all points. `LV_CHART_POINT_NONE` can be used to hide the points. 364 */ 365 void lv_chart_set_all_value(lv_obj_t * obj, lv_chart_series_t * ser, lv_coord_t value); 366 367 /** 368 * Set the next point's Y value according to the update mode policy. 369 * @param obj pointer to chart object 370 * @param ser pointer to a data series on 'chart' 371 * @param value the new value of the next data 372 */ 373 void lv_chart_set_next_value(lv_obj_t * obj, lv_chart_series_t * ser, lv_coord_t value); 374 375 /** 376 * Set the next point's X and Y value according to the update mode policy. 377 * @param obj pointer to chart object 378 * @param ser pointer to a data series on 'chart' 379 * @param x_value the new X value of the next data 380 * @param y_value the new Y value of the next data 381 */ 382 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); 383 384 /** 385 * Set an individual point's y value of a chart's series directly based on its index 386 * @param obj pointer to a chart object 387 * @param ser pointer to a data series on 'chart' 388 * @param id the index of the x point in the array 389 * @param value value to assign to array point 390 */ 391 void lv_chart_set_value_by_id(lv_obj_t * obj, lv_chart_series_t * ser, uint16_t id, lv_coord_t value); 392 393 /** 394 * Set an individual point's x and y value of a chart's series directly based on its index 395 * Can be used only with `LV_CHART_TYPE_SCATTER`. 396 * @param obj pointer to chart object 397 * @param ser pointer to a data series on 'chart' 398 * @param id the index of the x point in the array 399 * @param x_value the new X value of the next data 400 * @param y_value the new Y value of the next data 401 */ 402 void lv_chart_set_value_by_id2(lv_obj_t * obj, lv_chart_series_t * ser, uint16_t id, lv_coord_t x_value, 403 lv_coord_t y_value); 404 405 /** 406 * Set an external array for the y data points to use for the chart 407 * NOTE: It is the users responsibility to make sure the `point_cnt` matches the external array size. 408 * @param obj pointer to a chart object 409 * @param ser pointer to a data series on 'chart' 410 * @param array external array of points for chart 411 */ 412 void lv_chart_set_ext_y_array(lv_obj_t * obj, lv_chart_series_t * ser, lv_coord_t array[]); 413 414 /** 415 * Set an external array for the x data points to use for the chart 416 * NOTE: It is the users responsibility to make sure the `point_cnt` matches the external array size. 417 * @param obj pointer to a chart object 418 * @param ser pointer to a data series on 'chart' 419 * @param array external array of points for chart 420 */ 421 void lv_chart_set_ext_x_array(lv_obj_t * obj, lv_chart_series_t * ser, lv_coord_t array[]); 422 423 /** 424 * Get the array of y values of a series 425 * @param obj pointer to a chart object 426 * @param ser pointer to a data series on 'chart' 427 * @return the array of values with 'point_count' elements 428 */ 429 lv_coord_t * lv_chart_get_y_array(const lv_obj_t * obj, lv_chart_series_t * ser); 430 431 /** 432 * Get the array of x values of a series 433 * @param obj pointer to a chart object 434 * @param ser pointer to a data series on 'chart' 435 * @return the array of values with 'point_count' elements 436 */ 437 lv_coord_t * lv_chart_get_x_array(const lv_obj_t * obj, lv_chart_series_t * ser); 438 439 /** 440 * Get the index of the currently pressed point. It's the same for every series. 441 * @param obj pointer to a chart object 442 * @return the index of the point [0 .. point count] or LV_CHART_POINT_ID_NONE if no point is being pressed 443 */ 444 uint32_t lv_chart_get_pressed_point(const lv_obj_t * obj); 445 446 /********************** 447 * MACROS 448 **********************/ 449 450 #endif /*LV_USE_CHART*/ 451 452 #ifdef __cplusplus 453 } /*extern "C"*/ 454 #endif 455 456 #endif /*LV_CHART_H*/ 457
