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

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

Language

API reference / v1.29.1

DSL

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

Download Markdown

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

#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.

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>

  • 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:
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::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():

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; and using namespace ZufyUI::dsl; is allowed: every short factory has the Z prefix, 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; 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().

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.
View sourcedocs/src/API.en.md