mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-14 06:42:58 +08:00
71 lines
2.6 KiB
Markdown
71 lines
2.6 KiB
Markdown
```eval_rst
|
|
.. include:: /header.rst
|
|
:github_url: |github_link_base|/widgets/roller.md
|
|
```
|
|
# Roller (lv_roller)
|
|
|
|
## 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](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Drop down lists:
|
|
- **LV_EVENT_VALUE_CHANGED** sent when a new option is selected
|
|
|
|
Learn more about [Events](/overview/event).
|
|
|
|
## 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
|
|
|
|
```eval_rst
|
|
|
|
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_roller/index.rst
|
|
|
|
```
|
|
|
|
## API
|
|
|
|
```eval_rst
|
|
|
|
.. doxygenfile:: lv_roller.h
|
|
:project: lvgl
|
|
|
|
```
|