Roller (lv_roller)

Pick an item from a vertical list by scrolling. The item in the middle is the selected one and is usually styled to stand out.

Overview

A Roller lets the user pick an item from a vertical list by scrolling through it. The item in the middle is the selected one and is usually styled to stand out from the others.

Setting the list items

lv_roller_set_options(roller, "First\nSecond\nThird", LV_ROLLER_MODE_NORMAL)

sets the items; \n separates them. Use LV_ROLLER_MODE_INFINITE for a circular roller.

Select programmatically with lv_roller_set_selected(roller, id, LV_ANIM_ON) (index) or _set_selected_str(roller, str, LV_ANIM_ON) (option text).

Set translation tag

When using LVGL's translation module, you can bind a translation tag to the roller's options with lv_roller_set_options_translation_tag(roller, tag, mode). After binding, future changes to the language will automatically update the options to display the corresponding translation for that tag in the new language. The translation should contain the options in a \n separated list, e.g. "One\nTwo\nThree".

Calling lv_roller_set_options afterwards removes the binding.

Get selected option

• lv_roller_get_selected(roller) returns the index.
• lv_roller_get_selected_str(roller, buf, size) copies the option text into buf.

Visible rows

lv_roller_set_visible_row_count(roller, n) sets how many list rows are visible. The pixel height is derived from the current font and spacing — call this again after any change to those styles.

Styling

• LV_PART_MAIN The background of the roller uses the typical background and text style properties.

  • Style text_line_space adjusts the space between list items. Use lv_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_time milliseconds as specified in the anim_duration style. Use lv_obj_set_style_anim_duration to set this value.

• LV_PART_SELECTED The 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.

Roller has two stylable parts: LV_PART_MAIN (the listbox background and unselected items) and LV_PART_SELECTED (the highlighted row in the middle). Attach a named <style> with selector="main" or selector="selected" to target a part, or set local style_* props on the <lv_roller> tag (those target MAIN).

text_line_space on MAIN is doing double duty: it sets the spacing between list rows and the height of the selected band, because the indicator always sits in the gap between two items. Increase text_line_space when you want a chunkier highlighted row without computing a separate selected-area height.

Data binding

Data bindings connect a widget property to a piece of global data — a Subject. When the subject's value changes, every widget bound to it updates automatically; and an interactive widget can write back into the subject so other subscribers see the new value.

A Roller binds its selected index to a Subject. The link is two-way: scrolling to a new option updates the subject, and an application-side write into the subject snaps the roller to that index. Only integer subjects are supported.

• lv_roller_bind_value(roller, subject)

To show the value live in a label next to the widget, attach a label and call lv_label_bind_text(label, subject, "%d") — the format string accepts any printf-style specifier (XML: bind_text + bind_text-fmt).

Fade mask via draw events

XML can style the parts but can't paint a soft gradient over them. To fade the top and bottom edges of the roller, attach an LV_EVENT_DRAW_TASK_ADDED handler and blit a pre-rendered alpha mask onto the layer the roller is being drawn into:

Events

LV_EVENT_VALUE_CHANGED is sent sent when a new list item is selected.

Learn more about Events emitted by all Widgets.

Keys

• LV_KEY_RIGHT/DOWN Select next option
• LV_KEY_LEFT/UP Select previous option
• LV_KEY_ENTER Accept the selected option (sends LV_EVENT_VALUE_CHANGED event)

Learn more about Keys.