Arc (lv_arc)

Overview

The Arc consists of a background and a foreground arc. The foregrond (indicator) can be touch-adjusted.

Parts and Styles

  • LV_PART_MAIN Draws a background using the typical background style properties and an arc using the arc style properties. The arc's size and position will respect the padding style properties.

  • LV_PART_INDICATOR Draws an other arc using the arc style properties. Its padding values are interpreted relative to the background arc.

  • LV_PART_KNOB Draws a handle on the end of the indicator using all background properties and padding values. With zero padding the knob size is the same as the indicator's width. Larger padding makes it larger, smaller padding makes it smaller.

Usage

Value and range

A new value can be set using lv_arc_set_value(arc, new_value). The value is interpreted in a range (minimum and maximum values) which can be modified with lv_arc_set_range(arc, min, max). The default range is 1..100.

The indicator arc is drawn on the main part's arc. This if the value is set to maximum the indicator arc will cover the entire "background" arc. To set the start and end angle of the background arc use the lv_arc_set_bg_angles(arc, start_angle, end_angle) functions or lv_arc_set_bg_start/end_angle(arc, angle).

Zero degrees is at the middle right (3 o'clock) of the object and the degrees are increasing in clockwise direction. The angles should be in the [0;360] range.

Rotation

An offset to the 0 degree position can added with lv_arc_set_rotation(arc, deg).

Mode

The arc can be one of the following modes:

  • LV_ARC_MODE_NORMAL The indicator arc is drawn from the minimimum value to the current.

  • LV_ARC_MODE_REVERSE The indicator arc is drawn counter-clockwise from the maximum value to the current.

  • LV_ARC_MODE_SYMMETRICAL The indicator arc is drawn from the middle point to the current value.

The mode can be set by lv_arc_set_mode(arc, LV_ARC_MODE_...) and used only if the the angle is set by lv_arc_set_value() or the arc is adjusted by finger.

Change rate

If the arc is pressed the current value will set with a limited speed according to the set change rate. The change rate is defined in degree/second unit and can be set with lv_arc_set_change_rage(arc, rate)

Setting the indicator manually

It also possible to set the angles of the indicator arc directly with lv_arc_set_angles(arc, start_angle, end_angle) function or lv_arc_set_start/end_angle(arc, start_angle). In this case the set "value" and "mode" is ignored.

In other words, settings angles and values are independent. You should use either value and angle settings. Mixing the two might result in unintended behavior.

To make the arc non-adjustabe remove the style of the knob and make the object non-clickable:

lv_obj_remove_style(arc, NULL, LV_PART_KNOB);
lv_obj_clear_flag(arc, LV_OBJ_FLAG_CLICKABLE);

Events

  • LV_EVENT_VALUE_CHANGED sent when the arc is pressed/dragged to set a new value.

  • LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END are sent for the background rectangle, the background arc, the foreground arc and the knob to allow hooking the drawing. For more detail on the backround rectangle part see the Base object's documentation. The fields of lv_obj_draw_dsc_t are set as follows:

    • For both arcs: clip_area, p1 (center of the arc), radius, arc_dsc, part.

    • For the knob: clip_area, draw_area, rect_dsc, part.

Learn more about Events.

Keys

  • LV_KEY_RIGHT/UP Increases the value by one.

  • LV_KEY_LEFT/DOWN Decreases the value by one.

Learn more about Keys.

Example

Simple Arc

Click to try in the MicroPython simulator!
#include "../../lv_examples.h"

#if LV_USE_ARC && LV_BUILD_EXAMPLES

void lv_example_arc_1(void)
{
  /*Create an Arc*/
  lv_obj_t * arc = lv_arc_create(lv_scr_act());
  lv_obj_set_size(arc, 150, 150);
  lv_arc_set_rotation(arc, 135);
  lv_arc_set_bg_angles(arc, 0, 270);
  lv_arc_set_value(arc, 40);
  lv_obj_center(arc);
}

#endif

MicroPython code     view on GitHub

# Create an Arc
arc = lv.arc(lv.scr_act())
arc.set_end_angle(200)
arc.set_size(150, 150)
arc.center()




Loader with Arc

Click to try in the MicroPython simulator!
#include "../../lv_examples.h"

#if LV_USE_ARC && LV_BUILD_EXAMPLES

static void set_angle(void * obj, int32_t v)
{
    lv_arc_set_value(obj, v);
}

/**
 * Create an arc which acts as a loader.
 */
void lv_example_arc_2(void)
{
  /*Create an Arc*/
  lv_obj_t * arc = lv_arc_create(lv_scr_act());
  lv_arc_set_rotation(arc, 270);
  lv_arc_set_bg_angles(arc, 0, 360);
  lv_obj_remove_style(arc, NULL, LV_PART_KNOB);   /*Be sure the knob is not displayed*/
  lv_obj_clear_flag(arc, LV_OBJ_FLAG_CLICKABLE);  /*To not allow adjusting by click*/
  lv_obj_center(arc);

  lv_anim_t a;
  lv_anim_init(&a);
  lv_anim_set_var(&a, arc);
  lv_anim_set_exec_cb(&a, set_angle);
  lv_anim_set_time(&a, 1000);
  lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);    /*Just for the demo*/
  lv_anim_set_repeat_delay(&a, 500);
  lv_anim_set_values(&a, 0, 100);
  lv_anim_start(&a);



}

#endif

MicroPython code     view on GitHub

#
# An `lv_timer` to call periodically to set the angles of the arc
#
class ArcLoader():
    def __init__(self):
        self.a = 270
        
    def arc_loader_cb(self,tim,arc):
        # print(tim,arc)
        self.a += 5

        arc.set_end_angle(self.a)

        if self.a >= 270 + 360:
            tim._del()


#
# Create an arc which acts as a loader.
#

# Create an Arc
arc = lv.arc(lv.scr_act())
arc.set_bg_angles(0, 360)
arc.set_angles(270, 270)
arc.center()

# create the loader
arc_loader = ArcLoader()

# Create an `lv_timer` to update the arc.

timer = lv.timer_create_basic()
timer.set_period(20)
timer.set_cb(lambda src: arc_loader.arc_loader_cb(timer,arc))
  


API

Typedefs

typedef uint8_t lv_arc_mode_t

Enums

enum [anonymous]

Values:

enumerator LV_ARC_MODE_NORMAL
enumerator LV_ARC_MODE_SYMMETRICAL
enumerator LV_ARC_MODE_REVERSE

Functions

lv_obj_t *lv_arc_create(lv_obj_t *parent)

Create a arc objects

Parameters

par -- pointer to an object, it will be the parent of the new arc

Returns

pointer to the created arc

void lv_arc_set_start_angle(lv_obj_t *arc, uint16_t start)

Set the start angle of an arc. 0 deg: right, 90 bottom, etc.

Parameters
  • arc -- pointer to an arc object

  • start -- the start angle

void lv_arc_set_end_angle(lv_obj_t *arc, uint16_t end)

Set the end angle of an arc. 0 deg: right, 90 bottom, etc.

Parameters
  • arc -- pointer to an arc object

  • end -- the end angle

void lv_arc_set_angles(lv_obj_t *arc, uint16_t start, uint16_t end)

Set the start and end angles

Parameters
  • arc -- pointer to an arc object

  • start -- the start angle

  • end -- the end angle

void lv_arc_set_bg_start_angle(lv_obj_t *arc, uint16_t start)

Set the start angle of an arc background. 0 deg: right, 90 bottom, etc.

Parameters
  • arc -- pointer to an arc object

  • start -- the start angle

void lv_arc_set_bg_end_angle(lv_obj_t *arc, uint16_t end)

Set the start angle of an arc background. 0 deg: right, 90 bottom etc.

Parameters
  • arc -- pointer to an arc object

  • end -- the end angle

void lv_arc_set_bg_angles(lv_obj_t *arc, uint16_t start, uint16_t end)

Set the start and end angles of the arc background

Parameters
  • arc -- pointer to an arc object

  • start -- the start angle

  • end -- the end angle

void lv_arc_set_rotation(lv_obj_t *arc, uint16_t rotation)

Set the rotation for the whole arc

Parameters
  • arc -- pointer to an arc object

  • rotation -- rotation angle

void lv_arc_set_mode(lv_obj_t *arc, lv_arc_mode_t type)

Set the type of arc.

Parameters
  • arc -- pointer to arc object

  • mode -- arc's mode

void lv_arc_set_value(lv_obj_t *arc, int16_t value)

Set a new value on the arc

Parameters
  • arc -- pointer to a arc object

  • value -- new value

void lv_arc_set_range(lv_obj_t *arc, int16_t min, int16_t max)

Set minimum and the maximum values of a arc

Parameters
  • arc -- pointer to the arc object

  • min -- minimum value

  • max -- maximum value

void lv_arc_set_change_rate(lv_obj_t *arc, uint16_t rate)

Set a change rate to limit the speed how fast the arc should reache the pressed point.

Parameters
  • arc -- pointer to a arc object

  • rate -- the change rate

uint16_t lv_arc_get_angle_start(lv_obj_t *obj)

Get the start angle of an arc.

Parameters

arc -- pointer to an arc object

Returns

the start angle [0..360]

uint16_t lv_arc_get_angle_end(lv_obj_t *obj)

Get the end angle of an arc.

Parameters

arc -- pointer to an arc object

Returns

the end angle [0..360]

uint16_t lv_arc_get_bg_angle_start(lv_obj_t *obj)

Get the start angle of an arc background.

Parameters

arc -- pointer to an arc object

Returns

the start angle [0..360]

uint16_t lv_arc_get_bg_angle_end(lv_obj_t *obj)

Get the end angle of an arc background.

Parameters

arc -- pointer to an arc object

Returns

the end angle [0..360]

int16_t lv_arc_get_value(const lv_obj_t *obj)

Get the value of a arc

Parameters

arc -- pointer to a arc object

Returns

the value of the arc

int16_t lv_arc_get_min_value(const lv_obj_t *obj)

Get the minimum value of a arc

Parameters

arc -- pointer to a arc object

Returns

the minimum value of the arc

int16_t lv_arc_get_max_value(const lv_obj_t *obj)

Get the maximum value of a arc

Parameters

arc -- pointer to a arc object

Returns

the maximum value of the arc

lv_arc_mode_t lv_arc_get_mode(const lv_obj_t *obj)

Get whether the arc is type or not.

Parameters

arc -- pointer to a arc object

Returns

arc's mode

Variables

const lv_obj_class_t lv_arc_class
struct lv_arc_t

Public Members

lv_obj_t obj
uint16_t rotation
uint16_t indic_angle_start
uint16_t indic_angle_end
uint16_t bg_angle_start
uint16_t bg_angle_end
int16_t value
int16_t min_value
int16_t max_value
uint16_t dragging
uint16_t type
uint16_t min_close
uint16_t chg_rate
uint32_t last_tick
int16_t last_angle