Arc（圆弧） (lv_arc)

Overview（概述）

显示原文

The Arc consists of a background and a foreground arc. The foreground (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 another 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.

LV_PART_MAIN 使用典型背景样式特性绘制背景，使用圆弧样式特性绘制圆弧。圆弧的大小和位置遵循填充（padding）样式属性。
LV_PART_INDICATOR 使用圆弧（arc）样式属性绘制出来的另一条圆弧。它的填充值是相对于背景弧来解释的。
LV_PART_KNOB 在指标的末尾绘制一个旋钮，使用所有背景属性和填充值。如果使用零填充，旋钮大小与指示器的宽度相同。较大的填充使其更大，较小的填充使其更小。

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 0..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.

可以使用 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] 范围内。

Rotation（旋转）

显示原文

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

可以用 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 minimum 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 angle is set by lv_arc_set_value() or the arc is adjusted by finger.

弧线可以是以下模式之一：

LV_ARC_MODE_NORMAL 普通模式。指示器从最小值绘制到当前值。
LV_ARC_MODE_REVERSE 反向模式。指示器从最大值到当前值逆时针绘制。
LV_ARC_MODE_SYMMETRICAL 对称模式。指示器从中间点绘制到当前值。

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

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)

如果按下弧形键，当前值将以一定的速度反映在前景弧的变化上，这个变化的过程称为 变化率。变化率以度/秒为单位，可以用 lv_arc_set_change_rage(arc, rate) 设置。（简单的理解就是arc的前景弧到达某个值所需要的时间，时间单位是度/秒）

Knob offset（旋钮偏移）

显示原文

Changing the knob offset allows the location of the knob to be moved relative to the end of the arc The knob offset can be set by lv_arc_set_knob_offset(arc, offset_angle), will only be visible if LV_PART_KNOB is visible

旋钮的位置可以通过设置偏移值调整，如果不调整默认位于前景弧最末端处，调整偏移后可以在其之前以及之后。旋钮偏移可以通过 lv_arc_set_knob_offset(arc, offset_angle) 设置，只在 LV_PART_KNOB 部分生效。

Setting the indicator manually（手动设置指示器部分）

显示原文

It's 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" are ignored.

In other words, the angle and value settings are independent. You should exclusively use one or the other. Mixing the two might result in unintended behavior.

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

也可以使用 lv_arc_set_angles(arc, start_angle, end_angle) 函数或 lv_arc_set_start/end_angle(arc, start_angle) 直接设置指示器部分的角度(零度位于对象的中间右侧（3 点钟方向），并且度数沿顺时针方向增加。)。在这种情况下，设置的 “值” 和 “模式” 将被忽略。

换言之，角度和值设置是独立的。你应该只使用其中之一。将两者混合可能会导致意外行为。

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

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

Advanced hit test（高级触摸测试）

显示原文

If the LV_OBJ_FLAG_ADV_HITTEST flag is enabled the arc can be clicked through in the middle. Clicks are recognized only on the ring of the background arc. lv_obj_set_ext_click_size() makes the sensitive area larger inside and outside with the given number of pixels.

如果启用了 LV_OBJ_FLAG_ADV_HITTEST 标志，则弧可以在中间点击。只有在环上才能识别点击背景弧。 lv_obj_set_ext_click_size() 使敏感在给定的像素数下，内部和外部区域更大。

Place another object to the knob（将另一个对象放在旋钮上）

显示原文

Another object can be positioned according to the current position of the arc in order to follow the arc's current value (angle). To do this use lv_arc_align_obj_to_angle(arc, obj_to_align, radius_offset).

Similarly lv_arc_rotate_obj_to_angle(arc, obj_to_rotate, radius_offset) can be used to rotate the object to the current value of the arc.

It's a typical use case to call these functions in the VALUE_CHANGED event of the arc.

另一个对象可以根据当前位置定位弧，以便遵循弧的当前值（角度）。为此，执行此操作请使用 lv_arc_align_obj_to_angle(arc, obj_to_align, radius_offset)。

类似地，lv_arc_rotate_obj_to_angle(arc, obj_to_rotate, radius_offset) 可以是用于将对象根据旋钮的角度旋转之后再对齐到arc的旋钮的位置上。

在 VALUE_CHANGED 发生弧形时调用这些函数是一个典型的用例。

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 with the following types:
- LV_ARC_DRAW_PART_BACKGROUND The background arc.
  - part: LV_PART_MAIN
  - p1: center of the arc
  - radius: radius of the arc
  - arc_dsc
- LV_ARC_DRAW_PART_FOREGROUND The foreground arc.
  - part: LV_PART_INDICATOR
  - p1: center of the arc
  - radius: radius of the arc
  - arc_dsc
- LV_ARC_DRAW_PART_KNOB The knob
  - part: LV_PART_KNOB
  - draw_area: the area of the knob
  - rect_dsc:

See the events of the Base object too.

Learn more about Events（事件）.

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:

Keys（按键）

显示原文

LV_KEY_RIGHT/UP Increases the value by one.
LV_KEY_LEFT/DOWN Decreases the value by one.

Learn more about Keys（按键）.

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

了解有关 :ref:`indev_按键`的更多信息。

Example

[English]

Simple Arc

A simple example to demonstrate the use of an arc.

#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_screen_active());

    /*Create an Arc*/
    lv_obj_t * arc = lv_arc_create(lv_screen_active());
    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_obj_send_event(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, "%" LV_PRId32 "%%", 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

Loader with Arc

#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_screen_active());
    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_remove_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_duration(&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

API

lv_arc.h

lv_observer.h

lv_types.h

Arc（圆弧 ） (lv_arc)

Overview（概述）

Parts and Styles（部分和样式）

Usage（用法）

Value and range（值和范围）

Rotation（旋转）

Mode（模式）

Change rate（变化率）

Knob offset（旋钮偏移）

Setting the indicator manually（手动设置指示器部分）

Advanced hit test（高级触摸测试）

Place another object to the knob（将另一个对象放在旋钮上）

Events（事件）

Keys（按键）

Example

Simple Arc

Loader with Arc

API

Arc（圆弧） (lv_arc)