ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

从这里开始 · 支持全文搜索

框架概览

轻量到几 MB,快到原生合成。 纯头文件、零第三方依赖的 C++20 Windows 自绘 UI 框架,直接构建在 Direct2D 1.1 + DirectComposition 之上。 - 没有 Qt 的打包包袱,没有 Electron 的内存税。 几个头文件,include 即用;应用工程不链

易错点

> 这份文件把散落在代码注释、HANDOFF.md、TODO.md 里的“坑”集中到一处。接手/使用前先扫一遍。 > 优先级:易错 = 违反必踩;注意 = 契约/限制,违反易出问题;约定 = 库的取向;不要 = 明确不做。 --- 1. 链式构造 DSL(ZufyUIDsl.h) | | 状态 |

参考总览

> 本文档覆盖 ZufyUI 框架的全部公开 API,按“使用分类”组织(不是按代码/头文件顺序)。 > 配套阅读:[项目说明与构建](https://github.com/zhc9968/ZufyUI/blob/master/README.md)。 > 阅读方式:本文不是“签名清单”,而是按“它是

约定

颜色与标记 - 红色块:易错——真实踩坑、反直觉行为、会崩溃/UAF/竞争的用法,优先看。 - 橙色块:注意——线程、生命周期、绘制顺序等契约;不一定是错误,但违反后容易出问题。 - 绿色块:推荐——推荐写法、所有权模型、最佳实践。 - 普通项目符号表示普通语义、默认值或版本变化,不代表没有风险。

快速开始

最小程序 cpp include "ZufyUI.h" include "ZufyUIWidgets.h" using namespace ZufyUI; int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) { // Windows 子系

基础类型

Color cpp struct Color { float r, g, b, a; // 分量范围 [0,1],不是 0..255 Color(float r=0, float g=0, float b=0, float a=1.0f); static Color FromArgb(uint8t

事件与信号

何时用信号 - 控件对外通知(点击、选中、值变化)用内置 ZSignal。 - 自定义控件对外事件:自己声明 ZSignal 成员并 Fire。 ConnectionThread cpp enum class ConnectionThread { CurrentThread, NewThread,

语言

API 参考 / v1.29.1

选择与输入

CheckBox、RadioButton、RadioGroup、ToggleSwitch、Slider、NumberBox

下载 Markdown

本类共性:多个控件会同时发“过程信号”和“提交信号”;静态 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。
查看源文件docs/src/API.md