mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-14 06:42:58 +08:00
116 lines
3.9 KiB
ReStructuredText
116 lines
3.9 KiB
ReStructuredText
.. _lv_scale:
|
|
|
|
================
|
|
Scale (lv_scale)
|
|
================
|
|
|
|
Overview
|
|
********
|
|
|
|
Scale allows you to have a linear scale with ranges and sections with custom styling.
|
|
|
|
.. _lv_scale_parts_and_styles:
|
|
|
|
Parts and Styles
|
|
****************
|
|
|
|
The scale widget is divided in the following three parts:
|
|
|
|
- :cpp:enumerator:`LV_PART_MAIN` Main line. See blue line in the example image.
|
|
- :cpp:enumerator:`LV_PART_ITEMS` Minor ticks. See red minor ticks in the example image.
|
|
- :cpp:enumerator:`LV_PART_INDICATOR` Major ticks and its labels (if enabled).
|
|
See pink labels and green major ticks in the example image.
|
|
|
|
.. image:: /misc/scale.png
|
|
|
|
.. _lv_scale_usage:
|
|
|
|
Usage
|
|
*****
|
|
|
|
Set ranges
|
|
----------
|
|
|
|
The minor and major range (values of each tick) are configured with :cpp:expr:`lv_scale_set_range(scale, minor_range, major_range)`.
|
|
|
|
Tick drawing order
|
|
------------------
|
|
You can set the drawing of the ticks on top of the main line with :cpp:expr:`lv_scale_set_draw_ticks_on_top(scale, true)`. The default
|
|
drawing order is below the main line.
|
|
|
|
This is a scale with the ticks being drawn below of the main line (default):
|
|
|
|
.. image:: /misc/scale_ticks_below.png
|
|
|
|
This is an scale with the ticks being drawn at the top of the main line:
|
|
|
|
.. image:: /misc/scale_ticks_on_top.png
|
|
|
|
Configure ticks
|
|
---------------
|
|
|
|
Set the number of total ticks with :cpp:expr:`lv_scale_set_total_tick_count(scale, total_tick_count)`
|
|
and then configure the major tick being every Nth ticks with :cpp:expr:`lv_scale_set_major_tick_every(scale, nth_tick)`.
|
|
|
|
Labels on major ticks can be configured with :cpp:expr:`lv_scale_set_label_show(scale, show_label)`,
|
|
set `show_label` to true if labels should be drawn, :cpp:expr:`false` to hide them.
|
|
If instead of a numerical value in the major ticks a text is required they can be set
|
|
with :cpp:expr:`lv_scale_set_text_src(scale, custom_labels)` using ``NULL`` as the last element,
|
|
i.e. :cpp:expr:`static char * custom_labels[3] = {"One", "Two", NULL};`.
|
|
|
|
<strong> NOTE: </strong> The major tick value is calculated with the :cpp:expr:`lv_map` API (when not setting the custom labels),
|
|
this calculation takes into consideration the total tick number and the scale range, so the label drawn can present rounding errors
|
|
when the calculated value is a float number.
|
|
|
|
The length of the ticks can be configured with the length style property on the :cpp:enumerator:`LV_PART_INDICATOR`
|
|
for major ticks and :cpp:enumerator:`LV_PART_ITEMS` for minor ticks, for example with local style:
|
|
:cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_INDICATOR);` for major ticks
|
|
and :cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_ITEMS);` for minor ticks.
|
|
|
|
Sections
|
|
--------
|
|
|
|
A section is the space between a minor and a major range. They can be created with :cpp:expr:`lv_scale_add_section(scale)`
|
|
and it handles back an :cpp:type:`lv_scale_section_t` pointer.
|
|
|
|
The range of the section is configured with :cpp:expr:`lv_scale_section_set_range(section, minor_range, major_range)`.
|
|
The style of each of the three parts of the scale section can be set with
|
|
:cpp:expr:`lv_scale_section_set_style(section, PART, style_pointer)`, where `PART` can be
|
|
:cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_ITEMS` or :cpp:enumerator:`LV_PART_INDICATOR`,
|
|
:cpp:expr:`style_pointer` should point to a global or static :cpp:type:`lv_style_t` variable.
|
|
|
|
For labels the following properties can be configured:
|
|
:cpp:func:`lv_style_set_text_font`, :cpp:func:`lv_style_set_text_color`,
|
|
:cpp:func:`lv_style_set_text_letter_space`, :cpp:func:`lv_style_set_text_opa`.
|
|
|
|
For lines (main line, major and minor ticks) the following properties can be configured:
|
|
:cpp:func:`lv_style_set_line_color`, :cpp:func:`lv_style_set_line_width`.
|
|
|
|
.. _lv_scale_events:
|
|
|
|
Events
|
|
******
|
|
|
|
No events supported by this widget.
|
|
|
|
.. _lv_scale_keys:
|
|
|
|
Keys
|
|
****
|
|
|
|
No keys supported by this widget.
|
|
|
|
.. _lv_scale_example:
|
|
|
|
Example
|
|
*******
|
|
|
|
.. include:: ../examples/widgets/scale/index.rst
|
|
|
|
.. _lv_scale_api:
|
|
|
|
API
|
|
***
|
|
|
|
:ref:`lv_scale`
|