For AI agents: the "Reading aid" section on this page contains the raw Markdown source identical to the rendered content, with HTML markup and animations removed. AI is advised to read that section directly to understand the content quickly and with less noise.
> This chapter starts with copy-ready examples, then gives the API summary. `ZufyUIDsl.h` is 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

```cpp
#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**; `nameBox` is not an empty shell.
- You do not need to write `Ref<TextBox>()` first and wait for it to become a control.
- `ZApp().run()` already does `Create → apply options → Show → Run`; do not call `win->Show()` again.
- If the project uses a precompiled header, put `#include "pch.h"` first; that is project configuration, not a ZufyUI API.

###block_green_start
**Recommended**

Inline when possible: `ZRow(ZLbl(L"Name"), ZTxt().placeholder(L"..."))`. Keep `auto nameBox = ZTxt()` only when you need to read or modify that control later; do not use an empty `Ref<T>()` as a placeholder.
###block_green_end

## Variables, handles and `Ref<T>`

- `auto nameBox = ZTxt();` returns `Ref<TextBox>` holding a real `std::shared_ptr<TextBox>`; `auto` hides the type, and normal use never needs to spell `Ref`.
- `Ref<T>()` is an **empty handle**, not a factory: it creates no control, `ZRow` / `ZCol` ignore it, and dereferencing it gives a null pointer. Normal UI code does not need it.
- Only use a default-constructed `Ref` for a class member assigned later or for an explicitly nullable reference; even then `std::shared_ptr<T>` with a member initializer is usually clearer.
- If you do not want the `Ref` fluent sugar, DSL containers also accept `shared_ptr`; use the core `Connect` for events:

```cpp
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):

```cpp
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::OnClicked` and no chained `.On(...)`. `Button::Clicked` is legal only in a member-pointer position such as `.on<&Button::Clicked>`.

## Two ways to use `WindowApp`

Chain directly into `.run()`:

```cpp
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:

```cpp
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;` and `using namespace ZufyUI::dsl;` is allowed: every short factory has the `Z` prefix, so it does not collide with class names.

## API summary

```cpp
// 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;` then `ZRow(ZBtn(L"OK").size(100,36).on<&Button::Clicked>([]{...}), ...)`. Every short factory uses a `Z` prefix, so combining it with `using namespace ZufyUI;` no longer collides with class names.
- **`add()` dispatches on the container's real API**: `ColumnBox`/`RowBox`/`Label` → `AddChild`; `PageHost` → `AddPage` (non-`Page` arguments are skipped); `GridLayout` needs coordinates, so use `.cell(row,col,child[,rowSpan,colSpan])` or `dsl::ZCell(...)`. Null children (`nullptr` / empty `Ref`) 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` (chain `size/title/resizable/corner/backdrop/minSize/position/frameRateLimit/theme/useAppTheme/dropTarget/icon/titleBarVisible/showTitleText/menuBarInTitleBar/root/titleBar/menuBar/statusBar/hidden`; signals via `on<&Window::Closed>(...)`). `root()` accepts **any `Layout` subclass** (`ZCol`/`ZRow`/`ZGrid`), and `titleBar/menuBar/statusBar` take a `Ref<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()`.

###block_red_start
**Pitfall**

- `with(&T::Setter, args...)` takes a **member function pointer**; overloaded setters need `static_cast<...>(&T::SetX)`. A function with **default arguments** can't be used with `with` (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 `with` can't express (multi-step, conditional, needs iteration) goes through `apply(lambda)` so the chain doesn't break. It also silences a conversion warning: `.with(&TextBox::SetWidth, 220)` passes an `int` and trips `C4244` — prefer `.width(220.0f)`.
- `Window::Create` **does not show the window** (the app decides when) — `WindowApp::run()` therefore calls `Show()`; use `.hidden()` to start hidden. `WindowApp` is movable but not copyable. `Window::Run()` returns `void`; `Window` has no public `SetContent`, so set the root via `root(...)`.
- `Image` is **not** a `UIElement` (it is a resource object), so there is no `Ref<Image>` factory — use `.image(Image::FromFile(...)).imageFit(true)` on a `Label`.
- `Ref<T>()` is an empty handle, not a factory; it never becomes a control and containers ignore it. Use `ZTxt()` / `ZLbl()` / `ZBtn()` / `ZMake<T>()` for normal UI.
- Bind events with `.on<&Button::Clicked>(...)` or the core `Connect`; there is no `OnClicked` / `OnToggled` / `.On(...)`.
- `auto app = ZApp().title(...)` fails because copying is deleted; chain directly into `.run()`, or start with `WindowApp app = ZApp();` and call methods as statements.
- The namespace is lowercase `ZufyUI::dsl`, and short factories are `ZCol` / `ZRow` / `ZLbl` / `ZBtn` / `ZTxt`; not `ZufyUI::Dsl` / `Col` / `Row`.
###block_red_end
Chapter 19

DSL

Fluent construction (ZufyUIDsl.h, v1.19.4; extended in v1.20.0)

This chapter starts with copy-ready examples, then gives the API summary. ZufyUIDsl.h is 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

cpp
#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();
}

Recommended

Inline when possible: ZRow(ZLbl(L"Name"), ZTxt().placeholder(L"...")). Keep auto nameBox = ZTxt() only when you need to read or modify that control later; do not use an empty Ref<T>() as a placeholder.

Variables, handles and Ref<T>

cpp
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&) {});
cpp
dsl::Ref<Label> status_;          // empty handle; wait for assignment
status_ = dsl::ZLbl(L"Ready");    // now points at a real control

Event binding

Two ways to use WindowApp

Chain directly into .run():

cpp
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:

cpp
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; and using namespace ZufyUI::dsl; is allowed: every short factory has the Z prefix, so it does not collide with class names.

API summary

cpp
// 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();
}

Pitfall

  • with(&T::Setter, args...) takes a member function pointer; overloaded setters need static_cast<...>(&T::SetX). A function with default arguments can't be used with with (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 with can't express (multi-step, conditional, needs iteration) goes through apply(lambda) so the chain doesn't break. It also silences a conversion warning: .with(&TextBox::SetWidth, 220) passes an int and trips C4244 — prefer .width(220.0f).
  • Window::Create does not show the window (the app decides when) — WindowApp::run() therefore calls Show(); use .hidden() to start hidden. WindowApp is movable but not copyable. Window::Run() returns void; Window has no public SetContent, so set the root via root(...).
  • Image is not a UIElement (it is a resource object), so there is no Ref<Image> factory — use .image(Image::FromFile(...)).imageFit(true) on a Label.
  • Ref<T>() is an empty handle, not a factory; it never becomes a control and containers ignore it. Use ZTxt() / ZLbl() / ZBtn() / ZMake<T>() for normal UI.
  • Bind events with .on<&Button::Clicked>(...) or the core Connect; there is no OnClicked / OnToggled / .On(...).
  • auto app = ZApp().title(...) fails because copying is deleted; chain directly into .run(), or start with WindowApp app = ZApp(); and call methods as statements.
  • The namespace is lowercase ZufyUI::dsl, and short factories are ZCol / ZRow / ZLbl / ZBtn / ZTxt; not ZufyUI::Dsl / Col / Row.
↑