Module spin_box 

SpinBox — numeric input with increment/decrement buttons.

A generic composite over SpinValue (integer and floating-point primitives), pairing the TextInputField editing primitive with a stacked pair of up/down step buttons. Semantics are a synthesis of Qt’s QSpinBox / QDoubleSpinBox, WinUI 3’s NumberBox, GTK’s GtkSpinButton, and the W3C ARIA spinbutton role.

Behaviour

• Value binding: a Signal<T> is the single source of truth. Typing and stepping update it; external writes re-format the editable text.
• Commit model: the user can type freely (subject to the per-character input filter). The value is committed on Enter or on focus loss — at commit time the text is parsed, clamped into [min, max] (or wrapped, per WrapMode), and reformatted. Invalid input reverts to the last known good value.
• Keyboard:
  • Up / Down → ±single_step
  • PageUp / PageDown → ±page_step (default: 10 × single_step)
  • Enter → commit (stays focused)
  • Home / End stay bound to the text cursor (Qt-compatible).
• Mouse wheel: adjusts by single_step — wheel down decreases, wheel up increases, matching QAbstractSpinBox, GtkSpinButton and WinUI’s NumberBox. Gated by wheel_mode (default: only when focused, to avoid accidental scroll changes).
• Buttons: up/down buttons stack to the right of the field by default; can be hidden with button_layout.
• Special value text: when the current value equals min and special_value_text is set, the field shows that string instead of the formatted number — Qt’s “Auto” / “None” / “Unlimited” affordance.
• Adaptive step: with StepType::Adaptive, the effective step tracks the decimal magnitude of the current value (Qt’s AdaptiveDecimalStepType). Useful for values that span many orders of magnitude in the same control.
• Locale: the number follows the active locale’s decimal separator, digits and minus sign (localized, on by default); thousands separators are opt-in (use_grouping, off by default, as in Qt). Display, commit parse and the per-character input filter all resolve from one NumberPresentation, so they cannot disagree about which separator the field is using — a French user sees 12,5, types 12,5, and the numeric keypad’s . still works. Rendering is a string transform over the value’s own Display, never an f64 round-trip, so a SpinBox<i64> stays exact past 2^53. Turn it off for a number that is an identifier rather than a quantity (port, version component, database id). With no I18nManager installed the active locale is the C locale and this is a no-op.
• Custom formatter / parser: full override via text_from_value and value_from_text; together they let you implement currency, percentages with stored fraction, hex, duration, anything. A custom formatter/parser owns the whole convention — it is not re-punctuated by the locale layer.

Accessibility

The composite exposes itself as Role::SpinButton with numeric value, min, max, step, and jump properties set on the AccessKit node; the AT receives Increment, Decrement, SetValue, and Focus actions. The step buttons are structurally part of the SpinBox and publish no separate a11y nodes.

Example

use teksilo::widgets::{SpinBox, WrapMode};

let font_size = ctx.signal(12_i32);
ctx.add(
    SpinBox::new(font_size, 4, 72)
        .single_step(1)
        .page_step(10)
        .suffix(" pt"),
);

let gain_db = ctx.signal(0.0_f32);
ctx.add(
    SpinBox::new(gain_db, -60.0, 12.0)
        .single_step(0.5)
        .decimals(1)
        .suffix(" dB")
        .wrap_mode(WrapMode::Clamp),
);

Structs

SpinBox

Numeric input with step buttons. Generic over SpinValue — pre-implemented for i32, i64, u32, u64, usize, f32, and f64.

Enums

ButtonLayout

Step-button visibility / placement. Moved up from teksilo_widgets::spin_box::ButtonLayout so the trait config can carry it without forcing the recipe to depend on the widget crate.

StepType

Step-size policy for each key/button press.

WheelMode

When the mouse wheel is allowed to adjust the value.

WidthPolicy

How the SpinBox decides its horizontal size envelope.

WrapMode

Out-of-range behavior when stepping past min or max.

Traits

SpinValue

Numeric primitive that a SpinBox can hold.