Rollers, codes and spin boxes
A scrolling wheel of labels, a row of one character cells for codes, and a number edited one digit at a time.


In the galleryRollerrollerInput OTPinput_otpSpinboxspinbox
All three live in isolenui/kit/pickers.h, come in through isolenui/kit/kit.h, and need no kit.conf line. See the component kit.
roller
roller(u, label, items, count, &index, spec) shows a column of labels with the chosen one in a band in the middle. roller_fn is the same but asks a roller_text for each label, and only for the rows in view. The function gets the index, a 64 byte buffer and your user, and returns the text, either the buffer or a string of its own.
Dragging moves the wheel under the pointer and a release throws it on with its speed, then it settles on the nearest row. A tap without a drag goes to the row tapped. The wheel, Up and Down move one row, Page Up and Page Down move a page of rows, Home and End go to the first and last. The roller keeps the wheel so no view behind it scrolls. A trackpad, or any wheel delta under one row, moves the roller by distance instead of stepping a row per event.
- Trackpad. The wheel follows the fingers one to one, a logical pixel per point. When the platform reports the gesture phase, as macOS and Windows Direct Manipulation do, the roller adds no glide of its own: it tracks the fingers and then the system momentum, and snaps once both are done. With no phase to read it falls back to a short glide of its own. An event within about twice the recent gap, and never less than 50 ms, carries on the same stroke.
- Snap. The snap is the iOS style spring: critically damped with a 0.2 second response, so it lands fast with no bounce and rests once it is within a quarter pixel. A release rests on the nearest row the spring can reach without speeding up, so a slow release may settle back onto the row behind it. A flick faster than about 1200 units a second instead lands where an iOS scroll view projects it, at a deceleration rate of 0.998, and speeds between the two blend.
- Ends. A roller that is not
infinitestretches past its first and last row like a rubber band, under a drag or the trackpad. Each row past the end costs more, and the stretch never reaches half the rows in view. While trackpad events keep coming the stretch is pulled back a little on each one, so a harder push stretches further. Past an end it waits at the fingers for the next event rather than coasting. - Spring back. On release, or once the trackpad stops, it springs back at once on the same fast spring as the snap, solved exactly so it moves the same at any frame rate. A wheel notch against an end throws the wheel a little past it and the spring brings it back.
index is written when the roll is decided, on release, a key or a wheel step, and on every trackpad event, where it is the row nearest the wheel. The settle animation runs after it. It returns true on the frame the index changes. An index past the end is clamped to the last row, and that counts as a change. Setting index from outside rolls the wheel to it.
roller_spec field | Default | Meaning |
|---|---|---|
rows | 5 | The rows showing. Always odd, an even count gets one more, and 15 at most. Zero means 5. |
infinite | false | Loops from the last row to the first. Only with more than one item. |
row_h | 0 | The row height. Zero or less takes the theme's row_h. |
input_otp
input_otp(u, label, code, capacity, spec, &changed) edits a code in a row of cells, one code point per cell. It runs the text edit core over the whole code with the focused cell selected, so typing replaces that cell and moves on, Backspace deletes back through the cells, and the platform IME is asked for the caret. A paste fills from the first cell whichever cell has focus.
The return value and the out parameter answer different questions. input_otp returns true once, on the frame an edit leaves every cell filled, so it is the moment to submit the code. It stays false while the code sits full with no edit, so check the length of the code if you need to know it is complete later. changed is set true on every frame the code was edited. It may be null.
otp_spec field | Default | Meaning |
|---|---|---|
cells | 6 | How many cells, 16 at most. Zero means 6. |
group | 3 | A wider gap after every this many cells. Zero means no groups. |
numeric | true | Takes digits only. Off takes any code point above a space. |
mask | false | Draws a dot for each filled cell instead of the character. |
One cell is in the tab order, the first empty one, or the last when the code is full. A press never focuses past it. Left, Right, Home and End move between the cells up to that one. capacity is the buffer size with its terminator, so six ASCII digits need 7 bytes.
spinbox
spinbox(u, label, &value, lo, hi, spec) shows an integer as a fixed row of digits between a minus and a plus button, with one digit lit as the cursor. The buttons, the arrows and the wheel step at the cursor's place, so the tens digit steps by ten. It returns true on the frame the value changes.
| Input | Does |
|---|---|
| Left, Right | Moves the cursor one place. |
| Up, Down, wheel, the buttons | Adds or takes one at the cursor's place. |
| Page Up, Page Down | Ten at the cursor's place. |
| Home, End | lo and hi. |
| Digits | Overwrite the digit at the cursor and move right. |
- | Flips the sign, when lo is below zero. |
| Press | Focuses it and puts the cursor on the digit pressed. |
spinbox_spec field | Default | Meaning |
|---|---|---|
digits | 5 | How many digits show, 10 at most. Zero means 5. |
decimals | 0 | Draws a point this many digits from the right. The value stays an integer, so 250 with 2 decimals reads 2.50. |
The value is clamped to lo and hi, and to what the digits can show. A value that comes in out of range is clamped on the first frame and reported as a change. A sign column shows only when lo is below zero.
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
#include <stdio.h>
struct device_setup {
uint32_t region = 0u;
uint32_t minute = 0u;
char code[8] = "";
int32_t gain = 250; // shown as 2.50 with two decimals
};
static const char* const regions[] = { "north", "south", "east", "west" };
// only the rows in view are asked for, the buffer holds 64 bytes
static const char* minute_text(uint32_t index, char* buf, uint32_t cap, void*)
{
snprintf(buf, cap, "%02u", index);
return buf;
}
static void setup_view(ui::ctx* u, device_setup* d)
{
// a wheel of labels, five rows showing
ui::roller(u, "region", regions, 4u, &d->region);
// labels made on demand, looping round
ui::roller_spec loop = ui::roller_defaults();
loop.infinite = true;
ui::roller_fn(u, "minute", 60u, minute_text, nullptr, &d->minute, &loop);
// six digit cells in groups of three
bool edited = false;
if (ui::input_otp(u, "code", d->code, sizeof(d->code), nullptr, &edited)) {
// an edit just filled the last cell, check the code once here
}
// a fixed point value edited digit by digit
ui::spinbox_spec fixed = ui::spinbox_defaults();
fixed.digits = 4u;
fixed.decimals = 2u;
ui::spinbox(u, "gain", &d->gain, 0, 1000, &fixed);
}