滚轮 (lv_roller)

概述

滚轮允许通过滚动简单地从列表中选择一个选项。

部件和样式

• LV_PART_MAIN 滚轮的背景使用所有典型的背景属性和文本样式属性。style_text_line_space 调整选项之间的间距。 当滚轮滚动并未完全停在某个选项上时，它会在样式中指定的 anim_time 毫秒内自动滚动到最近的有效选项。

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

用法

设置选项

选项以字符串形式传递给滚轮，使用 lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL/INFINITE)。选项应以 \n 分隔。例如："第一个\n第二个\n第三个"。

LV_ROLLER_MODE_INFINITE 使滚轮变为循环模式。

可以使用 lv_roller_set_selected(roller, id, LV_ANIM_ON/OFF) 手动选择一个选项，其中 id 是选项的索引。

获取选中选项

要获取当前选中选项的 索引，请使用 lv_roller_get_selected(roller)。

lv_roller_get_selected_str(roller, buf, buf_size) 会将选中选项的名称复制到 buf 中。

可见行数

可以使用 lv_roller_set_visible_row_count(roller, num) 调整可见行数。

此函数会根据当前样式计算高度。如果滚轮的字体、行间距、边框宽度等发生变化，则需要再次调用此函数。

事件

• LV_EVENT_VALUE_CHANGED 当选择了新选项时发送。

也可以查看 基础对象 的事件。

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

按键

• LV_KEY_RIGHT/DOWN 选择下一个选项

• LV_KEY_LEFT/UP 选择上一个选项

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

示例

Simple Roller

C code  

 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_scr_act());
    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

MicroPython code  

 GitHub Simulator

def event_handler(e):
    code = e.get_code()
    obj = e.get_target()
    if code == lv.EVENT.VALUE_CHANGED:
        option = " "*10
        obj.get_selected_str(option, len(option))
        print("Selected month: " + option.strip())

#
# An infinite roller with the name of the months
#

roller1 = lv.roller(lv.scr_act())
roller1.set_options("\n".join([
    "January",
    "February",
    "March",
    "April",
    "May",
    "June",
    "July",
    "August",
    "September",
    "October",
    "November",
    "December"]),lv.roller.MODE.INFINITE)

roller1.set_visible_row_count(4)
roller1.center()
roller1.add_event_cb(event_handler, lv.EVENT.ALL, None)

---

Styling the roller

C code  

 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);

    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_scr_act());
    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_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_scr_act());
    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_scr_act());
    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

MicroPython code  

 GitHub Simulator

import fs_driver


def event_handler(e):
    code = e.get_code()
    obj = e.get_target()
    if code == lv.EVENT.VALUE_CHANGED:
        option = " "*10
        obj.get_selected_str(option, len(option))
        print("Selected value: %s\n" + option.strip())

#
# Roller with various alignments and larger text in the selected area
#

# A style to make the selected option larger
style_sel = lv.style_t()
style_sel.init()

try:
    style_sel.set_text_font(lv.font_montserrat_22)
except:
    fs_drv = lv.fs_drv_t()
    fs_driver.fs_register(fs_drv, 'S')
    print("montserrat-22 not enabled in lv_conf.h, dynamically loading the font")
    font_montserrat_22 = lv.font_load("S:" + "../../assets/font/montserrat-22.fnt")
    style_sel.set_text_font(font_montserrat_22)

opts = "\n".join(["1","2","3","4","5","6","7","8","9","10"])

# A roller on the left with left aligned text, and custom width
roller = lv.roller(lv.scr_act())
roller.set_options(opts, lv.roller.MODE.NORMAL)
roller.set_visible_row_count(2)
roller.set_width(100)
roller.add_style(style_sel, lv.PART.SELECTED)
roller.set_style_text_align(lv.TEXT_ALIGN.LEFT, 0)
roller.align(lv.ALIGN.LEFT_MID, 10, 0)
roller.add_event_cb(event_handler, lv.EVENT.ALL, None)
roller.set_selected(2, lv.ANIM.OFF)

# A roller in the middle with center aligned text, and auto (default) width
roller = lv.roller(lv.scr_act())
roller.set_options(opts, lv.roller.MODE.NORMAL)
roller.set_visible_row_count(3)
roller.add_style(style_sel, lv.PART.SELECTED)
roller.align(lv.ALIGN.CENTER, 0, 0)
roller.add_event_cb(event_handler, lv.EVENT.ALL, None)
roller.set_selected(5, lv.ANIM.OFF)

# A roller on the right with right aligned text, and custom width
roller = lv.roller(lv.scr_act())
roller.set_options(opts, lv.roller.MODE.NORMAL)
roller.set_visible_row_count(4)
roller.set_width(80)
roller.add_style(style_sel, lv.PART.SELECTED)
roller.set_style_text_align(lv.TEXT_ALIGN.RIGHT, 0)
roller.align(lv.ALIGN.RIGHT_MID, -10, 0)
roller.add_event_cb(event_handler, lv.EVENT.ALL, None)
roller.set_selected(8, lv.ANIM.OFF)

---

add fade mask to roller

C code  

 GitHub

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

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);
        lv_coord_t line_space = lv_obj_get_style_text_line_space(obj, LV_PART_MAIN);
        lv_coord_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_mem_buf_get(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_mem_buf_get(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_mem_buf_release(fade_mask_top);
        lv_mem_buf_release(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_scr_act(), &style, 0);

    lv_obj_t * roller1 = lv_roller_create(lv_scr_act());
    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

MicroPython code  

 GitHub Simulator

import fs_driver
import sys

class Lv_Roller_3():

    def __init__(self):
        self.mask_top_id = -1
        self.mask_bottom_id = -1

        #
        # Add a fade mask to roller.
        #
        style = lv.style_t()
        style.init()
        style.set_bg_color(lv.color_black())
        style.set_text_color(lv.color_white())

        lv.scr_act().add_style(style, 0)

        roller1 = lv.roller(lv.scr_act())
        roller1.add_style(style, 0)
        roller1.set_style_border_width(0, 0)
        roller1.set_style_pad_all(0, 0)
        roller1.set_style_bg_opa(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
        try:
            roller1.set_style_text_font(lv.font_montserrat_22,lv.PART.SELECTED)
        except:
            fs_drv = lv.fs_drv_t()
            fs_driver.fs_register(fs_drv, 'S')
            print("montserrat-22 not enabled in lv_conf.h, dynamically loading the font")
            font_montserrat_22 = lv.font_load("S:" + "../../assets/font/montserrat-22.fnt")
            roller1.set_style_text_font(font_montserrat_22,lv.PART.SELECTED)

        roller1.set_options("\n".join([
            "January",
            "February",
            "March",
            "April",
            "May",
            "June",
            "July",
            "August",
            "September",
            "October",
            "November",
            "December"]),lv.roller.MODE.NORMAL)

        roller1.center()
        roller1.set_visible_row_count(3)
        roller1.add_event_cb(self.mask_event_cb, lv.EVENT.ALL, None)

    def mask_event_cb(self,e):

        code = e.get_code()
        obj = e.get_target()

        if code == lv.EVENT.COVER_CHECK:
            e.set_cover_res(lv.COVER_RES.MASKED)

        elif code == lv.EVENT.DRAW_MAIN_BEGIN:
            # add mask
            font = obj.get_style_text_font(lv.PART.MAIN)
            line_space = obj.get_style_text_line_space(lv.PART.MAIN)
            font_h = font.get_line_height()

            roller_coords = lv.area_t()
            obj.get_coords(roller_coords)

            rect_area = lv.area_t()
            rect_area.x1 = roller_coords.x1
            rect_area.x2 = roller_coords.x2
            rect_area.y1 = roller_coords.y1
            rect_area.y2 = roller_coords.y1 + (obj.get_height() - font_h - line_space) // 2

            fade_mask_top = lv.draw_mask_fade_param_t()
            fade_mask_top.init(rect_area, lv.OPA.TRANSP, rect_area.y1, lv.OPA.COVER, rect_area.y2)
            self.mask_top_id = lv.draw_mask_add(fade_mask_top,None)

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

            fade_mask_bottom = lv.draw_mask_fade_param_t()
            fade_mask_bottom.init(rect_area, lv.OPA.COVER, rect_area.y1, lv.OPA.TRANSP, rect_area.y2)
            self.mask_bottom_id = lv.draw_mask_add(fade_mask_bottom, None)

        elif code == lv.EVENT.DRAW_POST_END:
            fade_mask_top = lv.draw_mask_remove_id(self.mask_top_id)
            fade_mask_bottom = lv.draw_mask_remove_id(self.mask_bottom_id)
            # Remove the masks
            lv.draw_mask_remove_id(self.mask_top_id)
            lv.draw_mask_remove_id(self.mask_bottom_id)
            self.mask_top_id = -1
            self.mask_bottom_id = -1

roller3 = Lv_Roller_3()

---

API

Typedefs

typedef uint8_t lv_roller_mode_t

Enums

Roller mode.

Values:

enumerator LV_ROLLER_MODE_NORMAL

Normal mode (roller ends at the end of the options).

enumerator LV_ROLLER_MODE_INFINITE

Infinite mode (roller can be scrolled forever).

Functions

lv_obj_t *lv_roller_create(lv_obj_t *parent)

Create a roller object

Parameters

parent -- pointer to an object, it will be the parent of the new roller.

Returns

pointer to the created roller

void lv_roller_set_options(lv_obj_t *obj, const char *options, lv_roller_mode_t mode)

Set the options on a roller

Parameters

• obj -- pointer to roller object

• options --

  a string with '

  ' separated options. E.g. "One\nTwo\nThree"

• mode -- LV_ROLLER_MODE_NORMAL or LV_ROLLER_MODE_INFINITE

void lv_roller_set_selected(lv_obj_t *obj, uint16_t sel_opt, lv_anim_enable_t anim)

Set the selected option

Parameters

• obj -- pointer to a roller object

• sel_opt -- index of the selected option (0 ... number of option - 1);

• anim_en -- LV_ANIM_ON: set with animation; LV_ANOM_OFF set immediately

void lv_roller_set_visible_row_count(lv_obj_t *obj, uint8_t row_cnt)

Set the height to show the given number of rows (options)

Parameters

• obj -- pointer to a roller object

• row_cnt -- number of desired visible rows

uint16_t lv_roller_get_selected(const lv_obj_t *obj)

Get the index of the selected option

Parameters

obj -- pointer to a roller object

Returns

index of the selected option (0 ... number of option - 1);

void lv_roller_get_selected_str(const lv_obj_t *obj, char *buf, uint32_t buf_size)

Get the current selected option as a string.

Parameters

• obj -- pointer to ddlist object

• buf -- pointer to an array to store the string

• buf_size -- size of buf in bytes. 0: to ignore it.

const char *lv_roller_get_options(const lv_obj_t *obj)

Get the options of a roller

Parameters

obj -- pointer to roller object

Returns

the options separated by '

'-s (E.g. "Option1\nOption2\nOption3")

uint16_t lv_roller_get_option_cnt(const lv_obj_t *obj)

Get the total number of options

Parameters

obj -- pointer to a roller object

Returns

the total number of options

Variables

const lv_obj_class_t lv_roller_class

struct lv_roller_t

Public Members

lv_obj_t obj

uint16_t option_cnt

Number of options

uint16_t sel_opt_id

Index of the current option

uint16_t sel_opt_id_ori

Store the original index on focus

lv_roller_mode_t mode

uint32_t moved