For AI agents: the "Reading aid" section on this page contains the raw Markdown source identical to the rendered content, with HTML markup and animations removed. AI is advised to read that section directly to understand the content quickly and with less noise.
> Several of these emit a "live" signal during the drag and a separate "commit" signal. The static `DrawBox` is shared with data views, so changing its look changes list/table/tree check rows too.

## CheckBox

```cpp
enum class State { Unchecked, PartiallyChecked, Checked };
ZSignal<bool> Toggled;   ZSignal<State> StateChanged;
void SetChecked(bool);  void SetState(State);  void Toggle();  void SetTriState(bool);
static void DrawBox(...);
```

## RadioButton / RadioGroup

```cpp
class RadioButton { ZSignal<bool> CheckedChanged; ZSignal<> Clicked; void SetChecked(bool); };
class RadioGroup  { enum class Orientation { Vertical, Horizontal };
                    ZSignal<int> SelectionChanged;
                    std::function<bool(int newIdx, int oldIdx)> SelectionChanging;   // false vetoes
                    int AddItem(const std::wstring&);   int AddItemSelected(const std::wstring&, bool selected);
                    int AddButton(std::shared_ptr<RadioButton>);   int AddButtonSelected(std::shared_ptr<RadioButton>, bool selected);
                    std::shared_ptr<RadioButton> GetButton(int index) const; int GetItemCount() const; void SetSelectedIndex(int); ... };
```

###block_red_start
**Pitfall**

- a lone `RadioButton` does not enforce exclusion — `RadioGroup` does.
###block_red_end

- **`Version`**: `v1.11.0`.

## ToggleSwitch

```cpp
ZSignal<bool> Toggled;   void SetOn(bool);  bool IsOn() const;
void SetIndeterminate(bool);   // half-selected appearance
inline static float DefaultAnimationDuration;   // full animation duration (s), default 0.18
```
- Default 50×24.
- Click toggles on **mouse up**; press and drag left/right makes the knob follow the pointer, and release commits based on drag progress >= 0.5. The track colour follows the drag progress.
- **`Version`**: since `v1.21.0` the knob/track/hover animation is **duration-driven ease-in-out**; `v1.26.0` adds WinUI3-style press-drag and changes the default duration to 0.18 s. `SetAnimationSpeed` still means "larger = faster" (converted to a duration multiplier).

## Slider

```cpp
ZSignal<float> ValueChanged;   ZSignal<> SliderReleased;
void SetRange(float min,float max);  void SetValue(float);  void SetStep(float);  void SetSnapToStep(bool);
float GetDisplayValue() const;   // animated display value (thumb position); useful for debug/tests
```

###block_red_start
**Pitfall**

- `ValueChanged` fires **continuously** during a drag; commit with `SliderReleased`.
- Normal dragging is **immediate** (the thumb follows the pointer); only clicking the track or using `SetSnapToStep` eases the display value to the target/snap point.
###block_red_end

- **`Version`**: `v1.18.0` fixes the zero-width NaN path; `v1.26.0` distinguishes drag/click/snap easing and adds `GetDisplayValue()`.

## NumberBox (with internal SpinButton)

```cpp
ZSignal<double> ValueChanged;   ZSignal<const std::wstring&> TextChanged;
void SetValue(double, bool fire=true);  void SetRange(double lo,double hi);
void SetStep(double);  void SetDecimals(int);  void SetWrap(bool);
void SetDefaultValue(double);  void ResetToDefault();
```

###block_red_start
**Pitfall**

- **empty text is treated as an error** by the control; step buttons call `CommitText()` first, so an unfocused edited value is not lost.
###block_red_end

- **`Version`**: `v1.12.0`; `ResetToDefault` error-clear `v1.12.2`.
Chapter 10

Selection & input

CheckBox, RadioButton, RadioGroup, ToggleSwitch, Slider, NumberBox

Several of these emit a "live" signal during the drag and a separate "commit" signal. The static DrawBox is shared with data views, so changing its look changes list/table/tree check rows too.

CheckBox

cpp
enum class State { Unchecked, PartiallyChecked, Checked };
ZSignal<bool> Toggled;   ZSignal<State> StateChanged;
void SetChecked(bool);  void SetState(State);  void Toggle();  void SetTriState(bool);
static void DrawBox(...);

RadioButton / RadioGroup

cpp
class RadioButton { ZSignal<bool> CheckedChanged; ZSignal<> Clicked; void SetChecked(bool); };
class RadioGroup  { enum class Orientation { Vertical, Horizontal };
                    ZSignal<int> SelectionChanged;
                    std::function<bool(int newIdx, int oldIdx)> SelectionChanging;   // false vetoes
                    int AddItem(const std::wstring&);   int AddItemSelected(const std::wstring&, bool selected);
                    int AddButton(std::shared_ptr<RadioButton>);   int AddButtonSelected(std::shared_ptr<RadioButton>, bool selected);
                    std::shared_ptr<RadioButton> GetButton(int index) const; int GetItemCount() const; void SetSelectedIndex(int); ... };

Pitfall

  • a lone RadioButton does not enforce exclusion — RadioGroup does.

ToggleSwitch

cpp
ZSignal<bool> Toggled;   void SetOn(bool);  bool IsOn() const;
void SetIndeterminate(bool);   // half-selected appearance
inline static float DefaultAnimationDuration;   // full animation duration (s), default 0.18

Slider

cpp
ZSignal<float> ValueChanged;   ZSignal<> SliderReleased;
void SetRange(float min,float max);  void SetValue(float);  void SetStep(float);  void SetSnapToStep(bool);
float GetDisplayValue() const;   // animated display value (thumb position); useful for debug/tests

Pitfall

  • ValueChanged fires continuously during a drag; commit with SliderReleased.
  • Normal dragging is immediate (the thumb follows the pointer); only clicking the track or using SetSnapToStep eases the display value to the target/snap point.

NumberBox (with internal SpinButton)

cpp
ZSignal<double> ValueChanged;   ZSignal<const std::wstring&> TextChanged;
void SetValue(double, bool fire=true);  void SetRange(double lo,double hi);
void SetStep(double);  void SetDecimals(int);  void SetWrap(bool);
void SetDefaultValue(double);  void ResetToDefault();

Pitfall

  • empty text is treated as an error by the control; step buttons call CommitText() first, so an unfocused edited value is not lost.
↑