[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"
//TODO
#if LV_USE_ROLLER && LV_DRAW_SW_COMPLEX && LV_BUILD_EXAMPLES && 0

static void mask_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);

    static int16_t mask_top_id = -1;
    static int16_t mask_bottom_id = -1;

    if(code == LV_EVENT_COVER_CHECK) {
        lv_event_set_cover_res(e, LV_COVER_RES_MASKED);

    }
    else if(code == LV_EVENT_DRAW_MAIN_BEGIN) {
        /* add mask */
        const lv_font_t * font = lv_obj_get_style_text_font(obj, LV_PART_MAIN);
        int32_t line_space = lv_obj_get_style_text_line_space(obj, LV_PART_MAIN);
        int32_t font_h = lv_font_get_line_height(font);

        lv_area_t roller_coords;
        lv_obj_get_coords(obj, &roller_coords);

        lv_area_t rect_area;
        rect_area.x1 = roller_coords.x1;
        rect_area.x2 = roller_coords.x2;
        rect_area.y1 = roller_coords.y1;
        rect_area.y2 = roller_coords.y1 + (lv_obj_get_height(obj) - font_h - line_space) / 2;

        lv_draw_mask_fade_param_t * fade_mask_top = lv_malloc(sizeof(lv_draw_mask_fade_param_t));
        lv_draw_mask_fade_init(fade_mask_top, &rect_area, LV_OPA_TRANSP, rect_area.y1, LV_OPA_COVER, rect_area.y2);
        mask_top_id = lv_draw_mask_add(fade_mask_top, NULL);

        rect_area.y1 = rect_area.y2 + font_h + line_space - 1;
        rect_area.y2 = roller_coords.y2;

        lv_draw_mask_fade_param_t * fade_mask_bottom = lv_malloc(sizeof(lv_draw_mask_fade_param_t));
        lv_draw_mask_fade_init(fade_mask_bottom, &rect_area, LV_OPA_COVER, rect_area.y1, LV_OPA_TRANSP, rect_area.y2);
        mask_bottom_id = lv_draw_mask_add(fade_mask_bottom, NULL);

    }
    else if(code == LV_EVENT_DRAW_POST_END) {
        lv_draw_mask_fade_param_t * fade_mask_top = lv_draw_mask_remove_id(mask_top_id);
        lv_draw_mask_fade_param_t * fade_mask_bottom = lv_draw_mask_remove_id(mask_bottom_id);
        lv_draw_mask_free_param(fade_mask_top);
        lv_draw_mask_free_param(fade_mask_bottom);
        lv_free(fade_mask_top);
        lv_free(fade_mask_bottom);
        mask_top_id = -1;
        mask_bottom_id = -1;
    }
}

/**
 * Add a fade mask to roller.
 */
void lv_example_roller_3(void)
{
    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_pad_all(&style, 0);
    lv_obj_add_style(lv_screen_active(), &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_TRANSP, LV_PART_SELECTED);

#if LV_FONT_MONTSERRAT_22
    lv_obj_set_style_text_font(roller1, &lv_font_montserrat_22, LV_PART_SELECTED);
#endif

    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, 3);
    lv_obj_add_event_cb(roller1, mask_event_cb, LV_EVENT_ALL, NULL);
}
#endif

---

API

lv_api_map_v8.h

lv_observer.h

lv_roller.h