这一章先给可直接照抄的写法,再给 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。