This chapter starts with copy-ready examples, then gives the API summary.
ZufyUIDsl.his an optional layer and changes no control tree; when a name is uncertain, use the header and this chapter — do not guess from Qt habits.
Minimal runnable example
#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"Type here...");
auto greeting = ZLbl(L"Hello, waiting...");
auto greetBtn = ZBtn(L"Greet");
auto root = ZCol(
ZRow(ZLbl(L"Your name:"), 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"Hello, stranger." : L"Hello, " + name + L"!");
});
return ZApp().title(L"ZufyUI DSL example").size(760, 520).root(root).run();
}
ZTxt()/ZLbl()/ZBtn()return handles to already-created controls;nameBoxis not an empty shell.- You do not need to write
Ref<TextBox>()first and wait for it to become a control. ZApp().run()already doesCreate → apply options → Show → Run; do not callwin->Show()again.- If the project uses a precompiled header, put
#include "pch.h"first; that is project configuration, not a ZufyUI API.
Recommended
Inline when possible:
ZRow(ZLbl(L"Name"), ZTxt().placeholder(L"...")). Keepauto nameBox = ZTxt()only when you need to read or modify that control later; do not use an emptyRef<T>()as a placeholder.
Variables, handles and Ref<T>
auto nameBox = ZTxt();returnsRef<TextBox>holding a realstd::shared_ptr<TextBox>;autohides the type, and normal use never needs to spellRef.Ref<T>()is an empty handle, not a factory: it creates no control,ZRow/ZColignore it, and dereferencing it gives a null pointer. Normal UI code does not need it.- Only use a default-constructed
Reffor a class member assigned later or for an explicitly nullable reference; even thenstd::shared_ptr<T>with a member initializer is usually clearer. - If you do not want the
Reffluent sugar, DSL containers also acceptshared_ptr; use the coreConnectfor events:
auto nameBox = std::make_shared<TextBox>();
nameBox->SetPlaceholder(L"Type here...");
auto root = ZCol(
ZRow(ZLbl(L"Your name:"), nameBox).spacing(12)
);
nameBox->Connect(nameBox->TextChanged, [](const std::wstring&) {});
- Class-member example (do not treat an empty Ref as ordinary construction):
dsl::Ref<Label> status_; // empty handle; wait for assignment
status_ = dsl::ZLbl(L"Ready"); // now points at a real control
Event binding
- The DSL form is a signal member pointer:
.on<&Button::Clicked>(...),.on<&ToggleSwitch::Toggled>(...). - The core signal form also works:
btn->Connect(btn->Clicked, ...). - There is no
Button::OnClickedand no chained.On(...).Button::Clickedis legal only in a member-pointer position such as.on<&Button::Clicked>.
Two ways to use WindowApp
Chain directly into .run():
return ZApp()
.title(L"ZufyUI DSL example")
.size(760, 520)
.root(ZCol(ZLbl(L"Hello")))
.run();
To keep the builder, construct it first and call methods as statements:
WindowApp app = ZApp();
app.title(L"ZufyUI DSL example");
app.size(760, 520);
app.root(ZCol(ZLbl(L"Hello")));
return app.run();
Do not write auto app = ZApp().title(...): chain methods return WindowApp&, and WindowApp has a deleted copy constructor, so that fails to compile. WindowApp is movable but not copyable; chain directly into .run(), or start with WindowApp app = ZApp();.
Common mistakes
| Wrong | Correct | Why |
|---|---|---|
ZufyUI::Dsl |
ZufyUI::dsl |
the namespace is lowercase dsl |
Col(...) / Row(...) |
ZCol(...) / ZRow(...) |
short factories use the Z prefix |
Ref<TextBox>() |
ZTxt() |
a default Ref is an empty handle, not a factory |
SetPlaceholderText(...) |
SetPlaceholder(...) / .placeholder(...) |
the actual API name differs |
ToggleSwitch(L"switch") |
ZToggle(true) plus a separate ZLbl |
ZToggle takes only a bool, no label |
Button::OnClicked / .On(...) |
.on<&Button::Clicked>(...) or Connect |
ZufyUI uses signals/slots |
auto app = ZApp().title(...) |
chain into .run(), or WindowApp app = ZApp() |
chaining returns an lvalue reference and copying is deleted |
ZApp().root(Col(...)) |
ZApp().root(ZCol(...)) |
root needs Ref<Layout>; the factory is ZCol |
Using both
using namespace ZufyUI;andusing namespace ZufyUI::dsl;is allowed: every short factory has theZprefix, so it does not collide with class names.
API summary
// header: ZufyUIDsl.h (optional, non-intrusive; changes no existing control)
namespace ZufyUI::dsl {
template<class T> class Ref { // wraps shared_ptr<T>
T* operator->() const; std::shared_ptr<T> shared() const;
operator std::shared_ptr<T>() const; // usable with AddChild/SetContent
template<class C, class R, class...A0, class...A>
Ref& with(R(C::*fn)(A0...), A&&... a); // generic setter forwarding (incl. inherited setters)
template<class F> Ref& apply(F&& f); // escape hatch: multi-step/conditional logic via 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); // add children (dispatches on the container's real API)
Ref& cell(int row, int col, child, int rowSpan=1, int colSpan=1); // GridLayout only
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-gated sugar: exists only when the control has that method
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 cell
Ref& root(const std::wstring&); Ref& separator(); Ref& submenu(const std::wstring&, Menu);
};
template<class T, class...A> Ref<T> ZMake(A&&... a); // generic factory
template<class T> Ref<T> ZWrap(std::shared_ptr<T> p); // wrap an existing shared_ptr into the chain
Ref<ColumnBox> ZCol(children...); Ref<RowBox> ZRow(...);
Ref<GridLayout> ZGrid(children...); // also accepts ZCell(row,col,child)
CellSpec ZCell(int row, int col, child, int rowSpan=1, int colSpan=1);
using Align = GridLayout::Alignment; // used by Ref::align
// short factories all use a Z prefix: 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
// This also avoids collisions with class names; no extra aliases are needed.
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); // e.g. on<&Window::Closed>
Window& window(); int run(); // run(): Create -> apply config -> Show() -> Run()
};
WindowApp ZApp();
}
- Usage:
using namespace ZufyUI::dsl;thenZRow(ZBtn(L"OK").size(100,36).on<&Button::Clicked>([]{...}), ...). Every short factory uses aZprefix, so combining it withusing namespace ZufyUI;no longer collides with class names. add()dispatches on the container's real API:ColumnBox/RowBox/Label→AddChild;PageHost→AddPage(non-Pagearguments are skipped);GridLayoutneeds coordinates, so use.cell(row,col,child[,rowSpan,colSpan])ordsl::ZCell(...). Null children (nullptr/ emptyRef) are always ignored — no null dereference.- ZGrid coordinates:
ZGrid(ZCell(1,2,ZLbl(L"x")), ZCell(0,0,btn,1,2))places cells explicitly; bare children are still accepted (old behaviour:(i,0)in order), so existing code is unaffected. - Window builder:
dsl::ZApp()→WindowApp(chainsize/title/resizable/corner/backdrop/minSize/position/frameRateLimit/theme/useAppTheme/dropTarget/icon/titleBarVisible/showTitleText/menuBarInTitleBar/root/titleBar/menuBar/statusBar/hidden; signals viaon<&Window::Closed>(...)).root()accepts anyLayoutsubclass (ZCol/ZRow/ZGrid), andtitleBar/menuBar/statusBartake aRef<T>directly. - Per-control sugar (SFINAE-gated: exists only when the control has the method):
text/checked/value/placeholder/padding(float and Thickness)/category/series/slice/item/menu/separator/submenu/items/rows/cols/header/cell/root(s)/background/textColor/spacing(f and h,v)/align/image/imageFit; extra short factories:ZPage()/ZMenu()/ZSettings()/ZRadioGroup()/ZScrollBar()/ZGlyph().
Pitfall
with(&T::Setter, args...)takes a member function pointer; overloaded setters needstatic_cast<...>(&T::SetX). A function with default arguments can't be used withwith(the pointer carries every parameter → "too few arguments"); since v1.22.0 such functions are split into non-defaulted overloads (e.g.TreeView::SetCheckable(bool)/SetCheckableShallow(bool),ListView::AddItem(text)/AddItemWidget(shared_ptr<Label>),RadioGroup::AddItem/AddItemSelected,Menu::AddCheckItem/AddCheckItemCb/AddCheckItemRadio).- anything
withcan't express (multi-step, conditional, needs iteration) goes throughapply(lambda)so the chain doesn't break. It also silences a conversion warning:.with(&TextBox::SetWidth, 220)passes anintand tripsC4244— prefer.width(220.0f).Window::Createdoes not show the window (the app decides when) —WindowApp::run()therefore callsShow(); use.hidden()to start hidden.WindowAppis movable but not copyable.Window::Run()returnsvoid;Windowhas no publicSetContent, so set the root viaroot(...).Imageis not aUIElement(it is a resource object), so there is noRef<Image>factory — use.image(Image::FromFile(...)).imageFit(true)on aLabel.Ref<T>()is an empty handle, not a factory; it never becomes a control and containers ignore it. UseZTxt()/ZLbl()/ZBtn()/ZMake<T>()for normal UI.- Bind events with
.on<&Button::Clicked>(...)or the coreConnect; there is noOnClicked/OnToggled/.On(...).auto app = ZApp().title(...)fails because copying is deleted; chain directly into.run(), or start withWindowApp app = ZApp();and call methods as statements.- The namespace is lowercase
ZufyUI::dsl, and short factories areZCol/ZRow/ZLbl/ZBtn/ZTxt; notZufyUI::Dsl/Col/Row.