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

DSL

链式构造(ZufyUIDsl.h,v1.19.4;v1.20.0 扩充)

下载 Markdown

这一章先给可直接照抄的写法,再给 API 摘要。ZufyUIDsl.h 是可选层,不改变底层控件树;遇到不确定的名字时,以本头文件和本章为准,不要凭 Qt 习惯猜。

最小可运行示例

#include "ZufyUI.h"
#include "ZufyUIWidgets.h"
#include "ZufyUIDsl.h"

using namespace ZufyUI;
using namespace ZufyUI::dsl;

int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) {
    auto nameBox = ZTxt().placeholder(L"在这里输入...");
    auto greeting = ZLbl(L"你好,等待输入...");
    auto greetBtn = ZBtn(L"打招呼");

    auto root = ZCol(
        ZRow(ZLbl(L"你的名字:"), nameBox).spacing(12),
        greeting.vWeight(1),
        ZRow(greetBtn).spacing(12)
    ).spacing(10).margin(Thickness(20));

    greetBtn.on<&Button::Clicked>([nameBox, greeting] {
        auto name = nameBox->GetText();
        greeting->SetText(name.empty() ? L"你好,陌生人。" : L"你好," + name + L"!");
    });

    return ZApp().title(L"ZufyUI DSL 示例").size(760, 520).root(root).run();
}
  • ZTxt() / ZLbl() / ZBtn() 返回已经创建好的控件句柄;nameBox 不是空壳。
  • 不需要先写 Ref<TextBox>() 再“等它变成控件”。
  • ZApp().run() 内部已经 Create → 应用配置 → Show → Run,不要额外 win->Show()。
  • 如果项目启用了预编译头,文件第一行需要 #include "pch.h";这是工程配置,不属于 ZufyUI API。

推荐写法

能内联就内联:ZRow(ZLbl(L"名字"), ZTxt().placeholder(L"..."))。只有后面还要读取/修改某个控件时,才用 auto nameBox = ZTxt() 保存句柄;不要用空 Ref<T>() 占位。

变量、句柄与 Ref<T>

  • auto nameBox = ZTxt(); 返回 Ref<TextBox>,内部持有真实的 std::shared_ptr<TextBox>;auto 把类型藏起来,正常使用不需要写出 Ref。
  • Ref<T>() 是空句柄,不是工厂:它不会创建控件,ZRow / ZCol 会忽略它,直接 -> 访问会得到空指针。普通界面不需要用它。
  • 只有“类成员先声明、之后再赋值”或“明确需要可空引用”才用默认空 Ref;即使是这种场景,也建议优先用 std::shared_ptr<T> + 成员初始化。
  • 不想用 Ref 的链式糖时,DSL 容器也直接接受 shared_ptr,事件改回核心 Connect 即可:
auto nameBox = std::make_shared<TextBox>();
nameBox->SetPlaceholder(L"在这里输入...");

auto root = ZCol(
    ZRow(ZLbl(L"你的名字:"), nameBox).spacing(12)
);

nameBox->Connect(nameBox->TextChanged, [](const std::wstring&) {});
  • 类成员示例(不推荐把空 Ref 当普通构造):
dsl::Ref<Label> status_;          // 空句柄,等待赋值
status_ = dsl::ZLbl(L"就绪");     // 赋值后才指向真实控件

事件绑定

  • DSL 推荐语法是信号成员指针:.on<&Button::Clicked>(...)、.on<&ToggleSwitch::Toggled>(...)。
  • 也可以直接用核心信号槽:btn->Connect(btn->Clicked, ...)。
  • 不存在 Button::OnClicked,也不存在链式 .On(...)。Button::Clicked 只在 .on<&Button::Clicked> 这种成员指针位置合法。

WindowApp 的两种写法

直接链到 .run():

return ZApp()
    .title(L"ZufyUI DSL 示例")
    .size(760, 520)
    .root(ZCol(ZLbl(L"你好")))
    .run();

需要保存 builder 时,先构造再分步调用:

WindowApp app = ZApp();
app.title(L"ZufyUI DSL 示例");
app.size(760, 520);
app.root(ZCol(ZLbl(L"你好")));
return app.run();

不要写 auto app = ZApp().title(...):链式方法返回 WindowApp&,而 WindowApp 拷贝构造被删除,所以这条会编译失败。WindowApp 可移动但不可拷贝;直接链到 .run(),或先 WindowApp app = ZApp(); 是正确写法。

常见错误对照

容易写成 正确写法 原因
ZufyUI::Dsl ZufyUI::dsl 命名空间是小写 dsl
Col(...) / Row(...) ZCol(...) / ZRow(...) 短工厂统一 Z 前缀
Ref<TextBox>() ZTxt() 默认 Ref 是空句柄,不是工厂
SetPlaceholderText(...) SetPlaceholder(...) / .placeholder(...) 实际 API 名不同
ToggleSwitch(L"开关") ZToggle(true) + 旁边 ZLbl ZToggle 只接收 bool,不带标签
Button::OnClicked / .On(...) .on<&Button::Clicked>(...) 或 Connect ZufyUI 使用信号槽
auto app = ZApp().title(...) 直接链 .run(),或 WindowApp app = ZApp() 链式返回左值引用,拷贝被删除
ZApp().root(Col(...)) ZApp().root(ZCol(...)) root 需要 Ref<Layout>,短工厂是 ZCol

同时 using namespace ZufyUI; 和 using namespace ZufyUI::dsl; 是允许的:短工厂都有 Z 前缀,不会和类名冲突。

API 摘要

// 头文件:ZufyUIDsl.h(可选,零侵入;不改任何现有控件)
namespace ZufyUI::dsl {
template<class T> class Ref {                      // 包装 shared_ptr<T>
    T* operator->() const;   std::shared_ptr<T> shared() const;
    operator std::shared_ptr<T>() const;           // 兼容 AddChild/SetContent
    template<class C, class R, class...A0, class...A>
    Ref& with(R(C::*fn)(A0...), A&&... a);         // 通用 setter 转发(含继承来的 setter)
    template<class F> Ref& apply(F&& f);           // 逃生口:多步/条件逻辑用 lambda
    template<class Sig, class F> Ref& on(Sig& sig, F&& f);
    template<auto SigMem, class F> Ref& on(F&& f);
    template<class...C> Ref& add(C&&... c);        // 容器加子(按容器真实接口分派)
    Ref& cell(int row, int col, child, int rowSpan=1, int colSpan=1);   // GridLayout 专用
    Ref& width(float); Ref& height(float); Ref& size(float,float); Ref& margin(Thickness);
    Ref& minWidth(float); Ref& minHeight(float); Ref& maxWidth(float); Ref& maxHeight(float);
    Ref& minSize(float,float); Ref& maxSize(float,float);
    Ref& weight(float h,float v); Ref& hWeight(float); Ref& vWeight(float);
    Ref& fill(bool w=true,bool h=true); Ref& visible(bool=true); Ref& enabled(bool=true);
    Ref& tooltip(const std::wstring&); Ref& cache(bool=true); Ref& bleed(float);
    Ref& clipRect(const Rect&); Ref& noClip(); Ref& cursor(HCURSOR);
    Ref& dropTarget(bool=true); Ref& contextMenuEnabled(bool=true); Ref& accessible(const std::wstring&);
    // SFINAE 门控糖:仅当该控件有对应方法时才存在
    Ref& spacing(float); Ref& spacing(float,float); Ref& padding(const Thickness&);
    Ref& background(Color); Ref& textColor(Color); Ref& align(Alignment, Alignment);
    Ref& text(const std::wstring&); Ref& checked(bool=true); Ref& value(float);
    Ref& placeholder(const std::wstring&); Ref& image(std::shared_ptr<Image>); Ref& imageFit(bool=true);
    Ref& items({...}); Ref& rows(int); Ref& cols(int); Ref& header(int, const std::wstring&);
    Ref& cell(int row, int col, const std::wstring&);   // TableView 单元格
    Ref& root(const std::wstring&); Ref& separator(); Ref& submenu(const std::wstring&, Menu);
};
template<class T, class...A> Ref<T> ZMake(A&&... a);          // 通用工厂
template<class T> Ref<T> ZWrap(std::shared_ptr<T> p);         // 把已有 shared_ptr 接进链
Ref<ColumnBox> ZCol(children...);   Ref<RowBox> ZRow(...);
Ref<GridLayout> ZGrid(children...);                          // 也接受 ZCell(row,col,child)
CellSpec ZCell(int row, int col, child, int rowSpan=1, int colSpan=1);
using Align = GridLayout::Alignment;                        // 供 Ref::align 使用
// 短工厂统一 Z 前缀:ZLbl ZBtn ZTxt ZEdit ZCombo ZCheck ZRadio ZToggle
//   ZSlider ZNum ZProgress ZRing ZScroll ZSplit ZTabs ZList ZTable ZTree
//   ZBar ZLine ZPie ZCard ZExpander ZPages ZPage ZMenu ZSettings
//   ZMenuBar ZStatusBar ZRadioGroup ZScrollBar ZGlyph
// 因此与类同名也不会冲突;不需要额外别名。
class WindowApp {                                  // dsl::ZApp()
    WindowApp& size(int,int);   WindowApp& title(const std::wstring&);
    WindowApp& resizable(bool=true);
    WindowApp& backdrop(Backdrop, DWORD tint=0);   WindowApp& hidden(bool=true);
    WindowApp& minSize(int,int);   WindowApp& position(int,int);   WindowApp& frameRateLimit(int);
    WindowApp& theme(const Theme&);   WindowApp& useAppTheme(bool=true);
    WindowApp& dropTarget(bool=true);   WindowApp& titleBarVisible(bool=true);
    WindowApp& showTitleText(bool=true);   WindowApp& menuBarInTitleBar(bool=true);
    WindowApp& icon(HICON, HICON);
    WindowApp& root(Ref<Layout>);   WindowApp& titleBar(Ref<T>);   WindowApp& menuBar(Ref<T>);
    WindowApp& statusBar(Ref<T>);
    template<auto SigMem, class F> WindowApp& on(F&& f);      // 如 on<&Window::Closed>
    Window& window();   int run();                 // run(): Create → 应用配置 → Show() → Run()
};
WindowApp ZApp();
}
  • 用法:using namespace ZufyUI::dsl; 后 ZRow(ZBtn(L"OK").size(100,36).on<&Button::Clicked>([]{...}), ...)。所有短工厂统一 Z 前缀,因此与 using namespace ZufyUI; 同时用时也不会和类名冲突。
  • 容器 add() 按真实接口分派:ColumnBox/RowBox/Label → AddChild;PageHost → AddPage(非 Page 实参会被跳过);GridLayout 需要坐标,用 .cell(row,col,child[,rowSpan,colSpan]) 或 dsl::ZCell(...)。空元素(nullptr / 空 Ref)一律被忽略,不会解引用空指针。
  • ZGrid 坐标:ZGrid(ZCell(1,2,ZLbl(L"x")), ZCell(0,0,btn,1,2)) 显式定位;也仍接受裸子元素(沿用旧行为,按出现顺序排 (i,0),现有代码不受影响)。
  • 窗口构建器:dsl::ZApp() → WindowApp(链式 size/title/resizable/corner/backdrop/minSize/position/frameRateLimit/theme/useAppTheme/dropTarget/icon/titleBarVisible/showTitleText/menuBarInTitleBar/root/titleBar/menuBar/statusBar/hidden;信号用 on<&Window::Closed>(...))。root() 接受任意 Layout 子类(ZCol/ZRow/ZGrid 都行),titleBar/menuBar/statusBar 可直接收 Ref<T>。
  • 控件专属糖(SFINAE 门控:仅当控件有该方法时才存在):text/checked/value/placeholder/padding(float 与 Thickness)/category/series/slice/item/menu/separator/submenu/items/rows/cols/header/cell/root(s)/background/textColor/spacing(f 与 h,v)/align/image/imageFit;短工厂另有 ZPage()/ZMenu()/ZSettings()/ZRadioGroup()/ZScrollBar()/ZGlyph()。

易错

  • with(&T::Setter, args...) 传成员函数指针;setter 重载需 static_cast<...>(&T::SetX) 消歧。带默认参数的函数不能直接用于 with(成员指针含全部形参 → “参数太少”);这类函数自 v1.22.0 起已拆成无默认参数的重载(如 TreeView::SetCheckable(bool) / SetCheckableShallow(bool),ListView::AddItem(text) / AddItemWidget(shared_ptr<Label>),RadioGroup::AddItem / AddItemSelected,Menu::AddCheckItem / AddCheckItemCb / AddCheckItemRadio)。
  • 不宜用 with 表达的(多步、条件、需要迭代)用 apply(lambda),避免链断掉。普通类型转换告警也顺手消掉:.with(&TextBox::SetWidth, 220) 传 int 会报 C4244,直接用 .width(220.0f)。
  • Window::Create 不显示窗口(何时显示由应用决定),所以 WindowApp::run() 内部会补 Show();要隐藏启动就调 .hidden()。WindowApp 可移动、不可拷贝。Window::Run() 返回 void;Window 无公开 SetContent,根内容走 root(...)。
  • Image 不是 UIElement(是资源对象),所以没有 Ref<Image> 工厂 —— 用 Label 上的 .image(Image::FromFile(...)).imageFit(true)。
  • Ref<T>() 是空句柄,不是工厂;它不会自动变成控件,容器会忽略。普通 UI 用 ZTxt() / ZLbl() / ZBtn() / ZMake<T>()。
  • 事件绑定用 .on<&Button::Clicked>(...) 或核心 Connect;不存在 OnClicked / OnToggled / .On(...)。
  • auto app = ZApp().title(...) 会因拷贝构造被删除而失败;直接链到 .run(),或先 WindowApp app = ZApp(); 再分步调用。
  • 命名空间是小写 ZufyUI::dsl,短工厂是 ZCol / ZRow / ZLbl / ZBtn / ZTxt;不是 ZufyUI::Dsl / Col / Row。
查看源文件docs/src/API.md