[English]

Slider （滑动条）(lv_slider)

Overview（概述）

显示原文

The Slider object looks like a Bar supplemented with a knob. The knob can be dragged to set a value. Just like Bar, Slider can be vertical or horizontal.

滑动条对象看起来像是在 进度条 增加了一个可以调节的旋钮，使用时可以通过拖动旋钮来设置一个值。 就像进度条(bar)一样，Slider可以是垂直的或水平的(当设置进度条的宽度小于其高度，就可以创建出垂直摆放的滑动条)。

Parts and Styles（零件和样式）

显示原文

• LV_PART_MAIN The background of the slider. Uses all the typical background style properties. padding makes the indicator smaller in the respective direction.

• LV_PART_INDICATOR The indicator that shows the current state of the slider. Also uses all the typical background style properties.

• LV_PART_KNOB A rectangle (or circle) drawn at the current value. Also uses all the typical background properties to describe the knob(s). By default, the knob is square (with an optional corner radius) with side length equal to the smaller side of the slider. The knob can be made larger with the padding values. Padding values can be asymmetric too.

• LV_PART_MAIN 滑动条的背景。 使用所有典型的背景样式属性。 设置 padding 样式会使指标在相应方向上变小。

• LV_PART_INDICATOR 显示滑动条当前状态的指示器。 也是使用所有典型的背景样式属性。

• LV_PART_KNOB 旋钮(可以是原形或矩形)。 也是使用所有典型的背景属性。 默认情况下，旋钮是方形的（带有可选的圆角半径），边长等于滑动条的较小边。 可以通过设置 padding 样式调整旋钮的大小。 填充值也可以是不对称的。

Usage（用法）

Value and range（值和范围）

显示原文

To set an initial value use lv_slider_set_value(slider, new_value, LV_ANIM_ON / OFF). The animation time is set by the styles' anim_time property.

To specify the range (min, max values), lv_slider_set_range(slider, min, max) can be used. The default range is 0..100, and the default drawing direction is from left to right in horizontal mode and bottom to top in vertical mode. If the minimum value is greater than the maximum value, like 100..0, the drawing direction changes to the opposite direction.

要设置滑动条的初始值，请使用 lv_slider_set_value(slider, new_value, LV_ANIM_ON / OFF)。 动画时间由样式的 anim_time 属性设置。

要指定滑动条的范围（最小值、最大值），可以使用 lv_slider_set_range(slider, min, max) 。默认范围为 0..100，在水平模式下默认绘制方向为从左到右，并且垂直模式下从下到上。如果最小值大于最大值，如100..0时，绘制方向变为相反的方向。

Modes（模式）

显示原文

The slider can be one of the following modes:

• LV_SLIDER_MODE_NORMAL A normal slider as described above

• LV_SLIDER_SYMMETRICAL Draw the indicator form the zero value to current value. Requires negative minimum range and positive maximum range.

• LV_SLIDER_RANGE Allows setting the start value too by lv_bar_set_start_value(bar, new_value, LV_ANIM_ON / OFF). The start value has to be always smaller than the end value.

The mode can be changed with lv_slider_set_mode(slider, LV_SLIDER_MODE_...)

与bar类似，滑动条可以是以下模式之一：

• LV_SLIDER_MODE_NORMAL 像上面说的普通情况

• LV_SLIDER_SYMMETRICAL 这个模式下可以指定负的最小范围。但是只能从零值到当前值绘制指示器。

• LV_SLIDER_RANGE 在这个模式下也可以指定负的最小范围。这样滑动条的起始值可以不是0，使用 lv_bar_set_start_value(bar, new_value, LV_ANIM_ON / OFF) 设置起始值。要注意设置的起始值必须小于结束值。

可以使用 lv_slider_set_mode(slider, LV_SLIDER_MODE_...) 更改模式。

Knob-only mode（仅旋钮模式）

显示原文

Normally, the slider can be adjusted either by dragging the knob, or by clicking on the slider bar. In the latter case the knob moves to the point clicked and slider value changes accordingly. In some cases it is desirable to set the slider to react on dragging the knob only. This feature is enabled by adding the LV_OBJ_FLAG_ADV_HITTEST: lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST).

The extended click area (set by lv_obj_set_ext_click_area(slider, value)) increases to knob's click area.

通常，可以通过拖动旋钮或单击滑动条来调整滑动条的值。 在后一种情况下，旋钮会移动到单击的点，指示器也会相应更改。在某些情况下，需要将滑动条设置为仅对拖动旋钮做出反应，可以通过添加 LV_OBJ_FLAG_ADV_HITTEST lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST) 来启用此功能。

扩展的单击区域(由 lv_obj_set_ext_click_area(slider, value) 设置)增加到旋钮的单击区域。

Events（事件）

显示原文

• LV_EVENT_VALUE_CHANGED Sent while the slider is being dragged or changed with keys. The event is sent continuously while the slider is being dragged.

• LV_EVENT_RELEASED Sent when the slider has just been released.

See the events of the Bar too.

Learn more about Events（事件）.

• LV_EVENT_VALUE_CHANGED 在拖动滑块或用键更改。当滑块处于被拖拽。

• LV_EVENT_RELEASED 在刚刚释放滑块时发送。

也可以查看 Bar 的事件。

详细了解更多 Events（事件）。

Keys（按键）

显示原文

• LV_KEY_UP/RIGHT Increment the slider's value by 1

• LV_KEY_DOWN/LEFT Decrement the slider's value by 1

Learn more about Keys（按键）.

• LV_KEY_UP/RIGHT 将滑动条的值增加 1

• LV_KEY_DOWN/LEFT 将滑动条的值减 1

了解有关 Keys（按键） 的更多信息。

Example

[English]

Simple Slider

C code  

 View on GitHub

#include "../../lv_examples.h"
#if LV_USE_SLIDER && LV_BUILD_EXAMPLES

static void slider_event_cb(lv_event_t * e);
static lv_obj_t * slider_label;

/**
 * A default slider with a label displaying the current value
 */
void lv_example_slider_1(void)
{
    /*Create a slider in the center of the display*/
    lv_obj_t * slider = lv_slider_create(lv_screen_active());
    lv_obj_center(slider);
    lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_VALUE_CHANGED, NULL);

    lv_obj_set_style_anim_duration(slider, 2000, 0);
    /*Create a label below the slider*/
    slider_label = lv_label_create(lv_screen_active());
    lv_label_set_text(slider_label, "0%");

    lv_obj_align_to(slider_label, slider, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
}

static void slider_event_cb(lv_event_t * e)
{
    lv_obj_t * slider = lv_event_get_target(e);
    char buf[8];
    lv_snprintf(buf, sizeof(buf), "%d%%", (int)lv_slider_get_value(slider));
    lv_label_set_text(slider_label, buf);
    lv_obj_align_to(slider_label, slider, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
}

#endif

---

Slider with custom style

C code  

 View on GitHub

#include "../../lv_examples.h"
#if LV_USE_SLIDER && LV_BUILD_EXAMPLES

/**
 * Show how to style a slider.
 */
void lv_example_slider_2(void)
{
    /*Create a transition*/
    static const lv_style_prop_t props[] = {LV_STYLE_BG_COLOR, 0};
    static lv_style_transition_dsc_t transition_dsc;
    lv_style_transition_dsc_init(&transition_dsc, props, lv_anim_path_linear, 300, 0, NULL);

    static lv_style_t style_main;
    static lv_style_t style_indicator;
    static lv_style_t style_knob;
    static lv_style_t style_pressed_color;
    lv_style_init(&style_main);
    lv_style_set_bg_opa(&style_main, LV_OPA_COVER);
    lv_style_set_bg_color(&style_main, lv_color_hex3(0xbbb));
    lv_style_set_radius(&style_main, LV_RADIUS_CIRCLE);
    lv_style_set_pad_ver(&style_main, -2); /*Makes the indicator larger*/

    lv_style_init(&style_indicator);
    lv_style_set_bg_opa(&style_indicator, LV_OPA_COVER);
    lv_style_set_bg_color(&style_indicator, lv_palette_main(LV_PALETTE_CYAN));
    lv_style_set_radius(&style_indicator, LV_RADIUS_CIRCLE);
    lv_style_set_transition(&style_indicator, &transition_dsc);

    lv_style_init(&style_knob);
    lv_style_set_bg_opa(&style_knob, LV_OPA_COVER);
    lv_style_set_bg_color(&style_knob, lv_palette_main(LV_PALETTE_CYAN));
    lv_style_set_border_color(&style_knob, lv_palette_darken(LV_PALETTE_CYAN, 3));
    lv_style_set_border_width(&style_knob, 2);
    lv_style_set_radius(&style_knob, LV_RADIUS_CIRCLE);
    lv_style_set_pad_all(&style_knob, 6); /*Makes the knob larger*/
    lv_style_set_transition(&style_knob, &transition_dsc);

    lv_style_init(&style_pressed_color);
    lv_style_set_bg_color(&style_pressed_color, lv_palette_darken(LV_PALETTE_CYAN, 2));

    /*Create a slider and add the style*/
    lv_obj_t * slider = lv_slider_create(lv_screen_active());
    lv_obj_remove_style_all(slider);        /*Remove the styles coming from the theme*/

    lv_obj_add_style(slider, &style_main, LV_PART_MAIN);
    lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR);
    lv_obj_add_style(slider, &style_pressed_color, LV_PART_INDICATOR | LV_STATE_PRESSED);
    lv_obj_add_style(slider, &style_knob, LV_PART_KNOB);
    lv_obj_add_style(slider, &style_pressed_color, LV_PART_KNOB | LV_STATE_PRESSED);

    lv_obj_center(slider);
}

#endif

---

Slider with extended drawer

C code  

 View on GitHub

#include "../../lv_examples.h"
#if LV_USE_SLIDER && LV_BUILD_EXAMPLES

#define MAX_VALUE 100
#define MIN_VALUE 0

static void slider_event_cb(lv_event_t * e);

/**
 * Show the current value when the slider is pressed by extending the drawer
 *
 */
void lv_example_slider_3(void)
{
    /*Create a slider in the center of the display*/
    lv_obj_t * slider;
    slider = lv_slider_create(lv_screen_active());
    lv_obj_center(slider);

    lv_slider_set_mode(slider, LV_SLIDER_MODE_RANGE);
    lv_slider_set_range(slider, MIN_VALUE, MAX_VALUE);
    lv_slider_set_value(slider, 70, LV_ANIM_OFF);
    lv_slider_set_left_value(slider, 20, LV_ANIM_OFF);

    lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_ALL, NULL);
    lv_obj_refresh_ext_draw_size(slider);
}

static void slider_event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);

    /*Provide some extra space for the value*/
    if(code == LV_EVENT_REFR_EXT_DRAW_SIZE) {
        lv_event_set_ext_draw_size(e, 50);
    }
    else if(code == LV_EVENT_DRAW_MAIN_END) {
        if(!lv_obj_has_state(obj, LV_STATE_PRESSED)) return;

        lv_area_t slider_area;
        lv_obj_get_coords(obj, &slider_area);
        lv_area_t indic_area = slider_area;
        lv_area_set_width(&indic_area, lv_area_get_width(&slider_area) * lv_slider_get_value(obj) / MAX_VALUE);
        indic_area.x1 += lv_area_get_width(&slider_area) * lv_slider_get_left_value(obj) / MAX_VALUE;
        char buf[16];
        lv_snprintf(buf, sizeof(buf), "%d - %d", (int)lv_slider_get_left_value(obj), (int)lv_slider_get_value(obj));

        lv_point_t label_size;
        lv_text_get_size(&label_size, buf, LV_FONT_DEFAULT, 0, 0, LV_COORD_MAX, 0);
        lv_area_t label_area;
        label_area.x1 = 0;
        label_area.x2 = label_size.x - 1;
        label_area.y1 = 0;
        label_area.y2 = label_size.y - 1;

        lv_area_align(&indic_area, &label_area, LV_ALIGN_OUT_TOP_MID, 0, -10);

        lv_draw_label_dsc_t label_draw_dsc;
        lv_draw_label_dsc_init(&label_draw_dsc);
        label_draw_dsc.color = lv_color_hex3(0x888);
        label_draw_dsc.text = buf;
        label_draw_dsc.text_local = true;
        lv_layer_t * layer = lv_event_get_layer(e);
        lv_draw_label(layer, &label_draw_dsc, &label_area);
    }
}

#endif

---

Slider with opposite direction

C code  

 View on GitHub

#include "../../lv_examples.h"
#if LV_USE_SLIDER && LV_BUILD_EXAMPLES

static void slider_event_cb(lv_event_t * e);
static lv_obj_t * slider_label;

/**
 * Slider with opposite direction
 */
void lv_example_slider_4(void)
{
    /*Create a slider in the center of the display*/
    lv_obj_t * slider = lv_slider_create(lv_screen_active());
    lv_obj_center(slider);
    lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
    /*Reverse the direction of the slider*/
    lv_slider_set_range(slider, 100, 0);
    /*Create a label below the slider*/
    slider_label = lv_label_create(lv_screen_active());
    lv_label_set_text(slider_label, "0%");

    lv_obj_align_to(slider_label, slider, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
}

static void slider_event_cb(lv_event_t * e)
{
    lv_obj_t * slider = lv_event_get_target(e);
    char buf[8];
    lv_snprintf(buf, sizeof(buf), "%d%%", (int)lv_slider_get_value(slider));
    lv_label_set_text(slider_label, buf);
    lv_obj_align_to(slider_label, slider, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
}

#endif

---

API

lv_types.h

lv_observer.h

lv_slider.h