mirror of
https://github.com/lvgl/lvgl.git
synced 2024-11-26 19:23:46 +08:00
feat(docs): batch 4 of proofread/edited docs (#7207)
Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com>
This commit is contained in:
Victor Wheeler
GitHub
parent
234ce5ef36
commit
a875298f7a
@ -7,18 +7,22 @@ Calendar (lv_calendar)
|
||||
Overview
|
||||
********
|
||||
|
||||
The Calendar Widget is a classic calendar which can: - show the days of
|
||||
any month in a 7x7 matrix - Show the name of the days - highlight the
|
||||
current day (today) - highlight any user-defined dates
|
||||
The Calendar Widget is a classic calendar which can:
|
||||
|
||||
The Calendar is added to the default group (if it is set). Calendar is
|
||||
- show the days of any month in a 7x7 matrix;
|
||||
- show the name of the days;
|
||||
- highlight the current day (today);
|
||||
- highlight any user-defined dates.
|
||||
|
||||
The Calendar is added to the default group (if one is set). Calendar is
|
||||
an editable Widget which allow selecting and clicking the dates with
|
||||
encoder navigation as well.
|
||||
encoder or keyboard navigation as well as pointer-type input devices.
|
||||
|
||||
To make the Calendar flexible, by default it doesn't show the current
|
||||
To make the Calendar flexible, by default it does not show the current
|
||||
year or month. Instead, there are optional "headers" that can be
|
||||
attached to the calendar.
|
||||
|
||||
|
||||
.. _lv_calendar_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
@ -27,14 +31,15 @@ Parts and Styles
|
||||
The calendar Widget uses the :ref:`Button Matrix <lv_buttonmatrix>`
|
||||
Widget under the hood to arrange the days into a matrix.
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the calendar. Uses all the background related style properties.
|
||||
- :cpp:enumerator:`LV_PART_ITEMS` Refers to the dates and day names. Button matrix control flags are set to differentiate the
|
||||
- :cpp:enumerator:`LV_PART_MAIN` Calendar background. Uses all the background-related style properties.
|
||||
- :cpp:enumerator:`LV_PART_ITEMS` Refers to dates and day names. Button matrix control flags are set to differentiate the
|
||||
buttons and a custom drawer event is added modify the properties of the buttons as follows:
|
||||
|
||||
- day names have no border, no background and drawn with a gray color
|
||||
- days of the previous and next month have :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_DISABLED` flag
|
||||
- day names have no border, no background and are drawn with a gray color
|
||||
- days of the previous and next month have the :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_DISABLED` flag
|
||||
- today has a thicker border with the theme's primary color - highlighted days have some opacity with the theme's primary color.
|
||||
|
||||
|
||||
.. _lv_calendar_usage:
|
||||
|
||||
Usage
|
||||
@ -50,37 +55,41 @@ To set the current date (today), use the
|
||||
:cpp:expr:`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
|
||||
----------
|
||||
Month shown
|
||||
-----------
|
||||
|
||||
To set the shown date, use
|
||||
:cpp:expr:`lv_calendar_set_shown_date(calendar, year, month)`
|
||||
:cpp:expr:`lv_calendar_set_showed_date(calendar, year, month)`
|
||||
|
||||
Highlighted days
|
||||
----------------
|
||||
|
||||
The list of highlighted dates should be stored in a
|
||||
:cpp:struct:`lv_calendar_date_t` array loaded by
|
||||
:cpp:struct:`lv_calendar_date_t` array and applied to the Calendar by calling
|
||||
:cpp:expr:`lv_calendar_set_highlighted_dates(calendar, highlighted_dates, date_num)`.
|
||||
Only the array's pointer will be saved so the array should be a static
|
||||
or global variable.
|
||||
Only the array's pointer will be saved so the array should be have static or
|
||||
global scope.
|
||||
|
||||
Name of the days
|
||||
----------------
|
||||
Names of days
|
||||
-------------
|
||||
|
||||
The name of the days can be adjusted with
|
||||
The names of the days can be adjusted with
|
||||
:cpp:expr:`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 elements should be static,
|
||||
global or constant variables.
|
||||
pointer of the day names is saved so the array should have static or
|
||||
global scope.
|
||||
|
||||
Custom year list
|
||||
----------------
|
||||
|
||||
Sets a custom year list with :cpp:expr:`lv_calendar_header_dropdown_set_year_list(calendar, years_list)`
|
||||
Set a custom year list with :cpp:expr:`lv_calendar_header_dropdown_set_year_list(calendar, years_list)`
|
||||
where ``years_list`` is a pointer to the custom years list. It can be a constant string
|
||||
like ``static const char * years = "2023\n2022\n2021\n2020\n2019";``,
|
||||
or can be generated dynamically into a buffer as well.
|
||||
or can be generated dynamically into a buffer as well. Calendar stores these in a
|
||||
Drop-Down List Widget via :cpp:func:`lv_dropdown_set_options` so the passed string
|
||||
pointer can be supplied by a local variable or buffer and does not need to persist
|
||||
beyond the call.
|
||||
|
||||
|
||||
Chinese calendar
|
||||
----------------
|
||||
@ -105,9 +114,9 @@ Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent if a date is clicked.
|
||||
:cpp:expr:`lv_calendar_get_pressed_date(calendar, &date)` set ``date`` to the
|
||||
:cpp:expr:`lv_calendar_get_pressed_date(calendar, &date)` to set ``date`` to the
|
||||
date currently being pressed. Returns :cpp:enumerator:`LV_RESULT_OK` if there is a
|
||||
valid pressed date, else :cpp:enumerator:`LV_RESULT_INVALID`.
|
||||
valid pressed date; otherwise it returns :cpp:enumerator:`LV_RESULT_INVALID`.
|
||||
|
||||
|
||||
.. admonition:: Further Reading
|
||||
@ -137,21 +146,21 @@ Keys
|
||||
Headers
|
||||
*******
|
||||
|
||||
**From v8.1 the header is added directly into the Calendar widget and
|
||||
**From LVGL v8.1 onward, the header is added directly into the Calendar Widget and
|
||||
the API of the headers has been changed.**
|
||||
|
||||
Arrow buttons
|
||||
-------------
|
||||
|
||||
:cpp:expr:`lv_calendar_header_arrow_create(calendar)` creates a header that
|
||||
contains a left and right arrow on the sides and a text with the current
|
||||
year and month between them.
|
||||
contains a left and right arrow on the sides and text between the arrows showing the
|
||||
current year and month.
|
||||
|
||||
Drop-down
|
||||
---------
|
||||
|
||||
:cpp:expr:`lv_calendar_header_dropdown_create(calendar)` creates a header that
|
||||
contains 2 drop-drown lists: one for the year and another for the month.
|
||||
contains 2 Drop-Drown List Widgets for the year and month.
|
||||
|
||||
.. _lv_calendar_example:
|
||||
|
||||
|
||||
@ -4,15 +4,108 @@
|
||||
Chart (lv_chart)
|
||||
================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Charts are a basic Widget to visualize data points. Currently *Line*
|
||||
charts (connect points with lines and/or draw points on them) and *Bar*
|
||||
charts are supported.
|
||||
Charts Widget are used to visualize data.
|
||||
|
||||
Charts have:
|
||||
|
||||
- 0 or more background division lines (horizontal and vertical),
|
||||
- 4 internal axes, any of which can be used to specify scale for a data series,
|
||||
- a ``point_count`` (default 10) that applies to all data series added,
|
||||
- 0 or more data series (you can add or remove them at any time),
|
||||
- 0 or more cursors (you can add or remove them at any time),
|
||||
- update mode (modifies behavior of :cpp:func:`lv_chart_set_next_value` if you use it).
|
||||
|
||||
Charts can:
|
||||
|
||||
- display flexible axes with ticks and text
|
||||
- show precise locations of points or other locations on chart with cursors
|
||||
- show or hide individual data series
|
||||
- show or hide individual data points
|
||||
- show or hide cursors
|
||||
- scroll and zoom
|
||||
|
||||
|
||||
|
||||
Chart Basics
|
||||
************
|
||||
|
||||
Each chart has the following attributes (over and above attributes found in
|
||||
:ref:`all Widgets <base_widget>`):
|
||||
|
||||
Type (governs how a chart's data series are drawn)
|
||||
- Can be LINE (default), BAR, SCATTER, or none.
|
||||
- You can change the chart's type at any point during it's life.
|
||||
|
||||
Horizontal and Vertical division lines
|
||||
- default 3 and 5 respectively
|
||||
- can be any non-negative value including 0
|
||||
|
||||
2 Y axes and 2 X axes (the latter are used with SCATTER charts)
|
||||
- All 4 axes come with each chart automatically (they do not have to be created).
|
||||
- Their default ranges are [0..100]. If you need a different range, set it before
|
||||
chart is drawn.
|
||||
- You "use" an axis by associating it with a data series, which happens when the
|
||||
data series is created (more on this below). More than one data series can be
|
||||
associated with each axis.
|
||||
|
||||
Point count (number of data points in all data series added to the chart)
|
||||
- default 10
|
||||
- If you provide your own data-value arrays, each array so provided must contain
|
||||
at least this number of values.
|
||||
- For LINE- and BAR-charts, this is the number of points on the X axis.
|
||||
- LINE- and BAR-charts require only one data-value array to supply Y-values for each data point.
|
||||
- For SCATTER charts, this is the number of scatter-points in the data series.
|
||||
- SCATTER charts have separate data-value arrays for both X-values and Y-values.
|
||||
|
||||
Any number of data series
|
||||
- After a chart is created, it initially contains no data series. You have to add them.
|
||||
- You can add and remove data series at any time during a chart's life.
|
||||
- When a data series is created, it comes with pre-allocated values array(s)
|
||||
based on its chart type and ``point_count``. (All chart types use an array of
|
||||
Y-values. SCATTER-type charts also use an array of X-values.). All Y-values so
|
||||
allocated are set to :c:macro:`LV_CHART_POINT_NONE`, which causes that point to be hidden.
|
||||
- To get points to be drawn on the chart, you must set their Y-values to something
|
||||
other than :c:macro:`LV_CHART_POINT_NONE`.
|
||||
- You can hide a point by setting its Y-value to :c:macro:`LV_CHART_POINT_NONE`.
|
||||
- If desired, you can tell a data series to instead use a value array you
|
||||
provide. If you do:
|
||||
|
||||
- Pre-allocated value arrays are automatically freed.
|
||||
- That data series will continue to use *your* array from that time onward.
|
||||
- The values in your array must remain available through the life of that data series.
|
||||
- You must ensure each array provided contains at least ``point_count`` ``int32_t`` elements.
|
||||
- Management of the life any value arrays you provide is up to you.
|
||||
|
||||
Any number of cursors
|
||||
- After a chart is created, it initially contains no cursors. You have to add them
|
||||
if you want to use them.
|
||||
- You can add, show, hide or remove cursors at any time during a chart's life.
|
||||
|
||||
Update mode
|
||||
- :ref:`See below <chart_update_modes>`
|
||||
|
||||
|
||||
Chart layers
|
||||
------------
|
||||
When a chart is drawn, certain things appear on top of other things, in this
|
||||
oder, from back to front:
|
||||
|
||||
- The chart's background (with optional division lines)
|
||||
- Each data series:
|
||||
|
||||
- Earliest data series added appears on top.
|
||||
- For a SCATTER chart, within each series, points later in the sequence will appear
|
||||
on top of points earlier in the sequence when there is overlap.
|
||||
|
||||
- Each cursor (if there are any):
|
||||
|
||||
- The most recent cursor added appears on top.
|
||||
|
||||
|
||||
Charts can have: - division lines - 2 y axis - axis ticks and texts on
|
||||
ticks - cursors - scrolling and zooming
|
||||
|
||||
.. _lv_chart_parts_and_styles:
|
||||
|
||||
@ -20,94 +113,132 @@ Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`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. For column
|
||||
charts ``pad_column`` sets the space between the columns of the
|
||||
adjacent indices.
|
||||
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar used if the chart is zoomed. See
|
||||
background and *line* (for division lines) related style
|
||||
properties. *Padding* makes the series area smaller. For BAR
|
||||
charts ``pad_column`` sets the space between bars in the same data series.
|
||||
- :cpp:enumerator:`LV_PART_SCROLLBAR` A scrollbar used if the chart is zoomed. See
|
||||
:ref:`base_widget`'s documentation for details.
|
||||
- :cpp:enumerator:`LV_PART_ITEMS` Refers to the line or bar series.
|
||||
- :cpp:enumerator:`LV_PART_ITEMS` Refers to the LINE or BAR data 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.
|
||||
- LINE chart: *line* properties are used by lines.
|
||||
``width``, ``height``, ``bg_color`` and ``radius`` are used to set
|
||||
the appearance of points on the line.
|
||||
- Bar chart: The typical background properties are used to style the
|
||||
bars. ``pad_column`` sets the space between the columns on the
|
||||
same index.
|
||||
bars. ``pad_column`` sets the space between columns in the same data series.
|
||||
|
||||
- :cpp:enumerator:`LV_PART_INDICATOR` Refers to the points on line and scatter chart
|
||||
(small circles or squares).
|
||||
- :cpp:enumerator:`LV_PART_CURSOR` *Line* properties are used to style the cursors.
|
||||
- :cpp:enumerator:`LV_PART_INDICATOR` Refers to points on LINE- and SCATTER-charts
|
||||
(small circles or squares [with possibly-rounded corners]).
|
||||
- :cpp:enumerator:`LV_PART_CURSOR` *Line* properties are used to style cursors.
|
||||
``width``, ``height``, ``bg_color`` and ``radius`` are used to set
|
||||
the appearance of points.
|
||||
the appearance of the cursor's "point" showing its location. If either ``width``
|
||||
or ``height`` are set to 0, only the cursor's lines are drawn.
|
||||
|
||||
.. _lv_chart_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
.. _lv_chart_details:
|
||||
|
||||
Details
|
||||
*******
|
||||
|
||||
Chart type
|
||||
----------
|
||||
|
||||
The following data display types exist:
|
||||
A chart can be one of the following types:
|
||||
|
||||
- :cpp:enumerator:`LV_CHART_TYPE_NONE`: Do not display any data. Can be used to hide the series.
|
||||
- :cpp:enumerator:`LV_CHART_TYPE_LINE`: Draw lines between the data points and/or points (rectangles or circles) on the data points.
|
||||
- :cpp:enumerator:`LV_CHART_TYPE_NONE`: Do not display any data. Can be used to hide chart's data.
|
||||
- :cpp:enumerator:`LV_CHART_TYPE_LINE`: Draw lines between data points. Data points
|
||||
can also be illustrated if their ``width``, ``height``, ``bg_color`` and ``radius``
|
||||
styles (for :cpp:enumerator:`LV_PART_ITEMS`) are set and both ``width`` and
|
||||
``height`` have non-zero values.
|
||||
- :cpp:enumerator:`LV_CHART_TYPE_BAR`: Draw bars.
|
||||
- :cpp:enumerator:`LV_CHART_TYPE_SCATTER`: X/Y chart drawing point's and lines between the points. .
|
||||
- :cpp:enumerator:`LV_CHART_TYPE_SCATTER`: X/Y chart drawing point's and optionally
|
||||
lines between the points if line-width style values for
|
||||
:cpp:enumerator:`LV_PART_ITEMS` is a non-zero value, and the point's Y-value is
|
||||
something other than :c:macro:`LV_CHART_POINT_NONE`. (Drawing of individual points on a
|
||||
SCATTER chart can be suppressed if their Y-values are set to :c:macro:`LV_CHART_POINT_NONE`.)
|
||||
|
||||
You can specify the display type with
|
||||
Charts start their life as LINE charts. You can change a chart's type with
|
||||
:cpp:expr:`lv_chart_set_type(chart, LV_CHART_TYPE_...)`.
|
||||
|
||||
Data series
|
||||
-----------
|
||||
|
||||
You can add any number of series to the charts by
|
||||
:cpp:expr:`lv_chart_add_series(chart, color, axis)`. This allocates an
|
||||
:cpp:expr:`lv_chart_series_t` structure which contains the chosen ``color`` and
|
||||
an array for the data points. ``axis`` can have the following values:
|
||||
You can add any number of data series to a chart by using
|
||||
|
||||
:cpp:expr:`lv_chart_add_series(chart, color, axis)`.
|
||||
|
||||
This allocates (and returns a pointer to) an :cpp:expr:`lv_chart_series_t` structure
|
||||
which remembers the ``color`` and ``axis`` you specified, and comes pre-allocated
|
||||
with an array of ``chart->point_cnt`` ``int32_t`` Y-values, all set to
|
||||
:c:macro:`LV_CHART_POINT_NONE`. (A SCATTER chart also comes with a pre-allocated array of
|
||||
the same number of X-values.)
|
||||
|
||||
``axis`` specifies which axis is used to scale its values, and may be one of the following:
|
||||
|
||||
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_Y`: Left axis
|
||||
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_Y`: Right axis
|
||||
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_X`: Bottom axis
|
||||
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_X`: Top axis
|
||||
|
||||
``axis`` tells which axis's range should be used to scale the values.
|
||||
When adding a data series to a SCATTER chart, bit-wise OR your selected Y axis
|
||||
(primary or secondary) with one of the X-axis values.
|
||||
|
||||
:cpp:expr:`lv_chart_set_ext_y_array(chart, ser, value_array)` makes the chart
|
||||
use an external array for the given series. ``value_array`` should look
|
||||
like this: ``int32_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
|
||||
:cpp:expr:`lv_chart_refresh(chart)` after the external data source has been
|
||||
updated to update the chart.
|
||||
If you wish to have the chart use your own Y-value array instead of the one provided,
|
||||
you can do so with
|
||||
|
||||
The value array of a series can be obtained with
|
||||
:cpp:expr:`lv_chart_get_y_array(chart, ser)`, which can be used with
|
||||
``ext_array`` or *normal array*\ s.
|
||||
:cpp:expr:`lv_chart_set_ext_y_array(chart, series, value_array)`.
|
||||
|
||||
For :cpp:enumerator:`LV_CHART_TYPE_SCATTER` type
|
||||
:cpp:expr:`lv_chart_set_ext_x_array(chart, ser, value_array)` and
|
||||
:cpp:expr:`lv_chart_get_x_array(chart, ser)` can be used as well.
|
||||
You are responsible for ensuring the array you provide contains at least
|
||||
``chart->point_cnt`` elements in it.
|
||||
|
||||
Modify the data
|
||||
---------------
|
||||
``value_array`` should look like this: ``int32_t * value_array[num_points]``. Only
|
||||
the array's pointer is saved in the series so its contents need to remain available
|
||||
for the life of the series, i.e. the array needs to be global, static or dynamically
|
||||
allocated.
|
||||
|
||||
You have several options to set the data of series:
|
||||
.. note::
|
||||
Call :cpp:expr:`lv_chart_refresh(chart)` when a chart's data has changed to
|
||||
signal that the chart should be re-rendered next time a display refresh occurs.
|
||||
You do not need to do this if you are using the provided value array(s) and
|
||||
setting values with ``lv_chart_set_...value_...()`` functions. See below
|
||||
for more information about these functions.
|
||||
|
||||
1. Set the values manually in the array like ``ser1->points[3] = 7`` and refresh the chart with :cpp:enumerator:`lv_chart_refresh(chart)`.
|
||||
2. Use :cpp:expr:`lv_chart_set_value_by_id(chart, ser, id, value)` where ``id`` is the index of the point you wish to update.
|
||||
3. Use the :cpp:expr:`lv_chart_set_next_value(chart, ser, value)`.
|
||||
4. Initialize all points to a given value with :cpp:expr:`lv_chart_set_all_value(chart, ser, value)`.
|
||||
A pointer to the Y-value array of a series can be obtained with
|
||||
:cpp:expr:`lv_chart_get_y_array(chart, series)`. This is true whether you are using
|
||||
the provided Y-value array or provided your own.
|
||||
|
||||
Use :cpp:enumerator:`LV_CHART_POINT_NONE` as value to make the library skip drawing
|
||||
that point, column, or line segment.
|
||||
For SCATTER-type charts,
|
||||
|
||||
For :cpp:enumerator:`LV_CHART_TYPE_SCATTER` type
|
||||
:cpp:expr:`lv_chart_set_value_by_id2(chart, ser, id, value)` and
|
||||
:cpp:expr:`lv_chart_set_next_value2(chart, ser, x_value, y_value)` can be used
|
||||
as well.
|
||||
- :cpp:expr:`lv_chart_set_ext_x_array(chart, series, value_array)` and
|
||||
- :cpp:expr:`lv_chart_get_x_array(chart, series)`
|
||||
|
||||
can be used as well.
|
||||
|
||||
Modifying data
|
||||
--------------
|
||||
|
||||
You have several options to set the Y-values for a data series:
|
||||
|
||||
1. Set the values programmatically in the array like ``ser1->points[3] = 7`` and refresh the
|
||||
chart with :cpp:enumerator:`lv_chart_refresh(chart)`.
|
||||
2. Use :cpp:expr:`lv_chart_set_value_by_id(chart, series, id, value)` where ``id`` is
|
||||
the zero-based index of the point you wish to update.
|
||||
3. Use :cpp:expr:`lv_chart_set_next_value(chart, series, value)`.
|
||||
(See `Update modes`_ below.)
|
||||
4. Set all points to a single Y-value with :cpp:expr:`lv_chart_set_all_value(chart, series, value)`.
|
||||
|
||||
Use :c:macro:`LV_CHART_POINT_NONE` as value to make the library skip drawing
|
||||
that point, column, or scatter-point.
|
||||
|
||||
For SCATTER-type charts,
|
||||
|
||||
- :cpp:expr:`lv_chart_set_value_by_id2(chart, series, id, x_value, y_value)` and
|
||||
- :cpp:expr:`lv_chart_set_next_value2(chart, series, x_value, y_value)`
|
||||
|
||||
can be used as well.
|
||||
|
||||
.. _chart_update_modes:
|
||||
.. _update modes:
|
||||
|
||||
Update modes
|
||||
------------
|
||||
@ -126,14 +257,14 @@ Number of points
|
||||
|
||||
The number of points in the series can be modified by
|
||||
:cpp:expr:`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, so you need to be sure the external
|
||||
array is large enough.
|
||||
Note: this affects the number of points processed when an external
|
||||
value array is assigned to a series, so you also need to be sure any external
|
||||
array so provided contains at least ``point_num`` elements.
|
||||
|
||||
Handling large number of points
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Handling large numbers of points
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
On line charts, if the number of points is greater than the pixels
|
||||
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
|
||||
points to a pixel, LVGL searches the smallest and the largest value and
|
||||
@ -142,10 +273,10 @@ draws a vertical lines between them to ensure no peaks are missed.
|
||||
Vertical range
|
||||
--------------
|
||||
|
||||
You can specify the minimum and maximum values in y-direction with
|
||||
You can specify the minimum and maximum values in Y-direction with
|
||||
:cpp:expr:`lv_chart_set_range(chart, axis, min, max)`. ``axis`` can be
|
||||
:cpp:enumerator:`LV_CHART_AXIS_PRIMARY` (left axis) or :cpp:enumerator:`LV_CHART_AXIS_SECONDARY`
|
||||
(right axis).
|
||||
:cpp:enumerator:`LV_CHART_AXIS_PRIMARY_Y` (left Y axis) or
|
||||
:cpp:enumerator:`LV_CHART_AXIS_SECONDARY_Y` (right Y axis).
|
||||
|
||||
The value of the points will be scaled proportionally. The default range
|
||||
is: 0..100.
|
||||
@ -157,15 +288,16 @@ The number of horizontal and vertical division lines can be modified by
|
||||
:cpp:expr:`lv_chart_set_div_line_count(chart, hdiv_num, vdiv_num)`. The default
|
||||
settings are 3 horizontal and 5 vertical division lines. 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.
|
||||
would be drawn on top of the border and in this case it is not drawn so
|
||||
as not to hide the chart border.
|
||||
|
||||
Override default start point for series
|
||||
---------------------------------------
|
||||
|
||||
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 index with the
|
||||
function :cpp:expr:`lv_chart_set_x_start_point(chart, ser, id)` where ``id`` is
|
||||
the new index position to start plotting from.
|
||||
function :cpp:expr:`lv_chart_set_x_start_point(chart, series, id)` where ``id`` is
|
||||
the new zero-based index position to start plotting from.
|
||||
|
||||
Note that :cpp:enumerator:`LV_CHART_UPDATE_MODE_SHIFT` also changes the
|
||||
``start_point``.
|
||||
@ -173,34 +305,47 @@ Note that :cpp:enumerator:`LV_CHART_UPDATE_MODE_SHIFT` also changes the
|
||||
Tick marks and labels
|
||||
---------------------
|
||||
|
||||
With the help of :ref:`Scale <lv_scale>`, vertical and horizontal scales can be added in a very flexible way.
|
||||
See the example below to learn more.
|
||||
With the help of :ref:`Scale <lv_scale>`, vertical and horizontal scales can be added
|
||||
in a very flexible way. See the `examples 2 <#axis-ticks-and-labels-with-scrolling>`_
|
||||
below to learn more.
|
||||
|
||||
Zoom
|
||||
----
|
||||
|
||||
To zoom the chart all you need to is wrapping it into a parent container and set the chart's width or height
|
||||
to larger value. This way the chart will be scrollable on its parent.
|
||||
To zoom the chart all you need to do is wrap it in a parent container and set the
|
||||
chart's width and/or height to a larger value. Doing this will cause the the chart
|
||||
to be scrollable in its parent --- the parent container provides the scrollable "view
|
||||
window".
|
||||
|
||||
Cursor
|
||||
------
|
||||
|
||||
A new cursor is initially given position :c:macro:`LV_CHART_POINT_NONE` which causes
|
||||
it to be hidden. To show the cursor, its location must be set by you
|
||||
programmatically using one of the functions below.
|
||||
|
||||
You can hide a cursor without removing it from the chart by using
|
||||
:cpp:func:`lv_chart_set_cursor_point` by passing :c:macro:`LV_CHART_POINT_NONE` as
|
||||
the point id.
|
||||
|
||||
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.
|
||||
The possible values of ``dir`` are the enumeration values of :cpp:type:`lv_dir_t`:
|
||||
``LV_DIR_NONE/RIGHT/UP/LEFT/DOWN/HOR/VER/ALL`` or their bit-wise OR-ed values to tell
|
||||
the chart which direction(s) to draw its lines.
|
||||
|
||||
:cpp:expr:`lv_chart_set_cursor_pos(chart, cursor, &point)` sets the position of
|
||||
the cursor. ``pos`` is a pointer to an :cpp:struct:`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.
|
||||
the cursor to an arbitrary point on the chart. ``&point`` is a pointer to an
|
||||
:cpp:struct:`lv_point_t` variable. E.g. ``lv_point_t point = {10, 20}``. If the chart
|
||||
is scrolled, the cursor moves with it.
|
||||
|
||||
:cpp:expr:`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.
|
||||
coordinate of a given point on the chart. This is useful to place the cursor on
|
||||
that data point.
|
||||
|
||||
:cpp:expr:`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.
|
||||
:cpp:expr:`lv_chart_set_cursor_point(chart, cursor, series, point_id)` places the
|
||||
cursor on the specified data point on the chart. If the point's position changes
|
||||
(via a new value or via scrolling), the cursor moves with the point.
|
||||
See an example of using this function `here <#show-cursor-on-the-clicked-point>`_.
|
||||
|
||||
|
||||
|
||||
@ -209,7 +354,7 @@ scrolling) the cursor will move with the point.
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new point is clicked pressed.
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new point on the chart is pressed.
|
||||
:cpp:expr:`lv_chart_get_pressed_point(chart)` returns the zero-based index of
|
||||
the pressed point.
|
||||
|
||||
|
||||
@ -10,20 +10,22 @@ Overview
|
||||
The Checkbox Widget is created from a "tick box" and a label. When the
|
||||
Checkbox is clicked the tick box is toggled.
|
||||
|
||||
|
||||
.. _lv_checkbox_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The is the background of the Checkbox and it uses
|
||||
the text and all the typical background style properties.
|
||||
``pad_column`` adjusts the spacing between the tickbox and the label
|
||||
- :cpp:enumerator:`LV_PART_MAIN` Background of Checkbox and it uses
|
||||
the text- and all the typical background-style properties.
|
||||
``pad_column`` adjusts spacing between tickbox and label
|
||||
- :cpp:enumerator:`LV_PART_INDICATOR` The "tick box" is a square that uses all the
|
||||
typical background style properties. By default, its size is equal to
|
||||
the height of the main part's font. Padding properties make the tick
|
||||
box larger in the respective directions.
|
||||
|
||||
The Checkbox is added to the default group (if it is set).
|
||||
The Checkbox is added to the default group (if one is set).
|
||||
|
||||
|
||||
.. _lv_checkbox_usage:
|
||||
|
||||
@ -33,27 +35,27 @@ Usage
|
||||
Text
|
||||
----
|
||||
|
||||
The text can be modified with the
|
||||
:cpp:expr:`lv_checkbox_set_text(cb, "New text")` function and will be
|
||||
The text can be modified with
|
||||
:cpp:expr:`lv_checkbox_set_text(cb, "New text")` and will be
|
||||
dynamically allocated.
|
||||
|
||||
To set a static text, use :cpp:expr:`lv_checkbox_set_static_text(cb, txt)`. This
|
||||
way, only a pointer to ``txt`` will be stored. The text then shouldn't
|
||||
be deallocated while the checkbox exists.
|
||||
To set static text, use :cpp:expr:`lv_checkbox_set_text_static(cb, txt)`. This
|
||||
way, only a pointer to ``txt`` will be stored. The provided text buffer must remain
|
||||
available for the life of the Checkbox.
|
||||
|
||||
Check, uncheck, disable
|
||||
-----------------------
|
||||
|
||||
You can manually check, un-check, and disable the Checkbox by using the
|
||||
You can programmatically check, un-check, and disable the Checkbox by using the
|
||||
common state add/clear function:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_obj_add_state(cb, LV_STATE_CHECKED); /* Make the checkbox checked */
|
||||
lv_obj_remove_state(cb, LV_STATE_CHECKED); /* Make the checkbox unchecked */
|
||||
lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); /* Make the checkbox checked and disabled */
|
||||
lv_obj_add_state(cb, LV_STATE_CHECKED); /* Make Checkbox checked */
|
||||
lv_obj_remove_state(cb, LV_STATE_CHECKED); /* Make Checkbox unchecked */
|
||||
lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); /* Make Checkbox checked and disabled */
|
||||
|
||||
To get whether the checkbox is checked or not use:
|
||||
To find out whether the Checkbox is checked use
|
||||
:cpp:expr:`lv_obj_has_state(cb, LV_STATE_CHECKED)`.
|
||||
|
||||
|
||||
@ -63,7 +65,7 @@ To get whether the checkbox is checked or not use:
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled.
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when Checkbox is toggled.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
@ -78,10 +80,11 @@ Events
|
||||
Keys
|
||||
****
|
||||
|
||||
The following *Keys* are processed by the 'Buttons': -
|
||||
``LV_KEY_RIGHT/UP`` Go to toggled state if toggling is enabled -
|
||||
``LV_KEY_LEFT/DOWN`` Go to non-toggled state if toggling is enabled -
|
||||
:cpp:enumerator:`LV_KEY_ENTER` Clicks the checkbox and toggles it
|
||||
The following *Keys* are processed by Checkbox:
|
||||
|
||||
- ``LV_KEY_RIGHT/UP`` Go to CHECKED state if Checkbox is enabled
|
||||
- ``LV_KEY_LEFT/DOWN`` Go to non-CHECKED state if Checkbox is enabled
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` Clicks the Checkbox and toggles its value.
|
||||
|
||||
Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to
|
||||
``LV_EVENT_PRESSED/PRESSING/RELEASED`` etc.
|
||||
|
||||
@ -7,92 +7,92 @@ Drop-Down List (lv_dropdown)
|
||||
Overview
|
||||
********
|
||||
|
||||
The drop-down list allows the user to select one value from a list.
|
||||
The Drop-Down List allows the user to select a value from a list.
|
||||
|
||||
The drop-down list is closed by default and displays a single value or a
|
||||
predefined text. When activated (by click on the drop-down list), a list
|
||||
is created from which the user may select one option. When the user
|
||||
The Drop-Down List is closed by default and displays a single value or
|
||||
predefined text. When activated (by click on the Drop-Down List), a list
|
||||
is created from which the user may select one item. When the user
|
||||
selects a new value, the list is deleted again.
|
||||
|
||||
The Drop-down list is added to the default group (if it is set). Besides
|
||||
the Drop-down list is an editable Widget to allow selecting an option
|
||||
with encoder navigation as well.
|
||||
The Drop-down list is added to the default group (if one is set).
|
||||
The Drop-down list is an editable Widget allowing list-item selection via
|
||||
encoder or keyboard navigation as well.
|
||||
|
||||
|
||||
.. _lv_dropdown_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
The Dropdown widget is built from the elements: "button" and "list"
|
||||
(both not related to the button and list widgets)
|
||||
The Drop-Down List Widget is built from the elements: "button" and "list"
|
||||
(lightweight versions of the Button and List Widgets).
|
||||
|
||||
Button
|
||||
------
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the button. Uses the typical
|
||||
background properties and text properties for the text on it.
|
||||
- :cpp:enumerator:`LV_PART_INDICATOR` Typically an arrow symbol that can be an image
|
||||
or a text (:cpp:enumerator:`LV_SYMBOL`).
|
||||
- :cpp:enumerator:`LV_PART_MAIN` Background of button, uses the typical
|
||||
background- and text-properties for its text.
|
||||
- :cpp:enumerator:`LV_PART_INDICATOR` Typically an arrow symbol that can be an Image
|
||||
or text (e.g. :cpp:enumerator:`LV_SYMBOL`).
|
||||
|
||||
The button goes to :cpp:enumerator:`LV_STATE_CHECKED` when it's opened.
|
||||
|
||||
List
|
||||
----
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The list itself. Uses the typical background
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The list itself; uses the typical background
|
||||
properties. ``max_height`` can be used to limit the height of the
|
||||
list.
|
||||
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar background, border, shadow
|
||||
properties and width (for its own width) and right padding for the
|
||||
spacing on the right.
|
||||
- :cpp:enumerator:`LV_PART_SELECTED` Refers to the currently pressed, checked or
|
||||
pressed+checked option. Also uses the typical background properties.
|
||||
pressed+checked option. Also uses the typical background properties.
|
||||
|
||||
The list is hidden/shown on open/close. To add styles to it use
|
||||
:cpp:expr:`lv_dropdown_get_list(dropdown)` to get the list Widget. For example:
|
||||
The list is shown/hidden on open/close. To add styles to it use
|
||||
:cpp:expr:`lv_dropdown_get_list(dropdown)` to get the list object. Example:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/
|
||||
lv_obj_add_style(list, &my_style, selector) /*Add the styles to the list*/
|
||||
lv_obj_t * list = lv_dropdown_get_list(dropdown) /* Get list */
|
||||
lv_obj_add_style(list, &my_style, selector) /* Add styles to list */
|
||||
|
||||
Alternatively the theme can be extended with new styles.
|
||||
|
||||
Alternatively the theme can be extended with the new styles.
|
||||
|
||||
.. _lv_dropdown_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
.. _lv_dropdown_options:
|
||||
|
||||
Options
|
||||
*******
|
||||
.. _lv_dropdown_list_items:
|
||||
|
||||
Set options
|
||||
-----------
|
||||
List items
|
||||
----------
|
||||
|
||||
Options are passed to the drop-down list as a string with
|
||||
:cpp:expr:`lv_dropdown_set_options(dropdown, options)`. Options should be
|
||||
separated by ``\n``. For example: ``"First\nSecond\nThird"``. This
|
||||
string will be saved in the drop-down list, so it can in a local
|
||||
variable.
|
||||
The list items are passed to the Drop-Down List as a newline-separated list in a string
|
||||
as the ``options`` argument to :cpp:expr:`lv_dropdown_set_options(dropdown, options)`.
|
||||
Each list item should be separated by ``\n``. Example: ``"First\nSecond\nThird"``.
|
||||
This string is copied by the Drop-Down List, so its contents do not need to remain
|
||||
available beyond this call.
|
||||
|
||||
The :cpp:expr:`lv_dropdown_add_option(dropdown, "New option", pos)` function
|
||||
inserts a new option to ``pos`` index.
|
||||
inserts a new option at index ``pos``.
|
||||
|
||||
To save memory the options can set from a static(constant) string as well
|
||||
with :cpp:expr:`lv_dropdown_set_static_options(dropdown, options)`. In this case
|
||||
the options string should be alive while the drop-down list exists and
|
||||
:cpp:func:`lv_dropdown_add_option` can't be used
|
||||
To save memory the options can be set from a static (const) string as well
|
||||
with :cpp:expr:`lv_dropdown_set_options_static(dropdown, options)`. In this case
|
||||
the options string's contents must remain available for the life of the Drop-Down
|
||||
List and :cpp:func:`lv_dropdown_add_option` cannot be used.
|
||||
|
||||
You can select an option manually with
|
||||
You can select an option programmatically with
|
||||
:cpp:expr:`lv_dropdown_set_selected(dropdown, id)`, where ``id`` is the index of
|
||||
an option.
|
||||
the target option.
|
||||
|
||||
Get selected option
|
||||
-------------------
|
||||
|
||||
The get the *index* of the selected option, use
|
||||
To get the *index* of the selected option, use
|
||||
:cpp:expr:`lv_dropdown_get_selected(dropdown)`.
|
||||
|
||||
:cpp:expr:`lv_dropdown_get_selected_str(dropdown, buf, buf_size)` copies the
|
||||
@ -102,7 +102,7 @@ Direction
|
||||
---------
|
||||
|
||||
The list can be created on any side. The default :cpp:enumerator:`LV_DIR_BOTTOM` can
|
||||
be modified by :cpp:expr:`lv_dropdown_set_dir(dropdown, LV_DIR_LEFT)` function.
|
||||
be modified using :cpp:expr:`lv_dropdown_set_dir(dropdown, LV_DIR_LEFT)`.
|
||||
|
||||
If the list would be vertically out of the screen, it will be aligned to
|
||||
the edge.
|
||||
@ -110,25 +110,25 @@ the edge.
|
||||
Symbol
|
||||
------
|
||||
|
||||
A symbol (typically an arrow) can be added to the dropdown list with
|
||||
A symbol (typically an arrow) can be added to the Drop-Down List with
|
||||
:cpp:expr:`lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)`
|
||||
|
||||
If the direction of the drop-down list is :cpp:enumerator:`LV_DIR_LEFT` the symbol
|
||||
If the direction of the Drop-Down List is :cpp:enumerator:`LV_DIR_LEFT` the symbol
|
||||
will be shown on the left, otherwise on the right.
|
||||
|
||||
Show selected
|
||||
-------------
|
||||
|
||||
The main part can either show the selected option or a static text. If a
|
||||
The main part can either show the selected item or static text. If
|
||||
static is set with :cpp:expr:`lv_dropdown_set_text(dropdown, "Some text")` it
|
||||
will be shown regardless to th selected option. If the text is ``NULL``
|
||||
will be shown regardless of the selected item. If the text is ``NULL``
|
||||
the selected option is displayed on the button.
|
||||
|
||||
Manually open/close
|
||||
-------------------
|
||||
Programmatically open/close
|
||||
---------------------------
|
||||
|
||||
To manually open or close the drop-down list the
|
||||
``lv_dropdown_open/close(dropdown)`` function can be used.
|
||||
To programmatically open or close the Drop-Down List use
|
||||
:cpp:expr:`lv_dropdown_open(dropdown)` or :cpp:expr:`lv_dropdown_close(dropdown)`.
|
||||
|
||||
|
||||
|
||||
@ -137,9 +137,9 @@ To manually open or close the drop-down list the
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the new option is selected or the list is opened/closed.
|
||||
- :cpp:enumerator:`LV_EVENT_CANCEL` Sent when the list is closed
|
||||
- :cpp:enumerator:`LV_EVENT_READY` Sent when the list is opened
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new option is selected or the list is opened/closed.
|
||||
- :cpp:enumerator:`LV_EVENT_CANCEL` Sent when list is closed.
|
||||
- :cpp:enumerator:`LV_EVENT_READY` Sent when list is opened.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
@ -154,10 +154,10 @@ Events
|
||||
Keys
|
||||
****
|
||||
|
||||
- ``LV_KEY_RIGHT/DOWN`` Select the next option.
|
||||
- ``LV_KEY_LEFT/UP`` Select the previous option.
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` Apply the selected option (Sends
|
||||
:cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event and closes the drop-down list).
|
||||
- ``LV_KEY_RIGHT/DOWN`` Select next list item.
|
||||
- ``LV_KEY_LEFT/UP`` Select previous list item.
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` Apply selected list item (sends
|
||||
:cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event and closes Drop-Down List).
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user