本类共性:多个控件会同时发“过程信号”和“提交信号”;静态
DrawBox与数据视图共用,改外观会同时影响列表/表格/树的勾选行。
CheckBox
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
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
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
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)
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。