[English]

Roller （滚轮）(lv_roller)

Overview（概述）

显示原文

Roller allows you to simply select one option from a list by scrolling.

滚轮类似下拉列表，和下拉列表不同的是，滚轮有直接可见的几个选项，我们可以通过滚动滚轮中的列表来浏览并选择选项。

Parts and Styles（部分和样式）

显示原文

• LV_PART_MAIN The background of the roller uses all the typical background properties and text style properties. style_text_line_space adjusts the space between the options. When the Roller is scrolled and doesn't stop exactly on an option it will scroll to the nearest valid option automatically in anim_time milliseconds as specified in the style.

• LV_PART_SELECTED The selected option in the middle. Besides the typical background properties it uses the text style properties to change the appearance of the text in the selected area.

• LV_PART_MAIN 滚轮的背景使用了所有典型的背景属性和文本样式属性。 可以通过 style_text_line_space 调整选项之间的间隔。 当滚轮滚动并且没有完全停在一个选项上时，它将按照样式中指定的 anim_time 值(毫秒)自动滚动到前进方向最近的有效选项。

• LV_PART_SELECTED 中间选中的选项。 除了典型的背景属性之外，它还使用文本样式属性来更改所选区域中文本的外观。

Usage（用法）

Set options（设置选项）

显示原文

Options are passed to the Roller as a string with lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL). The options should be separated by \n. For example: "First\nSecond\nThird".

LV_ROLLER_MODE_INFINITE makes the roller circular.

You can select an option manually with lv_roller_set_selected(roller, id, LV_ANIM_ON), where id is the index of an option.

可以通过这个函数 lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL) 设置 Roller 中的选项。 选项之间要用 \n 分隔。 例如： "First\nSecond\nThird"。

参数 LV_ROLLER_MODE_NORMAL 是设置为正常模式（滚轮在选项结束时结束） 参数 LV_ROLLER_MODE_INFINITE 是设置为无限模式（滚轮可以一直滚动）

可以使用 lv_roller_set_selected(roller, id, LV_ANIM_ON) 手动选中一个选项，其中 id 是选项的索引，选项从 0 开始索引。

Get selected option（获取选中的选项）

显示原文

To get the index of the currently selected option use lv_roller_get_selected(roller).

lv_roller_get_selected_str(roller, buf, buf_size) will copy the name of the selected option to buf.

要获取所选中的选项的索引(index) ，可以使用函数 lv_roller_get_selected(roller)。

函数 lv_roller_get_selected_str(roller, buf, buf_size) 会将所选选项的内容复制到 buf

Visible rows（可见行）

显示原文

The number of visible rows can be adjusted with lv_roller_set_visible_row_count(roller, num).

This function calculates the height with the current style. If the font, line space, border width, etc. of the roller changes this function needs to be called again.

可见行数可以通过 lv_roller_set_visible_row_count(roller, num) 进行调整。

此函数会根据滚轮当前样式的高度（字体、行距、边框宽度等）进行调整。如果滚轮的字体、行距、边框宽度等发生变化，则需要再次调用此函数对齐重新进行调整。

Events（事件）

显示原文

• LV_EVENT_VALUE_CHANGED Sent when a new option is selected.

See the events of the Base object too.

Learn more about Events（事件）.

• 在选中选项时会触发 LV_EVENT_VALUE_CHANGED 事件（按照逻辑来说只要你滚动了滚轮中的选项都会触发此事件类型）。

可以参考 基本对象 的事件。

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

Keys（按键）

显示原文

• LV_KEY_RIGHT/DOWN Select the next option

• LV_KEY_LEFT/UP Select the previous option

• LY_KEY_ENTER Apply the selected option (Send LV_EVENT_VALUE_CHANGED event)

• LV_KEY_RIGHT/DOWN 选择下一个选项

• LV_KEY_LEFT/UP 选择上一个选项

• LY_KEY_ENTER 应用选择的选项（发送 LV_EVENT_VALUE_CHANGED 事件）

使用编码器控制时要注意有两种模式：导航模式和编辑模式

Example

[English]

Simple Roller

C code  

 View on GitHub

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

static void event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);
    if(code == LV_EVENT_VALUE_CHANGED) {
        char buf[32];
        lv_roller_get_selected_str(obj, buf, sizeof(buf));
        LV_LOG_USER("Selected month: %s\n", buf);
    }
}

/**
 * An infinite roller with the name of the months
 */
void lv_example_roller_1(void)
{
    lv_obj_t * roller1 = lv_roller_create(lv_screen_active());
    lv_roller_set_options(roller1,
                          "January\n"
                          "February\n"
                          "March\n"
                          "April\n"
                          "May\n"
                          "June\n"
                          "July\n"
                          "August\n"
                          "September\n"
                          "October\n"
                          "November\n"
                          "December",
                          LV_ROLLER_MODE_INFINITE);

    lv_roller_set_visible_row_count(roller1, 4);
    lv_obj_center(roller1);
    lv_obj_add_event_cb(roller1, event_handler, LV_EVENT_ALL, NULL);
}

#endif

---

Styling the roller

C code  

 View on GitHub

#include "../../lv_examples.h"
#if LV_USE_ROLLER && LV_FONT_MONTSERRAT_22 && LV_BUILD_EXAMPLES

static void event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);
    if(code == LV_EVENT_VALUE_CHANGED) {
        char buf[32];
        lv_roller_get_selected_str(obj, buf, sizeof(buf));
        LV_LOG_USER("Selected value: %s", buf);
    }
}

/**
 * Roller with various alignments and larger text in the selected area
 */
void lv_example_roller_2(void)
{
    /*A style to make the selected option larger*/
    static lv_style_t style_sel;
    lv_style_init(&style_sel);
    lv_style_set_text_font(&style_sel, &lv_font_montserrat_22);
    lv_style_set_bg_color(&style_sel, lv_color_hex3(0xf88));
    lv_style_set_border_width(&style_sel, 2);
    lv_style_set_border_color(&style_sel, lv_color_hex3(0xf00));

    const char * opts = "1\n2\n3\n4\n5\n6\n7\n8\n9\n10";
    lv_obj_t * roller;

    /*A roller on the left with left aligned text, and custom width*/
    roller = lv_roller_create(lv_screen_active());
    lv_roller_set_options(roller, opts, LV_ROLLER_MODE_NORMAL);
    lv_roller_set_visible_row_count(roller, 2);
    lv_obj_set_width(roller, 100);
    lv_obj_add_style(roller, &style_sel, LV_PART_SELECTED);
    lv_obj_set_style_text_align(roller, LV_TEXT_ALIGN_LEFT, 0);
    lv_obj_set_style_bg_color(roller, lv_color_hex3(0x0f0), 0);
    lv_obj_set_style_bg_grad_color(roller, lv_color_hex3(0xafa), 0);
    lv_obj_set_style_bg_grad_dir(roller, LV_GRAD_DIR_VER, 0);
    lv_obj_align(roller, LV_ALIGN_LEFT_MID, 10, 0);
    lv_obj_add_event_cb(roller, event_handler, LV_EVENT_ALL, NULL);
    lv_roller_set_selected(roller, 2, LV_ANIM_OFF);

    /*A roller on the middle with center aligned text, and auto (default) width*/
    roller = lv_roller_create(lv_screen_active());
    lv_roller_set_options(roller, opts, LV_ROLLER_MODE_NORMAL);
    lv_roller_set_visible_row_count(roller, 3);
    lv_obj_add_style(roller, &style_sel, LV_PART_SELECTED);
    lv_obj_align(roller, LV_ALIGN_CENTER, 0, 0);
    lv_obj_add_event_cb(roller, event_handler, LV_EVENT_ALL, NULL);
    lv_roller_set_selected(roller, 5, LV_ANIM_OFF);

    /*A roller on the right with right aligned text, and custom width*/
    roller = lv_roller_create(lv_screen_active());
    lv_roller_set_options(roller, opts, LV_ROLLER_MODE_NORMAL);
    lv_roller_set_visible_row_count(roller, 4);
    lv_obj_set_width(roller, 80);
    lv_obj_add_style(roller, &style_sel, LV_PART_SELECTED);
    lv_obj_set_style_text_align(roller, LV_TEXT_ALIGN_RIGHT, 0);
    lv_obj_align(roller, LV_ALIGN_RIGHT_MID, -10, 0);
    lv_obj_add_event_cb(roller, event_handler, LV_EVENT_ALL, NULL);
    lv_roller_set_selected(roller, 8, LV_ANIM_OFF);
}

#endif

---

add fade mask to roller

C code  

 View on GitHub

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

#if LV_USE_ROLLER && LV_DRAW_SW_COMPLEX && LV_BUILD_EXAMPLES && 1

static void generate_mask(lv_draw_buf_t * mask)
{
    /*Create a "8 bit alpha" canvas and clear it*/
    lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
    lv_canvas_set_draw_buf(canvas, mask);
    lv_canvas_fill_bg(canvas, lv_color_white(), LV_OPA_TRANSP);

    lv_layer_t layer;
    lv_canvas_init_layer(canvas, &layer);

    /*Draw a label to the canvas. The result "image" will be used as mask*/
    lv_draw_rect_dsc_t rect_dsc;
    lv_draw_rect_dsc_init(&rect_dsc);
    rect_dsc.bg_grad.dir = LV_GRAD_DIR_VER;
    rect_dsc.bg_grad.stops[0].color = lv_color_black();
    rect_dsc.bg_grad.stops[1].color = lv_color_white();
    rect_dsc.bg_grad.stops[0].opa = LV_OPA_COVER;
    rect_dsc.bg_grad.stops[1].opa = LV_OPA_COVER;
    lv_area_t a = {0, 0, mask->header.w - 1, mask->header.h / 2 - 10};
    lv_draw_rect(&layer, &rect_dsc, &a);

    a.y1 = mask->header.h / 2 + 10;
    a.y2 = mask->header.h - 1;
    rect_dsc.bg_grad.stops[0].color = lv_color_white();
    rect_dsc.bg_grad.stops[1].color = lv_color_black();
    lv_draw_rect(&layer, &rect_dsc, &a);

    lv_canvas_finish_layer(canvas, &layer);

    /*Comment it to make the mask visible*/
    lv_obj_delete(canvas);
}

/**
 * Add a fade mask to roller.
 */
void lv_example_roller_3(void)
{
    lv_obj_set_style_bg_color(lv_screen_active(), lv_palette_main(LV_PALETTE_BLUE_GREY), 0);

    static lv_style_t style;
    lv_style_init(&style);
    lv_style_set_bg_color(&style, lv_color_black());
    lv_style_set_text_color(&style, lv_color_white());
    lv_style_set_border_width(&style, 0);
    lv_style_set_radius(&style, 0);

    lv_obj_t * roller1 = lv_roller_create(lv_screen_active());
    lv_obj_add_style(roller1, &style, 0);
    lv_obj_set_style_bg_opa(roller1, LV_OPA_50, LV_PART_SELECTED);

    lv_roller_set_options(roller1,
                          "January\n"
                          "February\n"
                          "March\n"
                          "April\n"
                          "May\n"
                          "June\n"
                          "July\n"
                          "August\n"
                          "September\n"
                          "October\n"
                          "November\n"
                          "December",
                          LV_ROLLER_MODE_NORMAL);

    lv_obj_center(roller1);
    lv_roller_set_visible_row_count(roller1, 4);

    /* Create the mask to make the top and bottom part of roller faded.
     * The width and height are empirical values for simplicity*/
    LV_DRAW_BUF_DEFINE_STATIC(mask, 130, 150, LV_COLOR_FORMAT_L8);
    LV_DRAW_BUF_INIT_STATIC(mask);

    generate_mask(&mask);
    lv_obj_set_style_bitmap_mask_src(roller1, &mask, 0);
}
#endif

---

API

lv_api_map_v8.h

lv_roller.h

lv_types.h

lv_obj_property_names.h

lv_observer.h