mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-28 07:03:00 +08:00
159 lines
5.0 KiB
ReStructuredText
159 lines
5.0 KiB
ReStructuredText
Meter (lv_meter)
|
|
================
|
|
|
|
Overview
|
|
********
|
|
|
|
The Meter widget can visualize data in very flexible ways. In can show
|
|
arcs, needles, ticks lines and labels.
|
|
|
|
Parts and Styles
|
|
****************
|
|
|
|
- :cpp:enumerator:`LV_PART_MAIN` The background of the Meter. Uses the typical
|
|
background properties.
|
|
- :cpp:enumerator:`LV_PART_TICK` The tick lines a labels using the *line* and *text*
|
|
style properties.
|
|
- :cpp:enumerator:`LV_PART_INDICATOR` The needle line or image using the *line* and
|
|
*img* style properties, as well as the background properties to draw
|
|
a square (or circle) on the pivot of the needles. Padding makes the
|
|
square larger.
|
|
- :cpp:enumerator:`LV_PART_ITEMS` The arcs using the *arc* properties.
|
|
|
|
Usage
|
|
*****
|
|
|
|
Scale
|
|
-----
|
|
|
|
The Scale has minor and major ticks, and labels on the major ticks.
|
|
|
|
The minor tick lines can be configured with:
|
|
:cpp:expr:`lv_meter_set_scale_ticks(meter, tick_count, line_width, tick_length, tick_color)`.
|
|
|
|
To show major tick lines use
|
|
:cpp:expr:`lv_meter_set_scale_major_ticks(meter, nth_major, tick_width, tick_length, tick_color, label_gap)`.
|
|
``nth_major`` to specify how many minor ticks to skip to draw a major
|
|
tick.
|
|
|
|
Labels are added automatically on major ticks with ``label_gap``
|
|
distance from the ticks with text proportionally to the values of the
|
|
tick line.
|
|
|
|
:cpp:expr:`lv_meter_set_scale_range(meter, min, max, angle_range, rotation)`
|
|
sets the value and angle range of the scale.
|
|
|
|
Add indicators
|
|
--------------
|
|
|
|
Indicators can be added to meter and their value is interpreted in the
|
|
range of the scale.
|
|
|
|
All the indicator add functions return an ``lv_meter_indicator_t *``.
|
|
|
|
Needle line
|
|
^^^^^^^^^^^
|
|
|
|
``indic = lv_meter_add_needle_line(meter, line_width, line_color, r_mod)``
|
|
adds a needle line to a Scale. By default, the length of the line is the
|
|
same as the scale's radius but ``r_mod`` changes the length.
|
|
|
|
:cpp:expr:`lv_meter_set_indicator_value(meter, indic, value)` sets the value of
|
|
the indicator.
|
|
|
|
Needle image
|
|
^^^^^^^^^^^^
|
|
|
|
``indic = lv_meter_add_needle_img(meter, img_src, pivot_x, pivot_y)``
|
|
sets an image that will be used as a needle. ``img_src`` should be a
|
|
needle pointing to the right like this ``-O--->``. ``pivot_x`` and
|
|
``pivot_y`` sets the pivot point of the rotation relative to the top
|
|
left corner of the image.
|
|
|
|
:cpp:expr:`lv_meter_set_indicator_value(meter, indicator, value)` sets the
|
|
value of the indicator.
|
|
|
|
Arc
|
|
^^^
|
|
|
|
``indic = lv_meter_add_arc(meter, arc_width, arc_color, r_mod)`` adds
|
|
and arc indicator. . By default, the radius of the arc is the same as
|
|
the scale's radius but ``r_mod`` changes the radius.
|
|
|
|
:cpp:expr:`lv_meter_set_indicator_start_value(meter, indic, value)` and
|
|
:cpp:expr:`lv_meter_set_indicator_end_value(meter, indicator, value)` sets the
|
|
value of the indicator.
|
|
|
|
Scale lines (ticks)
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
``indic = lv_meter_add_scale_lines(meter, color_start, color_end, local, width_mod)``
|
|
adds an indicator that modifies the ticks lines. If ``local`` is
|
|
``true`` the ticks' color will be faded from ``color_start`` to
|
|
``color_end`` in the indicator's start and end value range. If ``local``
|
|
is ``false`` ``color_start`` and ``color_end`` will be mapped to the
|
|
start and end value of the scale and only a "slice" of that color
|
|
gradient will be visible in the indicator's start and end value range.
|
|
``width_mod`` modifies the width of the tick lines.
|
|
|
|
:cpp:expr:`lv_meter_set_indicator_start_value(meter, indicator, value)` and
|
|
:cpp:expr:`lv_meter_set_indicator_end_value(meter, indicator, value)` sets the
|
|
value of the indicator.
|
|
|
|
Events
|
|
******
|
|
|
|
- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` is sent
|
|
for the following types:
|
|
|
|
- :cpp:enumerator:`LV_METER_DRAW_PART_ARC` The arc indicator
|
|
|
|
- ``part``: :cpp:enumerator:`LV_PART_ITEMS`
|
|
- ``sub_part_ptr``: pointer to the indicator
|
|
- ``arc_dsc``
|
|
- ``radius``: radius of the arc
|
|
- ``p1`` center of the arc
|
|
|
|
- :cpp:enumerator:`LV_METER_DRAW_PART_NEEDLE_LINE` The needle lines
|
|
|
|
- ``part``: :cpp:enumerator:`LV_PART_ITEMS`
|
|
- ``p1``, ``p2`` points of the line
|
|
- ``line_dsc``
|
|
- ``sub_part_ptr``: pointer to the indicator
|
|
|
|
- :cpp:enumerator:`LV_METER_DRAW_PART_NEEDLE_IMG` The needle images
|
|
|
|
- ``part``: :cpp:enumerator:`LV_PART_ITEMS`
|
|
- ``p1``, ``p2`` points of the line
|
|
- ``img_dsc``
|
|
- ``sub_part_ptr``: pointer to the indicator
|
|
|
|
- :cpp:enumerator:`LV_METER_DRAW_PART_TICK` The tick lines and labels
|
|
|
|
- ``part``: :cpp:enumerator:`LV_PART_TICKS`
|
|
- ``value``: the value of the line
|
|
- ``text``: ``value`` converted to decimal or ``NULL`` on minor
|
|
lines
|
|
- ``label_dsc``: label draw descriptor or ``NULL`` on minor lines
|
|
- ``line_dsc``:
|
|
- ``id``: the index of the line
|
|
|
|
See the events of the `Base object </widgets/obj>`__ too.
|
|
|
|
Learn more about :ref:`events`.
|
|
|
|
Keys
|
|
****
|
|
|
|
No keys are handled by the Meter widget.
|
|
|
|
Learn more about :ref:`indev_keys`.
|
|
|
|
Example
|
|
*******
|
|
|
|
.. include:: ../examples/widgets/meter/index.rst
|
|
|
|
API
|
|
***
|