Roller (lv_roller)
Overview
Roller allows the end user to select an item from a list by scrolling it.
Parts and Styles
LV_PART_MAINThe background of the Roller uses the background- and text-style properties.Style
text_line_spaceadjusts the space between list items. Uselv_obj_set_style_text_line_space()to set this value.When the Roller is scrolled and doesn't stop exactly on an item, it will automatically scroll to the nearest valid item in
anim_timemilliseconds as specified in theanim_durationstyle. Uselv_obj_set_style_anim_duration()to set this value.
LV_PART_SELECTEDThe selected item (displayed in the middle of the Roller). Besides the typical background properties, it uses text style properties to change the appearance of the text of the selected item.
Usage
Setting the list items
List items are passed to the Roller as a string with
lv_roller_set_options(roller, string_list, LV_ROLLER_MODE_NORMAL).
The items should be separated by \n. For example:
"First\nSecond\nThird".
LV_ROLLER_MODE_INFINITE makes the Roller circular.
You can select an option programmatically with lv_roller_set_selected(roller, id, LV_ANIM_ON), where id is the zero-based index of the list item to be selected.
If you don't know the index of an option can also select an item with lv_roller_set_selected_str(roller, str, LV_ANIM_ON), where str is the string equal to one of the list items.
Get selected option
To get the index of the currently selected item use lv_roller_get_selected(roller).
lv_roller_get_selected_str(roller, buf, buf_size) will copy the name of the selected item 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_CHANGEDSent when a new list item is selected.
Further Reading
Learn more about Base-Widget Events emitted by all Widgets.
Learn more about Events.
Keys
LV_KEY_RIGHT/DOWNSelect next optionLV_KEY_LEFT/UPSelect previous optionLY_KEY_ENTERAccept the selected option (sendsLV_EVENT_VALUE_CHANGEDevent)
Further Reading
Learn more about Keys.
Example
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