> 本类共性:多个控件会**同时**发“过程信号”和“提交信号”;静态 `DrawBox` 与数据视图共用,改外观会同时影响列表/表格/树的勾选行。
## 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(...); // 可复用的勾选框绘制(数据视图也用)
```
- **`版本`**:早期加入(`1d886f5`,v1.6.0 之前)。
## 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 可否决
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
**易错**
- 单独一个 `RadioButton` 不做互斥;互斥由 `RadioGroup` 保证。
###block_red_end
- **`版本`**:`v1.11.0`。
## ToggleSwitch
```cpp
ZSignal<bool> Toggled; void SetOn(bool); bool IsOn() const;
void SetIndeterminate(bool); // 半选外观
inline static float DefaultAnimationDuration; // 一次完整动画时长(秒),默认 0.18
```
- 默认 50×24。
- 点击在**松开时**切换;按住左右拖动时 knob 跟随鼠标,松开按拖动进度 >= 0.5 决定开/关。拖动期间轨道颜色同步变化。
- **`版本`**:`v1.21.0` 起滑块/底色/悬停改为**时长驱动 ease-in-out**;`v1.26.0` 支持 WinUI3 风格按住拖动,默认时长调为 0.18s。`SetAnimationSpeed` 仍保留"越大越快"(换算成时长倍率)。
## 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; // 动画中的显示值(刻度位置),用于调试/测试
```
###block_red_start
**易错**
- `ValueChanged` 在拖动中**连续**触发;提交用 `SliderReleased`。
- 普通拖动**不做显示缓动**(跟手);点击轨道和开启 `SetSnapToStep` 时才缓动到目标/吸附点。
###block_red_end
- **`版本`**:`v1.18.0` 修 0 宽时 0/0→NaN 静默把值设成 min/max;`v1.26.0` 区分拖动/点击/吸附缓动并新增 `GetDisplayValue()`。
## NumberBox(+ 内部 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
**易错**
- **空文本按“错误”处理**是控件行为(不是调用方责任);步进按钮会先 `CommitText()`,所以未失焦的编辑值不会丢。
###block_red_end
- **`版本`**:`v1.12.0`;`ResetToDefault` 清错误 `v1.12.2`。选择与输入
CheckBox、RadioButton、RadioGroup、ToggleSwitch、Slider、NumberBox
本类共性:多个控件会同时发“过程信号”和“提交信号”;静态
DrawBox与数据视图共用,改外观会同时影响列表/表格/树的勾选行。
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(...); // 可复用的勾选框绘制(数据视图也用)
版本:早期加入(1d886f5,v1.6.0 之前)。
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 可否决
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); ... };
易错
- 单独一个
RadioButton不做互斥;互斥由RadioGroup保证。
版本:v1.11.0。
ToggleSwitch
cpp
ZSignal<bool> Toggled; void SetOn(bool); bool IsOn() const;
void SetIndeterminate(bool); // 半选外观
inline static float DefaultAnimationDuration; // 一次完整动画时长(秒),默认 0.18
- 默认 50×24。
- 点击在松开时切换;按住左右拖动时 knob 跟随鼠标,松开按拖动进度 >= 0.5 决定开/关。拖动期间轨道颜色同步变化。
版本:v1.21.0起滑块/底色/悬停改为时长驱动 ease-in-out;v1.26.0支持 WinUI3 风格按住拖动,默认时长调为 0.18s。SetAnimationSpeed仍保留"越大越快"(换算成时长倍率)。
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; // 动画中的显示值(刻度位置),用于调试/测试
易错
ValueChanged在拖动中连续触发;提交用SliderReleased。- 普通拖动不做显示缓动(跟手);点击轨道和开启
SetSnapToStep时才缓动到目标/吸附点。
版本:v1.18.0修 0 宽时 0/0→NaN 静默把值设成 min/max;v1.26.0区分拖动/点击/吸附缓动并新增GetDisplayValue()。
NumberBox(+ 内部 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();
易错
- 空文本按“错误”处理是控件行为(不是调用方责任);步进按钮会先
CommitText(),所以未失焦的编辑值不会丢。
版本:v1.12.0;ResetToDefault清错误v1.12.2。