弧形控件 (lv_arc)¶

概述¶

弧形控件由背景弧和前景弧组成。前景弧（指示器）可以通过触摸进行调整。

部件和样式¶

LV_PART_MAIN 使用典型的背景样式属性绘制背景，并使用弧样式属性绘制弧。弧的大小和位置将遵循内边距样式属性。
LV_PART_INDICATOR 使用弧样式属性绘制另一个弧。其内边距值相对于背景弧进行解释。
LV_PART_KNOB 使用所有背景属性和内边距值在指示器的末端绘制一个手柄。当内边距为零时，旋钮的大小与指示器的宽度相同。更大的内边距会使其更大，更小的内边距会使其更小。

用法¶

值和范围¶

可以使用 lv_arc_set_value(arc, new_value) 设置新值。该值在一个范围内（最小值和最大值）进行解释，可以通过 lv_arc_set_range(arc, min, max) 修改范围。默认范围是 0..100。

指示器弧绘制在主部件的弧上。如果值设置为最大值，指示器弧将覆盖整个“背景”弧。可以使用 lv_arc_set_bg_angles(arc, start_angle, end_angle) 函数或 lv_arc_set_bg_start/end_angle(arc, angle) 设置背景弧的起始和结束角度。

零度位于对象的右中间（3 点钟方向），角度按顺时针方向增加。角度应在 [0;360] 范围内。

旋转¶

可以使用 lv_arc_set_rotation(arc, deg) 为零度位置添加一个偏移量。

模式¶

弧可以是以下模式之一：

LV_ARC_MODE_NORMAL 指示器弧从最小值绘制到当前值。
LV_ARC_MODE_REVERSE 指示器弧从最大值逆时针绘制到当前值。
LV_ARC_MODE_SYMMETRICAL 指示器弧从中点绘制到当前值。

可以通过 lv_arc_set_mode(arc, LV_ARC_MODE_...) 设置模式，仅在通过 lv_arc_set_value() 设置角度或通过手指调整弧时使用。

改变速率¶

如果按下弧，当前值将根据设置的改变速率以有限的速度设置。改变速率以度/秒为单位，可以通过 lv_arc_set_change_rage(arc, rate) 设置。

手动设置指示器¶

也可以直接使用 lv_arc_set_angles(arc, start_angle, end_angle) 函数或 lv_arc_set_start/end_angle(arc, start_angle) 设置指示器弧的角度。在这种情况下，设置的“值”和“模式”将被忽略。

换句话说，角度和值设置是独立的。您应该专门使用其中之一。混合使用可能会导致意外行为。

要使弧不可调整，请移除旋钮的样式并使对象不可点击：

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

高级点击测试¶

如果启用了 LV_OBJ_FLAG_ADV_HITTEST 标志，则可以通过弧的中间进行点击。仅在背景弧的环上识别点击。lv_obj_set_ext_click_size() 可以使敏感区域在内外扩展给定的像素数。

在旋钮上放置另一个对象¶

可以根据弧的当前位置定位另一个对象，以跟随弧的当前值（角度）。为此，请使用 lv_arc_align_obj_to_angle(arc, obj_to_align, radius_offset)。

类似地，可以使用 lv_arc_rotate_obj_to_angle(arc, obj_to_rotate, radius_offset) 将对象旋转到弧的当前值。

在弧的 VALUE_CHANGED 事件中调用这些函数是一个典型的用例。

事件¶

LV_EVENT_VALUE_CHANGED 当按下/拖动弧以设置新值时发送。
LV_EVENT_DRAW_PART_BEGIN 和 LV_EVENT_DRAW_PART_END 发送以下类型：
- LV_ARC_DRAW_PART_BACKGROUND 背景弧。
  - part: LV_PART_MAIN
  - p1: 弧的中心
  - radius: 弧的半径
  - arc_dsc
- LV_ARC_DRAW_PART_FOREGROUND 前景弧。
  - part: LV_PART_INDICATOR
  - p1: 弧的中心
  - radius: 弧的半径
  - arc_dsc
- LV_ARC_DRAW_PART_KNOB 旋钮
  - part: LV_PART_KNOB
  - draw_area: 旋钮的区域
  - rect_dsc:

另请参阅基础对象的事件。

了解更多关于事件的信息。

按键¶

LV_KEY_RIGHT/UP 将值增加 1。
LV_KEY_LEFT/DOWN 将值减少 1。

了解更多关于按键的信息。

示例¶

简单的弧形¶

一个简单的示例，用于演示弧形的使用。

#include "../../lv_examples.h"

#if LV_USE_ARC && LV_BUILD_EXAMPLES

static void value_changed_event_cb(lv_event_t * e);

void lv_example_arc_1(void)
{
    lv_obj_t * label = lv_label_create(lv_scr_act());

    /*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, 10);
    lv_obj_center(arc);
    lv_obj_add_event_cb(arc, value_changed_event_cb, LV_EVENT_VALUE_CHANGED, label);

    /*Manually update the label for the first time*/
    lv_event_send(arc, LV_EVENT_VALUE_CHANGED, NULL);
}

static void value_changed_event_cb(lv_event_t * e)
{
    lv_obj_t * arc = lv_event_get_target(e);
    lv_obj_t * label = lv_event_get_user_data(e);

    lv_label_set_text_fmt(label, "%d%%", lv_arc_get_value(arc));

    /*Rotate the label to the current position of the arc*/
    lv_arc_rotate_obj_to_angle(arc, label, 25);
}

#endif

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

带弧形的加载器¶

#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

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

Values:

enumerator LV_ARC_MODE_NORMAL¶

enumerator LV_ARC_MODE_SYMMETRICAL¶

enumerator LV_ARC_MODE_REVERSE¶

enum lv_arc_draw_part_type_t¶

type field in lv_obj_draw_part_dsc_t if class_p = lv_arc_class Used in LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END

Values:

enumerator LV_ARC_DRAW_PART_BACKGROUND¶: The background arc

enumerator LV_ARC_DRAW_PART_FOREGROUND¶: The foreground arc

enumerator LV_ARC_DRAW_PART_KNOB¶: The knob

Functions

lv_obj_t *lv_arc_create(lv_obj_t *parent)¶

Create an arc object

Parameters: parent -- 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 *obj, uint16_t start)¶

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

Parameters

obj -- pointer to an arc object
start -- the start angle

void lv_arc_set_end_angle(lv_obj_t *obj, uint16_t end)¶

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

Parameters

obj -- pointer to an arc object
end -- the end angle

void lv_arc_set_angles(lv_obj_t *obj, uint16_t start, uint16_t end)¶

Set the start and end angles

Parameters

obj -- pointer to an arc object
start -- the start angle
end -- the end angle

void lv_arc_set_bg_start_angle(lv_obj_t *obj, uint16_t start)¶

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

Parameters

obj -- pointer to an arc object
start -- the start angle

void lv_arc_set_bg_end_angle(lv_obj_t *obj, uint16_t end)¶

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

Parameters

obj -- pointer to an arc object
end -- the end angle

void lv_arc_set_bg_angles(lv_obj_t *obj, uint16_t start, uint16_t end)¶

Set the start and end angles of the arc background

Parameters

obj -- pointer to an arc object
start -- the start angle
end -- the end angle

void lv_arc_set_rotation(lv_obj_t *obj, uint16_t rotation)¶

Set the rotation for the whole arc

Parameters

obj -- pointer to an arc object
rotation -- rotation angle

void lv_arc_set_mode(lv_obj_t *obj, lv_arc_mode_t type)¶

Set the type of arc.

Parameters

obj -- pointer to arc object
mode -- arc's mode

void lv_arc_set_value(lv_obj_t *obj, int16_t value)¶

Set a new value on the arc

Parameters

obj -- pointer to an arc object
value -- new value

void lv_arc_set_range(lv_obj_t *obj, int16_t min, int16_t max)¶

Set minimum and the maximum values of an arc

Parameters

obj -- pointer to the arc object
min -- minimum value
max -- maximum value

void lv_arc_set_change_rate(lv_obj_t *obj, uint16_t rate)¶

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

Parameters

obj -- pointer to an 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: obj -- 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: obj -- 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: obj -- 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: obj -- 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 an arc

Parameters: obj -- pointer to an 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 an arc

Parameters: obj -- pointer to an 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 an arc

Parameters: obj -- pointer to an 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: obj -- pointer to an arc object
Returns: arc's mode

void lv_arc_align_obj_to_angle(const lv_obj_t *obj, lv_obj_t *obj_to_align, lv_coord_t r_offset)¶

Align an object to the current position of the arc (knob)

Parameters

obj -- pointer to an arc object
obj_to_align -- pointer to an object to align
r_offset -- consider the radius larger with this value (< 0: for smaller radius)

void lv_arc_rotate_obj_to_angle(const lv_obj_t *obj, lv_obj_t *obj_to_rotate, lv_coord_t r_offset)¶

Rotate an object to the current position of the arc (knob)

Parameters

obj -- pointer to an arc object
obj_to_align -- pointer to an object to rotate
r_offset -- consider the radius larger with this value (< 0: for smaller radius)

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¶