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