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

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

Language

API reference / v1.29.1

Conventions

Namespaces, units, lifetime, version & pitfall notation

Download Markdown

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

Pitfall

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

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

  • 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).

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

  • Every control has inline static Default* 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 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.
View sourcedocs/src/API.en.md