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 #include "../../core/lv_obj.h" 18 19 #if LV_USE_CHART != 0 20 21 /********************* 22 * DEFINES 23 *********************/ 24 25 /**Default value of points. Can be used to not draw a point*/ 26 #define LV_CHART_POINT_NONE (INT32_MAX) 27 LV_EXPORT_CONST_INT(LV_CHART_POINT_NONE); 28 29 /********************** 30 * TYPEDEFS 31 **********************/ 32 33 /** 34 * Chart types 35 */ 36 typedef enum { 37 LV_CHART_TYPE_NONE, /**< Don't draw the series*/ 38 LV_CHART_TYPE_LINE, /**< Connect the points with lines*/ 39 LV_CHART_TYPE_BAR, /**< Draw columns*/ 40 LV_CHART_TYPE_SCATTER, /**< Draw points and lines in 2D (x,y coordinates)*/ 41 } lv_chart_type_t; 42 43 /** 44 * Chart update mode for `lv_chart_set_next` 45 */ 46 typedef 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 } lv_chart_update_mode_t; 50 51 /** 52 * Enumeration of the axis' 53 */ 54 typedef enum { 55 LV_CHART_AXIS_PRIMARY_Y = 0x00, 56 LV_CHART_AXIS_SECONDARY_Y = 0x01, 57 LV_CHART_AXIS_PRIMARY_X = 0x02, 58 LV_CHART_AXIS_SECONDARY_X = 0x04, 59 LV_CHART_AXIS_LAST 60 } lv_chart_axis_t; 61 62 LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_chart_class; 63 64 /********************** 65 * GLOBAL PROTOTYPES 66 **********************/ 67 68 /** 69 * Create a chart object 70 * @param parent pointer to an object, it will be the parent of the new chart 71 * @return pointer to the created chart 72 */ 73 lv_obj_t * lv_chart_create(lv_obj_t * parent); 74 75 /** 76 * Set a new type for a chart 77 * @param obj pointer to a chart object 78 * @param type new type of the chart (from 'lv_chart_type_t' enum) 79 */ 80 void lv_chart_set_type(lv_obj_t * obj, lv_chart_type_t type); 81 /** 82 * Set the number of points on a data line on a chart 83 * @param obj pointer to a chart object 84 * @param cnt new number of points on the data lines 85 */ 86 void lv_chart_set_point_count(lv_obj_t * obj, uint32_t cnt); 87 88 /** 89 * Set the minimal and maximal y values on an axis 90 * @param obj pointer to a chart object 91 * @param axis `LV_CHART_AXIS_PRIMARY_Y` or `LV_CHART_AXIS_SECONDARY_Y` 92 * @param min minimum value of the y axis 93 * @param max maximum value of the y axis 94 */ 95 void lv_chart_set_range(lv_obj_t * obj, lv_chart_axis_t axis, int32_t min, int32_t max); 96 97 /** 98 * Set update mode of the chart object. Affects 99 * @param obj pointer to a chart object 100 * @param update_mode the update mode 101 */ 102 void lv_chart_set_update_mode(lv_obj_t * obj, lv_chart_update_mode_t update_mode); 103 104 /** 105 * Set the number of horizontal and vertical division lines 106 * @param obj pointer to a chart object 107 * @param hdiv number of horizontal division lines 108 * @param vdiv number of vertical division lines 109 */ 110 void lv_chart_set_div_line_count(lv_obj_t * obj, uint8_t hdiv, uint8_t vdiv); 111 112 /** 113 * Get the type of a chart 114 * @param obj pointer to chart object 115 * @return type of the chart (from 'lv_chart_t' enum) 116 */ 117 lv_chart_type_t lv_chart_get_type(const lv_obj_t * obj); 118 119 /** 120 * Get the data point number per data line on chart 121 * @param obj pointer to chart object 122 * @return point number on each data line 123 */ 124 uint32_t lv_chart_get_point_count(const lv_obj_t * obj); 125 126 /** 127 * Get the current index of the x-axis start point in the data array 128 * @param obj pointer to a chart object 129 * @param ser pointer to a data series on 'chart' 130 * @return the index of the current x start point in the data array 131 */ 132 uint32_t lv_chart_get_x_start_point(const lv_obj_t * obj, lv_chart_series_t * ser); 133 134 /** 135 * Get the position of a point to the chart. 136 * @param obj pointer to a chart object 137 * @param ser pointer to series 138 * @param id the index. 139 * @param p_out store the result position here 140 */ 141 void lv_chart_get_point_pos_by_id(lv_obj_t * obj, lv_chart_series_t * ser, uint32_t id, lv_point_t * p_out); 142 143 /** 144 * Refresh a chart if its data line has changed 145 * @param obj pointer to chart object 146 */ 147 void lv_chart_refresh(lv_obj_t * obj); 148 149 /*====================== 150 * Series 151 *=====================*/ 152 153 /** 154 * Allocate and add a data series to the chart 155 * @param obj pointer to a chart object 156 * @param color color of the data series 157 * @param axis the y axis to which the series should be attached (::LV_CHART_AXIS_PRIMARY_Y or ::LV_CHART_AXIS_SECONDARY_Y) 158 * @return pointer to the allocated data series or NULL on failure 159 */ 160 lv_chart_series_t * lv_chart_add_series(lv_obj_t * obj, lv_color_t color, lv_chart_axis_t axis); 161 162 /** 163 * Deallocate and remove a data series from a chart 164 * @param obj pointer to a chart object 165 * @param series pointer to a data series on 'chart' 166 */ 167 void lv_chart_remove_series(lv_obj_t * obj, lv_chart_series_t * series); 168 169 /** 170 * Hide/Unhide a single series of a chart. 171 * @param chart pointer to a chart object. 172 * @param series pointer to a series object 173 * @param hide true: hide the series 174 */ 175 void lv_chart_hide_series(lv_obj_t * chart, lv_chart_series_t * series, bool hide); 176 177 /** 178 * Change the color of a series 179 * @param chart pointer to a chart object. 180 * @param series pointer to a series object 181 * @param color the new color of the series 182 */ 183 void lv_chart_set_series_color(lv_obj_t * chart, lv_chart_series_t * series, lv_color_t color); 184 185 /** 186 * Get the color of a series 187 * @param chart pointer to a chart object. 188 * @param series pointer to a series object 189 * @return the color of the series 190 */ 191 lv_color_t lv_chart_get_series_color(lv_obj_t * chart, const lv_chart_series_t * series); 192 193 /** 194 * Set the index of the x-axis start point in the data array. 195 * This point will be considers the first (left) point and the other points will be drawn after it. 196 * @param obj pointer to a chart object 197 * @param ser pointer to a data series on 'chart' 198 * @param id the index of the x point in the data array 199 */ 200 void lv_chart_set_x_start_point(lv_obj_t * obj, lv_chart_series_t * ser, uint32_t id); 201 202 /** 203 * Get the next series. 204 * @param chart pointer to a chart 205 * @param ser the previous series or NULL to get the first 206 * @return the next series or NULL if there is no more. 207 */ 208 lv_chart_series_t * lv_chart_get_series_next(const lv_obj_t * chart, const lv_chart_series_t * ser); 209 210 /*===================== 211 * Cursor 212 *====================*/ 213 214 /** 215 * Add a cursor with a given color 216 * @param obj pointer to chart object 217 * @param color color of the cursor 218 * @param dir direction of the cursor. `LV_DIR_RIGHT/LEFT/TOP/DOWN/HOR/VER/ALL`. OR-ed values are possible 219 * @return pointer to the created cursor 220 */ 221 lv_chart_cursor_t * lv_chart_add_cursor(lv_obj_t * obj, lv_color_t color, lv_dir_t dir); 222 223 /** 224 * Set the coordinate of the cursor with respect to the paddings 225 * @param chart pointer to a chart object 226 * @param cursor pointer to the cursor 227 * @param pos the new coordinate of cursor relative to the chart 228 */ 229 void lv_chart_set_cursor_pos(lv_obj_t * chart, lv_chart_cursor_t * cursor, lv_point_t * pos); 230 231 /** 232 * Stick the cursor to a point 233 * @param chart pointer to a chart object 234 * @param cursor pointer to the cursor 235 * @param ser pointer to a series 236 * @param point_id the point's index or `LV_CHART_POINT_NONE` to not assign to any points. 237 */ 238 void lv_chart_set_cursor_point(lv_obj_t * chart, lv_chart_cursor_t * cursor, lv_chart_series_t * ser, 239 uint32_t point_id); 240 241 /** 242 * Get the coordinate of the cursor with respect to the paddings 243 * @param chart pointer to a chart object 244 * @param cursor pointer to cursor 245 * @return coordinate of the cursor as lv_point_t 246 */ 247 lv_point_t lv_chart_get_cursor_point(lv_obj_t * chart, lv_chart_cursor_t * cursor); 248 249 /*===================== 250 * Set/Get value(s) 251 *====================*/ 252 253 /** 254 * Initialize all data points of a series with a value 255 * @param obj pointer to chart object 256 * @param ser pointer to a data series on 'chart' 257 * @param value the new value for all points. `LV_CHART_POINT_NONE` can be used to hide the points. 258 */ 259 void lv_chart_set_all_values(lv_obj_t * obj, lv_chart_series_t * ser, int32_t value); 260 261 /** 262 * Set the next point's Y value according to the update mode policy. 263 * @param obj pointer to chart object 264 * @param ser pointer to a data series on 'chart' 265 * @param value the new value of the next data 266 */ 267 void lv_chart_set_next_value(lv_obj_t * obj, lv_chart_series_t * ser, int32_t value); 268 269 /** 270 * Set the next point's X and Y value according to the update mode policy. 271 * @param obj pointer to chart object 272 * @param ser pointer to a data series on 'chart' 273 * @param x_value the new X value of the next data 274 * @param y_value the new Y value of the next data 275 */ 276 void lv_chart_set_next_value2(lv_obj_t * obj, lv_chart_series_t * ser, int32_t x_value, int32_t y_value); 277 278 /** 279 * Set an individual point's y value of a chart's series directly based on its index 280 * @param obj pointer to a chart object 281 * @param ser pointer to a data series on 'chart' 282 * @param id the index of the x point in the array 283 * @param value value to assign to array point 284 */ 285 void lv_chart_set_value_by_id(lv_obj_t * obj, lv_chart_series_t * ser, uint32_t id, int32_t value); 286 287 /** 288 * Set an individual point's x and y value of a chart's series directly based on its index 289 * Can be used only with `LV_CHART_TYPE_SCATTER`. 290 * @param obj pointer to chart object 291 * @param ser pointer to a data series on 'chart' 292 * @param id the index of the x point in the array 293 * @param x_value the new X value of the next data 294 * @param y_value the new Y value of the next data 295 */ 296 void lv_chart_set_value_by_id2(lv_obj_t * obj, lv_chart_series_t * ser, uint32_t id, int32_t x_value, 297 int32_t y_value); 298 299 /** 300 * Set an external array for the y data points to use for the chart 301 * NOTE: It is the users responsibility to make sure the `point_cnt` matches the external array size. 302 * @param obj pointer to a chart object 303 * @param ser pointer to a data series on 'chart' 304 * @param array external array of points for chart 305 */ 306 void lv_chart_set_ext_y_array(lv_obj_t * obj, lv_chart_series_t * ser, int32_t array[]); 307 308 /** 309 * Set an external array for the x data points to use for the chart 310 * NOTE: It is the users responsibility to make sure the `point_cnt` matches the external array size. 311 * @param obj pointer to a chart object 312 * @param ser pointer to a data series on 'chart' 313 * @param array external array of points for chart 314 */ 315 void lv_chart_set_ext_x_array(lv_obj_t * obj, lv_chart_series_t * ser, int32_t array[]); 316 317 /** 318 * Get the array of y values of a series 319 * @param obj pointer to a chart object 320 * @param ser pointer to a data series on 'chart' 321 * @return the array of values with 'point_count' elements 322 */ 323 int32_t * lv_chart_get_y_array(const lv_obj_t * obj, lv_chart_series_t * ser); 324 325 /** 326 * Get the array of x values of a series 327 * @param obj pointer to a chart object 328 * @param ser pointer to a data series on 'chart' 329 * @return the array of values with 'point_count' elements 330 */ 331 int32_t * lv_chart_get_x_array(const lv_obj_t * obj, lv_chart_series_t * ser); 332 333 /** 334 * Get the index of the currently pressed point. It's the same for every series. 335 * @param obj pointer to a chart object 336 * @return the index of the point [0 .. point count] or LV_CHART_POINT_ID_NONE if no point is being pressed 337 */ 338 uint32_t lv_chart_get_pressed_point(const lv_obj_t * obj); 339 340 /** 341 * Get the overall offset from the chart's side to the center of the first point. 342 * In case of a bar chart it will be the center of the first column group 343 * @param obj pointer to a chart object 344 * @return the offset of the center 345 */ 346 int32_t lv_chart_get_first_point_center_offset(lv_obj_t * obj); 347 348 /********************** 349 * MACROS 350 **********************/ 351 352 #endif /*LV_USE_CHART*/ 353 354 #ifdef __cplusplus 355 } /*extern "C"*/ 356 #endif 357 358 #endif /*LV_CHART_H*/ 359
