面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
> 本类共性:多个控件会**同时**发“过程信号”和“提交信号”;静态 `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`。
第 10 章

选择与输入

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(...);   // 可复用的勾选框绘制(数据视图也用)

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 保证。

ToggleSwitch

cpp
ZSignal<bool> Toggled;   void SetOn(bool);  bool IsOn() const;
void SetIndeterminate(bool);   // 半选外观
inline static float DefaultAnimationDuration;   // 一次完整动画时长(秒),默认 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;   // 动画中的显示值(刻度位置),用于调试/测试

易错

  • ValueChanged 在拖动中连续触发;提交用 SliderReleased。
  • 普通拖动不做显示缓动(跟手);点击轨道和开启 SetSnapToStep 时才缓动到目标/吸附点。

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(),所以未失焦的编辑值不会丢。
↑