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 viaAddChild. Use raw pointers orweak_ptrfor cross-layer references; do not hold a parent'sshared_ptrback, 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.