🔢 Spinbox

The Spinbox widget is a numerical input field equipped with increment and decrement buttons. It is the ideal choice for settings that require precise step-by-step adjustments, such as setting a target temperature, adjusting a timer, or selecting a quantity.

---

⚙️ Properties (Props)

The Spinbox configuration is defined by the SpinboxWidget interface. It manages a numeric value within a strictly defined range.

Property	Type	Description
Value	number	The current integer or decimal value.
Range	number	The Min and Max allowed values.
Step	number	The amount added or subtracted with each button click.
Digit Count	number	The total number of digits displayed (including padding).
Rollover	boolean	If true, incrementing past Max returns to Min.

---

🛠 Interaction Logic

The Spinbox provides three ways to interact:

1. Plus/Minus Buttons: Clicking the side buttons changes the value by the defined step.
2. Long Press: Holding a button down will rapidly cycle through values, with the speed increasing the longer it is held.
3. Direct Entry: Clicking the central number area can trigger a Keyboard for manual numerical entry.

---

🎨 Layout and Styling

In the Inspector Panel, you can customize the appearance of the component parts:

• Main: Styles the background and border of the entire widget.
• Buttons: Adjust the color, size, and icons (usually + and -) for the control elements.
• Cursor: If direct editing is enabled, you can style the text cursor color and thickness.

---

⚡ Runtime API (Lua)

Spinboxes are essential for parameter tuning in the Logic and Events system.

-- Get the current value
local target_temp = spb_ac_control:get_value()

-- Update the value based on an external event
spb_ac_control:set_value(22)

-- Change the step size dynamically
-- (e.g., hold a 'Shift' button to increase by 10 instead of 1)
if btn_shift:is_pressed() then
    spb_ac_control:set_step(10)
else
    spb_ac_control:set_step(1)
end

-- React to value changes
function on_value_changed(new_val)
    system:update_setpoint(new_val)
end

---

PRECISION TIP

For decimal values (e.g., 22.5), use a large integer range (e.g., 0 to 1000) and use Lua to format the display text with a decimal point. This avoids floating-point rounding errors on low-power hardware.

---

🚀 Next Steps

• Slider — For faster, less precise value adjustments.
• Keyboard — Learn how to set up the numeric pad for direct Spinbox entry.
• Logic and Events — Synchronize your Spinbox with hardware sensors.