## Colours and markers - **Red block**: `Pitfall` — real traps, counter-intuitive behaviour, and usage that can crash/UAF/race. Read these first. - **Orange block**: `Note` — contracts such as threading, lifetime and paint order. Not necessarily an error, but violating them usually leads to one. - **Green block**: `Recommended` — preferred usage, ownership models and best practices. - Plain bullets are ordinary semantics, defaults or version changes; they are not automatically risk-free. ## Namespaces and headers - Everything is in `namespace ZufyUI`. - Headers are **layered by usage**: - `ZufyUI.h`: core — types / signals / fonts / element base / layout / menus / window. - `ZufyUIAcrylic.h`: hand-written DComp composition effects + the official acrylic/mica recipes (included by `ZufyUI.h`). - `ZufyUIWidgets.h`: basic controls (Label/Button/TextBox/TextEdit/ComboBox/…/ScrollViewer/TabView/icons), includes `ZufyUI.h`. - `ZDataViewer.h`: data views (ListView/TableView/TreeView), depends on the two above. - `ZufyUICharts.h`: **charts (BarChart/LineChart/PieChart)**, depends on `ZufyUI.h`. - `ZufyUIImages.h`: `Image` / `ImageManager` (image loading and device cache). - `ZufyUIIcons.h`: the `FontIcon` glyph control (the `Icon` enum itself lives in `ZufyUIWidgets.h`). - `ZufyUIWindowTool.h`: window extras (title bar / MessageBox / tray / system dialogs / accessibility provider / debug channel); **since v1.20.0 it includes `ZufyUIWidgets.h` itself**, so it can be included on its own; it includes `ZufyUIHwndView.h` at the end. - `ZufyUIHwndView.h`: native HWND host `HwndView` (WebView2 / camera / third-party / out-of-process windows). - `ZufyUIDragDrop.h`: drag & drop (included at the end of `ZufyUI.h`). - `ZufyUIDsl.h`: optional **fluent construction DSL** (purely additive; changes no existing control). - All are **header-only**; `#pragma comment(lib, ...)` auto-links `d2d1 / dwrite / dwmapi / imm32 / winmm`. - **Source encoding**: `.h` / `.cpp` files containing non-ASCII (e.g. Chinese) must be saved as **UTF-8 with BOM** (otherwise MSVC decodes them with the local code page and reports `C2143/C2259/C2888/C4819`); `.md` / `.tex` are saved as **UTF-8 without BOM**. For a BOM-free / ASCII-only copy, use `tools/export_ascii.py` (output `dist/ascii`, not committed; see the README's "ASCII-only export"). ## Units - All coordinates and sizes are **DIP** (device-independent pixels), not physical pixels. - The framework snaps to the physical pixel grid via `Snap()` before drawing; you do **not** do DPI math yourself. - Mouse event coordinates are DIP too. Screen coordinates only appear in system APIs (`Create`, `ShowAt`, `FileDialog`). ###block_red_start **Pitfall** ###block_red_end ## Object model & lifetime - Controls are owned by `std::shared_ptr<T>`, created with `std::make_shared<T>()`. - Mount to a parent via the container's `AddChild()`; the parent holds the child's `shared_ptr` — **the child survives as long as the parent**. - Detached with no other `shared_ptr`, the element is destroyed; destruction auto-releases its offscreen cache and registered connections (internal `ConnectionGroup`). ###block_green_start **Recommended ownership model** Controls are owned by `std::shared_ptr`; the parent container holds children via `AddChild`. Use raw pointers or `weak_ptr` for cross-layer references; do not hold a parent's `shared_ptr` back, and do not let two containers own the same control. ###block_green_end ###block_red_start **Pitfall** - `UIElement::SetParent` stores a **raw** (non-owning) pointer; ownership always lives in the container/`Application` `shared_ptr`. An element records its window only as a **window id**, to avoid UAF if the window is destroyed first. ###block_red_end ## Signals & events - Bind with `Connect(signal, slot)`, returns a `Connection`, auto-disconnected when the host element is destroyed. - The slot may be any callable (lambda / function pointer / `std::function`). ###block_red_start **Pitfall** - do not connect a lambda that captures the host's own `shared_ptr` by value to the host's own signal — reference cycle, the whole subtree leaks. See the "Events & Signals" chapter. ###block_red_end ## Defaults - Every control has `inline static` `Default*` fields (e.g. `Button::DefaultSize`). - `static SetDefault*()` affects **only instances created afterwards**; instance setters affect only that instance. ###block_red_start **Pitfall** - static defaults are **process-global**; for different looks across windows, set before creating, or use per-instance setters. ###block_red_end ## Three cross-cutting concepts (all controls) - **Enabled/disabled**: `UIElement::SetEnabled(false)` makes the element and subtree non-interactive (mouse/keyboard blocked); controls decide graying via `IsEffectivelyEnabled()`. **Disabled does not change layout** (still occupies space). `SetEnabled(false)` ≠ `SetVisible(false)`. - **Focus**: only elements whose `IsFocusable()` returns true can take keyboard focus. Tab traversal moves focus; the focus ring shows only when focus comes from Tab, not mouse. - **Offscreen cache**: see the "Element base" chapter. On by default; turn it off with `SetUseCache(false)` for frequently-animating / many-instance controls to save VRAM.
Conventions
Namespaces, units, lifetime, version & pitfall notation
Colours and markers
- Red block:
Pitfall— real traps, counter-intuitive behaviour, and usage that can crash/UAF/race. Read these first. - Orange block:
Note— contracts such as threading, lifetime and paint order. Not necessarily an error, but violating them usually leads to one. - Green block:
Recommended— preferred usage, ownership models and best practices. - Plain bullets are ordinary semantics, defaults or version changes; they are not automatically risk-free.
Namespaces and headers
- Everything is in
namespace ZufyUI. - Headers are layered by usage:
ZufyUI.h: core — types / signals / fonts / element base / layout / menus / window.ZufyUIAcrylic.h: hand-written DComp composition effects + the official acrylic/mica recipes (included byZufyUI.h).ZufyUIWidgets.h: basic controls (Label/Button/TextBox/TextEdit/ComboBox/…/ScrollViewer/TabView/icons), includesZufyUI.h.ZDataViewer.h: data views (ListView/TableView/TreeView), depends on the two above.ZufyUICharts.h: charts (BarChart/LineChart/PieChart), depends onZufyUI.h.ZufyUIImages.h:Image/ImageManager(image loading and device cache).ZufyUIIcons.h: theFontIconglyph control (theIconenum itself lives inZufyUIWidgets.h).ZufyUIWindowTool.h: window extras (title bar / MessageBox / tray / system dialogs / accessibility provider / debug channel); since v1.20.0 it includesZufyUIWidgets.hitself, so it can be included on its own; it includesZufyUIHwndView.hat the end.ZufyUIHwndView.h: native HWND hostHwndView(WebView2 / camera / third-party / out-of-process windows).ZufyUIDragDrop.h: drag & drop (included at the end ofZufyUI.h).ZufyUIDsl.h: optional fluent construction DSL (purely additive; changes no existing control).- All are header-only;
#pragma comment(lib, ...)auto-linksd2d1 / dwrite / dwmapi / imm32 / winmm. - Source encoding:
.h/.cppfiles containing non-ASCII (e.g. Chinese) must be saved as UTF-8 with BOM (otherwise MSVC decodes them with the local code page and reportsC2143/C2259/C2888/C4819);.md/.texare saved as UTF-8 without BOM. For a BOM-free / ASCII-only copy, usetools/export_ascii.py(outputdist/ascii, not committed; see the README's "ASCII-only export").
Units
- All coordinates and sizes are DIP (device-independent pixels), not physical pixels.
- The framework snaps to the physical pixel grid via
Snap()before drawing; you do not do DPI math yourself. - Mouse event coordinates are DIP too. Screen coordinates only appear in system APIs (
Create,ShowAt,FileDialog).
Pitfall
Object model & lifetime
- Controls are owned by
std::shared_ptr<T>, created withstd::make_shared<T>(). - Mount to a parent via the container's
AddChild(); the parent holds the child'sshared_ptr— the child survives as long as the parent. - Detached with no other
shared_ptr, the element is destroyed; destruction auto-releases its offscreen cache and registered connections (internalConnectionGroup).
Recommended ownership model
Controls are owned by std::shared_ptr; the parent container holds children via AddChild. Use raw pointers or weak_ptr for cross-layer references; do not hold a parent's shared_ptr back, and do not let two containers own the same control.
Pitfall
UIElement::SetParentstores a raw (non-owning) pointer; ownership always lives in the container/Applicationshared_ptr. An element records its window only as a window id, to avoid UAF if the window is destroyed first.
Signals & events
- Bind with
Connect(signal, slot), returns aConnection, auto-disconnected when the host element is destroyed. - The slot may be any callable (lambda / function pointer /
std::function).
Pitfall
- do not connect a lambda that captures the host's own
shared_ptrby value to the host's own signal — reference cycle, the whole subtree leaks. See the "Events & Signals" chapter.
Defaults
- Every control has
inline staticDefault*fields (e.g.Button::DefaultSize). static SetDefault*()affects only instances created afterwards; instance setters affect only that instance.
Pitfall
- static defaults are process-global; for different looks across windows, set before creating, or use per-instance setters.
Three cross-cutting concepts (all controls)
- Enabled/disabled:
UIElement::SetEnabled(false)makes the element and subtree non-interactive (mouse/keyboard blocked); controls decide graying viaIsEffectivelyEnabled(). Disabled does not change layout (still occupies space).SetEnabled(false)≠SetVisible(false). - Focus: only elements whose
IsFocusable()returns true can take keyboard focus. Tab traversal moves focus; the focus ring shows only when focus comes from Tab, not mouse. - Offscreen cache: see the "Element base" chapter. On by default; turn it off with
SetUseCache(false)for frequently-animating / many-instance controls to save VRAM.