🎡 Roller
The Roller widget is a scrolling selection tool inspired by classic slot machines and modern mobile date pickers. It allows users to browse a list of options by swiping vertically, making it highly tactile and efficient for touchscreens where a standard Dropdown might be too small to interact with.
⚙️ Properties (Props)
The Roller configuration is defined by the RollerWidget interface. It handles a vertical stack of labels and manages the momentum of the scroll.
| Property | Type | Description |
|---|---|---|
| Options | string[] | An array of labels that will appear in the scrolling list. |
| Selected | number | The index of the item currently in the center/active position. |
| Visible Row Count | number | The number of items shown at once (e.g., 3 or 5). |
| Mode | Dropdown | Normal: Stops at the ends. Infinite: Loops back to the start. |
🛠 Scrolling Behavior
The Roller provides a unique interaction model:
- Snapping: The widget automatically "snaps" to the nearest item when the user stops scrolling, ensuring an option is always perfectly centered.
- Infinite Mode: In this mode, the list wraps around (e.g., scrolling past "December" takes you back to "January"), which is ideal for time and date settings.
- Momentum: The engine calculates the speed of the user's swipe to allow for "flicking" through long lists quickly.
🎨 Visual Styling
In the Inspector Panel, you can customize how the list and selection area appear:
- Main: Styles the background and the overall container dimensions.
- Selected Area: Specifically styles the center row (e.g., adding a border or a different text color) to indicate the active choice.
- Text Fade: (Advanced) You can adjust the opacity or scale of the items further away from the center to create a 3D "cylindrical" effect.
⚡ Runtime API (Lua)
The Roller is commonly used for setting parameters or navigating menus via the Logic and Events system.
-- Get the text of the currently snapped option
local index = roll_minutes:get_selected()
local val = roll_minutes:get_selected_str()
-- Programmatically scroll to a specific option with animation
roll_hours:set_selected(12, true) -- index, animate
-- Update the list of options (e.g., updating days based on month)
local days = {"1", "2", "3", "...", "31"}
roll_day:set_options(days)
The Roller is the best choice for selecting numbers or dates on a small screen where a Keyboard would take up too much space. Use an Odd Number for Visible Row Count (e.g., 3 or 5) to ensure there is always a clear center item.
🚀 Next Steps
- Dropdown — A compact alternative that only shows the list when clicked.
- Calendar — Use for full-month date selection.
- Logic and Events — Learn how to synchronize multiple rollers for time-setting (HH:MM:SS).