lvgl/docs/widgets/meter.rst

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
***