acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

chart.md (9936B)

      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/widgets/extra/chart.md
      4 ```
      5 # Chart (lv_chart)
      6 
      7 ## Overview
      8 
      9 Charts are a basic object to visualize data points. Currently *Line* charts (connect points with lines and/or draw points on them) and *Bar* charts are supported.
     10 
     11 Charts can have:
     12 - division lines
     13 - 2 y axis
     14 - axis ticks and texts on ticks
     15 - cursors
     16 - scrolling and zooming
     17 
     18 ## Parts and Styles
     19 - `LV_PART_MAIN` The background of the chart. Uses all the typical background and *line* (for the division lines) related style properties. *Padding* makes the series area smaller.
     20 - `LV_PART_SCROLLBAR` The scrollbar used if the chart is zoomed. See the [Base object](/widgets/obj)'s documentation for details.
     21 - `LV_PART_ITEMS` Refers to the line or bar series.
     22     - Line chart: The *line* properties are used by the lines. `width`, `height`, `bg_color` and `radius` is used to set the appearance of points.
     23     - Bar chart: The typical background properties are used to style the bars.
     24 - `LV_PART_INDICATOR` Refers to the points on line and scatter chart (small circles or squares).
     25 - `LV_PART_CURSOR` *Line* properties are used to style the cursors.  `width`, `height`, `bg_color` and `radius` are used to set the appearance of points.
     26 - `LV_PART_TICKS` *Line* and *Text* style properties are used to style the ticks
     27 
     28 ## Usage
     29 
     30 
     31 ### Chart type
     32 The following data display types exist:
     33 - `LV_CHART_TYPE_NONE`  Do not display any data. Can be used to hide the series.
     34 - `LV_CHART_TYPE_LINE`  Draw lines between the data points and/or points (rectangles or circles) on the data points.
     35 - `LV_CHART_TYPE_BAR` - Draw bars.
     36 - `LV_CHART_TYPE_SCATTER` - X/Y chart drawing point's and lines between the points. .
     37 
     38 You can specify the display type with `lv_chart_set_type(chart, LV_CHART_TYPE_...)`.
     39 
     40 
     41 ### Data series
     42 You can add any number of series to the charts by `lv_chart_add_series(chart, color, axis)`. This allocates an `lv_chart_series_t` structure which contains the chosen `color` and an array for the data points.
     43 `axis` can have the following values:
     44 - `LV_CHART_AXIS_PRIMARY_Y` Left axis
     45 - `LV_CHART_AXIS_SECONDARY_Y` Right axis
     46 - `LV_CHART_AXIS_PRIMARY_X` Bottom axis
     47 - `LV_CHART_AXIS_SECONDARY_X` Top axis
     48 
     49 
     50 `axis` tells which axis's range should be used te scale the values.
     51 
     52 `lv_chart_set_ext_y_array(chart, ser, value_array)` makes the chart use an external array for the given series.
     53 `value_array` should look like this: `lv_coord_t * value_array[num_points]`. The array size needs to be large enough to hold all the points of that series.
     54 The array's pointer will be saved in the chart so it needs to be global, static or dynamically allocated.
     55 Note: you should call `lv_chart_refresh(chart)` after the external data source has been updated to update the chart.
     56 
     57 The value array of a series can be obtained with `lv_chart_get_y_array(chart, ser)`, which can be used with `ext_array` or *normal array*s.
     58 
     59 For `LV_CHART_TYPE_SCATTER` type  `lv_chart_set_ext_x_array(chart, ser, value_array)` and `lv_chart_get_x_array(chart, ser)` can be used as well.
     60 
     61 ### Modify the data
     62 You have several options to set the data of series:
     63 1. Set the values manually in the array like `ser1->points[3] = 7` and refresh the chart with `lv_chart_refresh(chart)`.
     64 2. Use `lv_chart_set_value_by_id(chart, ser, id, value)` where `id` is the index of the point you wish to update.
     65 3. Use the `lv_chart_set_next_value(chart, ser, value)`.
     66 4. Initialize all points to a given value with: `lv_chart_set_all_value(chart, ser, value)`.
     67 
     68 Use `LV_CHART_POINT_NONE` as value to make the library skip drawing that point, column, or line segment.
     69 
     70 For `LV_CHART_TYPE_SCATTER` type  `lv_chart_set_value_by_id2(chart, ser, id, value)` and `lv_chart_set_next_value2(chart, ser, x_valuem y_value)` can be used as well.
     71 
     72 
     73 ### Update modes
     74 `lv_chart_set_next_value` can behave in two ways depending on *update mode*:
     75 - `LV_CHART_UPDATE_MODE_SHIFT` Shift old data to the left and add the new one to the right.
     76 - `LV_CHART_UPDATE_MODE_CIRCULAR` - Add the new data in circular fashion, like an ECG diagram.
     77 
     78 The update mode can be changed with `lv_chart_set_update_mode(chart, LV_CHART_UPDATE_MODE_...)`.
     79 
     80 ### Number of points
     81 The number of points in the series can be modified by `lv_chart_set_point_count(chart, point_num)`. The default value is 10.
     82 Note: this also affects the number of points processed when an external buffer is assigned to a series, so you need to be sure the external array is large enough.
     83 
     84 #### Handling large number of points
     85 On line charts, if the number of points is greater than the pixels horizontally, the Chart will draw only vertical lines to make the drawing of large amount of data effective.
     86 If there are, let's say, 10 points to a pixel, LVGL searches the smallest and the largest value and draws a vertical lines between them to ensure no peaks are missed.
     87 
     88 ### Vertical range
     89 You can specify the minimum and maximum values in y-direction with `lv_chart_set_range(chart, axis, min, max)`.
     90 `axis` can be `LV_CHART_AXIS_PRIMARY` (left axis) or `LV_CHART_AXIS_SECONDARY` (right axis).
     91 
     92 The value of the points will be scaled proportionally. The default range is: 0..100.
     93 
     94 ### Division lines
     95 The number of horizontal and vertical division lines can be modified by `lv_chart_set_div_line_count(chart, hdiv_num, vdiv_num)`.
     96 The default settings are 3 horizontal and 5 vertical division lines.
     97 If there is a visible border on a side and no padding on that side, the division line would be drawn on top of the border and therefore it won't be drawn.
     98 
     99 ### Override default start point for series
    100 If you want a plot to start from a point other than the default which is `point[0]` of the series, you can set an alternative
    101 index with the function `lv_chart_set_x_start_point(chart, ser, id)` where `id` is the new index position to start plotting from.
    102 
    103 Note that `LV_CHART_UPDATE_MODE_SHIFT` also changes the `start_point`.
    104 
    105 ### Tick marks and labels
    106 Ticks and labels can be added to the axis with `lv_chart_set_axis_tick(chart, axis, major_len, minor_len, major_cnt, minor_cnt, label_en, draw_size)`.
    107 - `axis` can be `LV_CHART_AXIS_X/PRIMARY_Y/SECONDARY_Y`
    108 - `major_len` is the length of major ticks
    109 - `minor_len` is the length of minor ticks
    110 - `major_cnt` is the number of major ticks on the axis
    111 - `minor_cnt` in the number of minor ticks between two major ticks
    112 - `label_en` `true`: enable label drawing on major ticks
    113 - `draw_size` extra size required to draw the tick and labels (start with 20 px and increase if the ticks/labels are clipped)
    114 
    115 ### Zoom
    116 The chart can be zoomed independently in x and y directions with `lv_chart_set_zoom_x(chart, factor)` and `lv_chart_set_zoom_y(chart, factor)`.
    117 If `factor` is 256 there is no zoom. 512 means double zoom, etc. Fractional values are also possible but < 256 value is not allowed.
    118 
    119 
    120 ### Cursor
    121 
    122 A cursor can be added with `lv_chart_cursor_t * c1 = lv_chart_add_cursor(chart, color, dir);`.
    123 The possible values of `dir`  `LV_DIR_NONE/RIGHT/UP/LEFT/DOWN/HOR/VER/ALL` or their OR-ed values to tell in which direction(s) should the cursor be drawn.
    124 
    125 `lv_chart_set_cursor_pos(chart, cursor, &point)` sets the position of the cursor.
    126 `pos` is a pointer to an `lv_point_t` variable. E.g. `lv_point_t point = {10, 20};`. If the chart is scrolled the cursor will remain in the same place.
    127 
    128 `lv_chart_get_point_pos_by_id(chart, series, id, &point_out)` gets the coordinate of a given point. It's useful to place the cursor at a given point.
    129 
    130 `lv_chart_set_cursor_point(chart, cursor, series, point_id)` sticks the cursor at a point. If the point's position changes (new value or scrolling) the cursor will move with the point.
    131 
    132 ## Events
    133 - `LV_EVENT_VALUE_CHANGED` Sent when a new point is clicked pressed.  `lv_chart_get_pressed_point(chart)` returns the zero-based index of the pressed point.
    134 - `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent with the following types:
    135    - `LV_CHART_DRAW_PART_DIV_LINE_INIT`  Used before/after drawn the div lines to add masks to any extra drawings. The following fields are set:
    136        -  `part`: `LV_PART_MAIN`
    137        - `line_dsc`
    138    - `LV_CHART_DRAW_PART_DIV_LINE_HOR`, `LV_CHART_DRAW_PART_DIV_LINE_VER` Used for each horizontal and vertical division lines.
    139        - `part`: `LV_PART_MAIN`
    140        - `id`: index of the line
    141        - `p1`, `p2`: points of the line
    142        - `line_dsc`
    143    - `LV_CHART_DRAW_PART_LINE_AND_POINT` Used on line and scatter charts for lines and points.
    144        - `part`: `LV_PART_ITEMS`
    145        - `id`: index of the point
    146        - `value`: value of `id`th point
    147        - `p1`, `p2`: points of the line
    148        - `draw_area`: area of the point
    149        - `line_dsc`
    150        - `rect_dsc`
    151        - `sub_part_ptr`: pointer to the series
    152    - `LV_CHART_DRAW_PART_BAR` Used on bar charts for the rectangles.
    153         - `part`: `LV_PART_ITEMS`
    154         - `id`: index of the point
    155         - `value`: value of `id`th point
    156         - `draw_area`: area of the point
    157         - `rect_dsc`:
    158         - `sub_part_ptr`: pointer to the series
    159    - `LV_CHART_DRAW_PART_CURSOR`  Used on cursor lines and points.
    160         - `part`: `LV_PART_CURSOR`
    161         - `p1`, `p2`: points of the line
    162         - `line_dsc`
    163         - `rect_dsc`
    164         - `draw_area`: area of the points
    165    - `LV_CHART_DRAW_PART_TICK_LABEL`  Used on tick lines and labels.
    166         - `part`: `LV_PART_TICKS`
    167         - `id`: axis
    168         - `value`: value of the tick
    169         - `text`: `value` converted to decimal or `NULL` for minor ticks
    170         - `line_dsc`,
    171         - `label_dsc`,
    172 
    173 See the events of the [Base object](/widgets/obj) too.
    174 
    175 Learn more about [Events](/overview/event).
    176 
    177 ## Keys
    178 No *Keys* are processed by the object type.
    179 
    180 Learn more about [Keys](/overview/indev).
    181 
    182 ## Example
    183 
    184 ```eval_rst
    185 
    186 .. include:: ../../../examples/widgets/chart/index.rst
    187 
    188 ```
    189 
    190 ## API
    191 
    192 ```eval_rst
    193 
    194 .. doxygenfile:: lv_chart.h
    195   :project: lvgl
    196 
    197 ```