github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

dics add calendar, chart, colorpicker

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi
2021-05-17 15:37:35 +02:00
parent 7d26d10c3b
commit 5ca2481aa2
4 changed files with 169 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/widgets/extra/calendar.md
View File

@@ -1,6 +1,6 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/calendar.md
:github_url: |github_link_base|/widgets/extra/calendar.md
```
# Calendar (lv_calendar)
@@ -9,28 +9,28 @@
The Calendar object is a classic calendar which can:
- can show the days of any month in a 7x7 matrix
- Show the name of the days
- highlight the current day
- highlight the current day (today)
- highlight any user-defined dates
The Calendar is added to the deafult group (if it is set). Besides the Calendar is an editable object to allow selecting and clicing the dates with encoder navigation too.
The Calendar is added to the default group (if it is set). Besides the Calendar is an editable object to allow selecting and clicking the dates with encoder navigation too.
To make the Calendar flexible, by default it doesn't show the curent year or month. Instead, there external "headers" that can be attached to the calendar.
To make the Calendar flexible, by default it doesn't show the current year or month. Instead, there area external "headers" that can be attached to the calendar.
## Parts and Styles
The calendar object uses the [Button matrix](/widgets/btnmatrix) object under the hood to arrange the days into a matrix.
- `LV_PART_MAIN`
- `LV_PART_ITEMS` Refers to the dates and day names. Button matrix control flags are set the to differentiate the buttons and a custom drawer event modifies the properties of the buttons
- day names haev no border, no background, drawn with a grey color
The calendar object uses the [Button matrix](/widgets/core/btnmatrix) object under the hood to arrange the days into a matrix.
- `LV_PART_MAIN` The background of the calendar. It uses all the background related style properties.
- `LV_PART_ITEMS` Refers to the dates and day names. Button matrix control flags are set the to differentiate the buttons and a custom drawer event is added modify the properties of the buttons
- day names have no border, no background and drawn with a gray color
- days of the previous and next month have `LV_BTNMATRIX_CTRL_DISABLED` flag
- today has a ticker border with the themes primary color
- highlighted day have 40% opacity with the themes primary color.
- highlighted day have some opacity with the themes primary color.
## Usage
Some funnctions uses the `lv_calendar_date_t` type is used which is a structure with `year`, `month` and `day` fields.
Some functions uses the `lv_calendar_date_t` type which is a structure with `year`, `month` and `day` fields.
### Current date
To set the current date (today), use the `lv_calendar_set_today_date(calendar, year, month, day)` function. `month` needs to be in 1..12 range and `day` in 1..31 range
To set the current date (today), use the `lv_calendar_set_today_date(calendar, year, month, day)` function. `month` needs to be in 1..12 range and `day` in 1..31 range.
### Shown date
To set the shown date, use `lv_calendar_set_shown_date(calendar, year, month)`;
@@ -42,31 +42,36 @@ Only the arrays pointer will be saved so the array should be a static or global
### Name of the days
The name of the days can be adjusted with `lv_calendar_set_day_names(calendar, day_names)` where `day_names` looks like `const char * day_names[7] = {"Su", "Mo", ...};`
Only the pointer of the day names is saved so the array should be a static, global or constant variables.
Only the pointer of the day names is saved so the elements should be static, global or constant variables.
## Headers
### Arrow buttons
`lv_calendar_header_arrow_create(parent, calendar, button_size)` creates a header that contains a left and right arrow on the sides and atext with the current year and month between them.
### Dropdown
`lv_calendar_header_dropdown_create(parent, calendar)` creates a header that contains 2 drop-drown lists: one for the year and an other for the month.
## Events
- `LV_EVENT_VALUE_CHANGED` Sent is a data is clicked. `lv_calendar_get_pressed_date(calendar, &date)` tells which day is currently being pressed. Returns `LV_RES_OK` if theres is valid pressed data, else `LV_RES_INV`.
Learn more about [vent](/overview/event).
## Keys
- `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons to dates
- `LV_KEY_ENTER` To press/release the selected date
Learn more about [Keys](/overview/indev).
## Headers
### Arrow buttons
`lv_calendar_header_arrow_create(parent, calendar, button_size)` creates a header that contains a left and right arrow on the sides and a text with the current year and month between them.
### Drop-down
`lv_calendar_header_dropdown_create(parent, calendar)` creates a header that contains 2 drop-drown lists: one for the year and an other for the month.
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_calendar/index.rst
.. include:: ../../../examples/widgets/calendar/index.rst
```

161
docs/widgets/extra/chart.md
View File

@@ -1,128 +1,131 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/chart.md
:github_url: |github_link_base|/widgets/extra/chart.md
```
# Chart (lv_chart)
## Overview
Charts are a basic object to visualize data points.
They support *Line* charts (connect points with lines and/or draw points on them) and *Column* charts.
They support *Line* charts (connect points with lines and/or draw points on them) and *Bar* charts.
Charts also support division lines, 2 y axis, axis ticks, and texts on ticks.
Charts also support:
- division lines
- 2 y axis
- axis ticks and texts on ticks
- cursors
- scrolling and zooming
## Parts and Styles
The Chart's main part is called `LV_CHART_PART_BG` and it uses all the typical background properties.
The *text* style properties determine the style of the axis texts and the *line* properties determine ticks' style.
*Padding* values add some space on the sides thus it makes the *series area* smaller. Padding also can be used to make space for axis texts and ticks.
The background of the series is called `LV_CHART_PART_SERIES_BG` and it's placed on the main background.
The division lines, and series data is drawn on this part. Besides the typical background style properties
the *line* style properties are used by the division lines. The *padding* values tells the space between the this part and the axis texts.
The style of the series can be referenced by `LV_CHART_PART_SERIES`. In case of column type the following properties are used:
- *radius*: radius of the bars
- *padding_inner*: space between the columns of the same x coordinate
In case of Line type these properties are used:
- *line properties* to describe the lines
- *size* radius of the points
- *bg_opa*: the overall opacity of the area below the lines
- *bg_main_stop*: % of *bg_opa* at the top to create an alpha fade (0: transparent at the top, 255: *bg_opa* at the top)
- *bg_grad_stop*: % of *bg_opa* at the bottom to create an alpha fade (0: transparent at the bottom, 255: *bg_opa* at the top)
- *bg_drag_dir*: should be `LV_GRAD_DIR_VER` to allow alpha fading with *bg_main_stop* and *bg_grad_stop*
`LV_CHART_PART_CURSOR` refres to the cursors. Any number of cursor can be added and their appearence can be set by the line related style properties. The color of the cursors are set when the cursor is created and `line_color` fro mteh style is overwritten by this value.
- `LV_PART_MAIN` The background of the chart. It uses all the typical background related style properties and *line* properties for teh division lines. *Padding* makes the series area smaller.
- `LV_PART_SCROLLBAR` The scrollbar used if the chart is zoomed. See the [Base object](/widgets/obj)'s documentation for details.
- `LV_PART_ITEMS` Refers to the line or bar series.
- Line chart: The *line* properties are used by the lines. `width`, `height`, `bg_color` and `radius` is used to set the appearance of points.
- Bar chart: The typical background properties are used to style the bars.
- `LV_PART_CURSOR` *Line* properties are used to styke the cursors. `width`, `height`, `bg_color` and `radius` is used to set the appearance of points.
- `LV_PART_TICKS` *Line* and *Text* style properties are used to style the ticks
## Usage
### Data series
You can add any number of series to the charts by `lv_chart_add_series(chart, color)`.
It allocates data for a `lv_chart_series_t` structure which contains the chosen `color` and an array for the data points if
not using an external array, if an external array is assigned any internal points associated with the series are deallocated
and the series points to the external array instead.
You can add any number of series to the charts by `lv_chart_add_series(chart, color, LV_CHART_AXIS_PRIMARY/SECONDARY)`.
It allocates data for a `lv_chart_series_t` structure which contains the chosen `color` and an array for the data points.
`LV_CHART_AXIS_PRIMARY/SECONDARY` tells series should use the range of the `LV_CHART_AXIS_PRIMARY` (left) or `LV_CHART_AXIS_SECONDARY` (right) Y axis.
With `lv_chart_set_ext_array(chart, ser, value_array)` makes the chart use an external array for the given series.
`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.
The array's pointer will be saved in the chart so it needs to be global, static or dynamically allocated.
Note: you should call `lv_chart_refresh(chart)` after the external data source has been updated, to update the chart.
The value array of a series can be get by `lv_chart_get_array(chart, ser)`. It can be use with `ext_array` or *normal array*s.
### Series' type
The following **data display types** exist:
- **LV_CHART_TYPE_NONE** - Do not display any data. It can be used to hide the series.
- **LV_CHART_TYPE_LINE** - Draw lines between the points.
- **LV_CHART_TYPE_COLUMN** - Draw columns.
The following data display types exist:
- `LV_CHART_TYPE_NONE` Do not display any data. It can be used to hide the series.
- `LV_CHART_TYPE_LINE` Draw lines between the data points and/or points (rectangles or circles) on the data points.
- `LV_CHART_TYPE_BAR` - Draw bars.
You can specify the display type with `lv_chart_set_type(chart, LV_CHART_TYPE_...)`. The types can be 'OR'ed (like `LV_CHART_TYPE_LINE`).
### Modify the data
You have several options to set the data of series:
1. Set the values manually in the array like `ser1->points[3] = 7` and refresh the chart with `lv_chart_refresh(chart)`.
2. Use `lv_chart_set_point_id(chart, ser, value, id)` where id is the index of the point you wish to update.
3. Use the `lv_chart_set_next(chart, ser, value)`.
4. Initialize all points to a given value with: `lv_chart_init_points(chart, ser, value)`.
5. Set all points from an array with: `lv_chart_set_points(chart, ser, value_array)`.
2. Use `lv_chart_set_value_by_id(chart, ser, value, id)` where `id` is the index of the point you wish to update.
3. Use the `lv_chart_set_next_value(chart, ser, value)`.
4. Initialize all points to a given value with: `lv_chart_set_all_value(chart, ser, value)`.
Use `LV_CHART_POINT_DEF` as value to make the library skip drawing that point, column, or line segment.
### Override default start point for series
If you wish a plot to start from a point other than the default which is point[0] of the series, you can set an alternative
index with the function `lv_chart_set_x_start_point(chart, ser, id)` where id is the new index position to start plotting from.
### Set an external data source
You can make the chart series update from an external data source by assigning it with the function:
`lv_chart_set_ext_array(chart, ser, array, point_cnt )` where array is an external array of lv_coord_t with point_cnt elements.
Note: you should call `lv_chart_refresh(chart)` after the external data source has been updated, to update the chart.
### Get current chart information
There are four functions to get information about a chart:
1. `lv_chart_get_type(chart)` returns the current chart type.
2. `lv_chart_get_point_count(chart)` returns the current chart point count.
3. `lv_chart_get_x_start_point(ser)` returns the current plotting index for the specified series.
4. `lv_chart_get_point_id(chart, ser, id)` returns the value of the data at a particular index(id) for the specified series.
### Update modes
`lv_chart_set_next` can behave in two ways depending on *update mode*:
- **LV_CHART_UPDATE_MODE_SHIFT** - Shift old data to the left and add the new one o the right.
- **LV_CHART_UPDATE_MODE_CIRCULAR** - Circularly add the new data (Like an ECG diagram).
`lv_chart_set_next_value` can behave in two ways depending on *update mode*:
- `LV_CHART_UPDATE_MODE_SHIFT` Shift old data to the left and add the new one o the right.
- `LV_CHART_UPDATE_MODE_CIRCULAR` - Circularly add the new data (Like an ECG diagram).
The update mode can be changed with `lv_chart_set_update_mode(chart, LV_CHART_UPDATE_MODE_...)`.
### Number of points
The number of points in the series can be modified by `lv_chart_set_point_count(chart, point_num)`. The default value is 10.
Note: this also affects the number of points processed when an external buffer is assigned to a series.
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.
#### Handling large number of points
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.
If there are let's say 10 point a pixel, LVGL searches the smallest and the greatest value and draws a vertical lines between them. It ensures to not miss any peaks.
### Vertical range
You can specify the minimum and maximum values in y-direction with `lv_chart_set_range(chart, y_min, y_max)`. The value of the points will be scaled proportionally. The default range is: 0..100.
You can specify the minimum and maximum values in y-direction with `lv_chart_set_range(chart, axis, min, max)`.
`axis` can be `LV_CHART_AXIS_PRIMARY` (left axis) or `LV_CHART_AXIS_SECONDARY` (right axis).
The value of the points will be scaled proportionally. The default range is: 0..100.
### Division lines
The number of horizontal and vertical division lines can be modified by `lv_chart_set_div_line_count(chart, hdiv_num, vdiv_num)`. The default settings are 3 horizontal and 5 vertical division lines.
The number of horizontal and vertical division lines can be modified by `lv_chart_set_div_line_count(chart, hdiv_num, vdiv_num)`.
The default settings are 3 horizontal and 5 vertical division lines.
If the there is visible border on a side and there is not padding on that side the division line would be drawn on top the border, therefore on it won't be drawn.
### Override default start point for series
If you wish a plot to start from a point other than the default which is `point[0]` of the series, you can set an alternative
index with the function `lv_chart_set_x_start_point(chart, ser, id)` where `id` is the new index position to start plotting from.
Note that `LV_CHART_UPDATE_MODE_SHIFT` also changes the `start_point`.
### Tick marks and labels
Ticks and labels can be added to the axis.
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)`.
- `axis` can be `LV_CHART_AXIS_X/PRIMARY_Y/SECONDARY_Y`
- `major_len` is the length of major ticks
- `minor_len` is the length of minor ticks
- `major_cnt` is the number of major ticks on the axis
- `minor_cnt` in the number of minor ticks between two major ticks
- `label_en` `true`: enable label drawing on major ticks
- `draw_size` extra size required to draw the tick and labels (start with 20 px and increase if the ticks/labels are clipped)
`lv_chart_set_x_tick_text(chart, list_of_values, num_tick_marks, LV_CHART_AXIS_...)` set the ticks and texts on x axis.
`list_of_values` is a string with `'\n'` terminated text (expect the last) with text for the ticks. E.g. `const char * list_of_values = "first\nsec\nthird"`. `list_of_values` can be `NULL`.
If `list_of_values` is set then `num_tick_marks` tells the number of ticks between two labels. If `list_of_values` is `NULL` then it specifies the total number of ticks.
### Zoom
The chart can be zoom independently in x and y directions with `lv_chart_set_zoom_x(chart, factor)` and `lv_chart_set_zoom_y(chart, factor)`.
If `factor` is 256 there is no zoom. 512 means double zoom, etc. Fractional values are also possible but < 256 value is not allowed.
*Major tick lines* are drawn where text is placed, and *minor tick lines* are drawn elsewhere. `lv_chart_set_x_tick_length(chart, major_tick_len, minor_tick_len)` sets the length of tick lines on the x-axis.
The same functions exists for the y axis too: `lv_chart_set_y_tick_text` and `lv_chart_set_y_tick_length`.
### Cursor
A cursor can be added with `lv_chart_cursor_t * c1 = lv_chart_add_cursor(chart, color, dir);`. The possible values of `dir` `LV_CHART_CURSOR_NONE/RIGHT/UP/LEFT/DOWN` or their OR-ed values to tell in which direction(s) should the cursor be drawn.
A cursor can be added with `lv_chart_cursor_t * c1 = lv_chart_add_cursor(chart, color, dir);`.
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.
`lv_chart_set_cursor_point(chart, cursor, &point)` sets the position of the cursor. `point` is a pointer to an `lv_poin_t` variable. E.g. `lv_point_t point = {10, 20};`. The point is relative to the series area of the chart.
The `lv_coord_t p_index = lv_chart_get_nearest_index_from_coord(chart, x)` tells which point index is to the closest to a X coordinate (relative to the series area). It can be used to snap the cursor to a point for example when the chart is clicked.
`lv_chart_get_x_from_index(chart, series, id)` and `lv_chart_get_y_from_index(chart, series, id)` tells the X and Y coordinate of a given point. It's useful to place the cursor to given point.
The current series area can be retrieved with `lv_chart_get_series_area(chart, &area)` where `area` is a pointer to an `lv_area_t` variable to store the result. The area has absolute coordinates.
`lv_chart_set_cursor_point(chart, cursor, &point)` sets the position of the cursor.
`point` is a pointer to an `lv_poin_t` variable. E.g. `lv_point_t point = {10, 20};`.
`lv_chart_get_point_pos_by_id(chart, series, id, &point_out)` tells the coordinate of a given point. It's useful to place the cursor to given point.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for multiple parts. The fields of `lv_obj_draw_part_dsc_t` is set as the followings:
- `LV_PART_ITEMS` (the series)
- *Line chart* `clip_area`, `id` (index of the point), `value` (value of `id`th point), `p1`, `p2` (points of the line), `draw_area` (area of the point), `line_dsc`, `rect_dsc`, `sub_part_ptr` (pointer to the series), `part`
- *Bar chart* `clip_area`, `id` (index of the point), `value` (value of `id`th point), `draw_area` (area of the point), `rect_dsc`, `sub_part_ptr` (pointer to the series), `part`
- `LV_PART_TICKS` (major tick lines and label) `clip_area`, `id` (axis), `value` (scaled value of the tick), `text` (`value` converted to decimal), `line_dsc`, `label_dsc`, `part`
- `LV_PART_CURSOR` Te events are send for 3 times:
- vertical line `clip_area`, `p1`, `p2` (points of the line), `line_dsc`, `part`
- horizontal line `clip_area`, `p1`, `p2` (points of the line), `line_dsc`, `part`
- point `clip_area`, `draw_area` (points of the line), `rect_dsc`, `part`
- `LV_PART_MAIN` (the division lines) `clip_area`, `id` (index of the line), `p1`, `p2` (points of the line), `line_dsc`, `part`
Learn more about [Events](/overview/event).
## Keys
@@ -134,7 +137,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_chart/index.rst
.. include:: ../../../examples/widgets/lv_example_chart/index.rst
```

60
docs/widgets/extra/colorwheel.md Normal file
View File

@@ -0,0 +1,60 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/extra/colorwheel.md
```
# Color wheel (lv_colorwheel)
## Overview
As its name implies *Color wheel* allows to select color. The Hue, Saturation and Value of the color can be selected after each other.
Long pressing the object, the color wheel will change to the next parameter of the color (hue, saturation or value).
Besides, double click will reset the current parameter.
## Parts and Styles
- `LV_PART_MAIN` Only `arc_width` is used to set the width of the color wheel
- `LV_PART_KNOB` A rectangle (or circle) drawn on the current value. It uses all the rectangle like style properties and padding to make it larger than the width of the arc.
## Usage
### Create a color wheel
`lv_colorwheel_create(parent, knob_recolor)` creates a new color wheel. With `knob_recolor=true` the knob's background color will be set to the current color.
### Set color
The color can be set manually with `lv_colorwheel_set_hue/saturation/value(colorwheel, x)` or all at once with `lv_colorwheel_set_hsv(colorwheel, hsv)` or `lv_colorwheel_set_color(colorwheel, rgb)`
### Color mode
The current color mode can be manually selected with `lv_colorwheel_set_color_mode(colorwheel, LV_COLORWHEEL_MODE_HUE/SATURATION/VALUE)`.
The color mode be fixed (do not change with long press) using `lv_colorwheel_set_color_mode_fixed(colorwheel, true)`
## Events
- `LV_EVENT_VALUE_CHANGED` Sent if a new color is selected.
Learn more about [Events](/overview/event).
## Keys
- `LV_KEY_UP`, `LV_KEY_RIGHT` Increment the current parameter's value by 1
- `LV_KEY_DOWN`, `LV_KEY_LEFT` Decrement the current parameter's by 1
- `LV_KEY_ENTER` By long press the next mode will be shown. By double click the current parameter will be reset.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: ../../../examples/widgets/lv_example_colorwheel/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_colorwheel.h
:project: lvgl
```

69
docs/widgets/extra/cpicker.md
View File

@@ -1,69 +0,0 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/cpicker.md
```
# color picker (lv_cpicker)
## Overview
As its name implies *Color picker* allows to select color. The Hue, Saturation and Value of the color can be selected after each other.
The widget has two forms: circle (disc) and rectangle.
In both forms, be long pressing the object, the color picker will change to the next parameter of the color (hue, saturation or value).
Besides, double click will reset the current parameter.
## Parts and Styles
The Color picker's main part is called `LV_CPICKER_PART_BG`. In circular form it uses *scale_width* to set the the width of the circle and *pad_inner* for padding between the circle and the inner preview circle.
In rectangle mode *radius* can be used to apply a radius on the rectangle.
The object has virtual part called `LV_CPICKER_PART_KNOB` which is rectangle (or circle) drawn on the current value.
It uses all the rectangle like style properties and padding to make it larger than the width of the circle or rectangle background.
## Usage
### Type
The type of the Color picker can be changed with `lv_cpicker_set_type(cpicker, LV_CPICKER_TYPE_RECT/DISC)`
### Set color
The colro can be set manually with `lv_cpicker_set_hue/saturation/value(cpicker, x)` or all at once with `lv_cpicker_set_hsv(cpicker, hsv)` or `lv_cpicker_set_color(cpicker, rgb)`
### Color mode
The current color moed can be manually selected with `lv_cpicker_set_color_mode(cpicker, LV_CPICKER_COLOR_MODE_HUE/SATURATION/VALUE)`.
The color moe be fixed (do not change with long press) using `lv_cpicker_set_color_mode_fixed(cpicker, true)`
### Knob color
`lv_cpicker_set_knob_colored(cpicker, true)` make the knob to automatically show the selected color as background color.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
- **LV_KEY_UP**, **LV_KEY_RIGHT** Increment the current parameter's value by 1
- **LV_KEY_DOWN**, **LV_KEY_LEFT** Decrement the current parameter's by 1
- **LV_KEY_ENTER** By long press the next mode will be shown. By double click the current parameter will be reset.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_cpicker/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_cpicker.h
:project: lvgl
```