Roller (lv_roller) — LVGL documentation (2024)

Docs »
Widgets »
Roller (lv_roller)
Edit on GitHub

Overview¶

Roller allows you to simply select one option from more with scrolling.

Parts and Styles¶

The Roller's main part is called LV_ROLLER_PART_BG. It's a rectangle and uses all the typical background properties.The style of the Roller's label is inherited from the text style properties of the background.To adjust the space between the options use the text_line_space style property.The padding style properties set the space on the sides.

The selected option in the middle can be referenced with LV_ROLLER_PART_SELECTED virtual part. Besides the typical background properties it uses the text properties to change the appearance of the text in the selected area.

Usage¶

Set options¶

The 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 make 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¶

The get the currently selected option use lv_roller_get_selected(roller) it will return the index of the selected option.

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

Align the options¶

To align the label horizontally use lv_roller_set_align(roller, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT).

Visible rows¶

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

Animation time¶

When the Roller is scrolled and doesn't stop exactly on an option it will scroll to the nearest valid option automatically.The time of this scroll animation can be changed by lv_roller_set_anim_time(roller, anim_time). Zero animation time means no animation.

Events¶

Besides, the Generic events the following Special events are sent by the Drop down lists:

Keys¶

The following Keys are processed by the Buttons:

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)

Example¶

C¶

Simple Roller¶

code

#include "../../../lv_examples.h"#include <stdio.h>#if LV_USE_ROLLERstatic void event_handler(lv_obj_t * obj, lv_event_t event){ if(event == LV_EVENT_VALUE_CHANGED) { char buf[32]; lv_roller_get_selected_str(obj, buf, sizeof(buf)); printf("Selected month: %s\n", buf); }}void lv_ex_roller_1(void){ lv_obj_t *roller1 = lv_roller_create(lv_scr_act(), NULL); 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_align(roller1, NULL, LV_ALIGN_CENTER, 0, 0); lv_obj_set_event_cb(roller1, event_handler);}#endif

MicroPython¶

No examples yet.

API¶

Typedefs

typedef uint8_t lv_roller_mode_t¶

typedef uint8_t lv_roller_part_t¶

Enums

enum [anonymous]¶

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

enum [anonymous]¶

Values: