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 inanim_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.
Usage¶
Set options¶
Options are passed to the Roller as a string with lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL/INFINITE)
. 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/OFF)
, where id is the index of an option.
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
.
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.
Events¶
LV_EVENT_VALUE_CHANGED
Sent when a new option is selected.
See the events of the Base object too.
Learn more about Events.
Keys¶
LV_KEY_RIGHT/DOWN
Select the next optionLV_KEY_LEFT/UP
Select the previous optionLY_KEY_ENTER
Apply the selected option (SendLV_EVENT_VALUE_CHANGED
event)
Example¶
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
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
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
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
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
orLV_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.
Variables
-
const lv_obj_class_t lv_roller_class¶
-
struct lv_roller_t¶