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

Conventions

Namespaces, units, lifetime, version & pitfall notation

Colours and markers

Namespaces and headers

Units

Pitfall

Object model & lifetime

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

Signals & events

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.

Defaults

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)

↑