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 in anim_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 option

  • LV_KEY_LEFT/UP Select the previous option

  • LY_KEY_ENTER Apply the selected option (Send LV_EVENT_VALUE_CHANGED event)

Example

API

Typedefs

typedef uint8_t lv_roller_mode_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).

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