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.
## Nested public types

```cpp
struct BackgroundParams { float blurAmount=30, saturation=1; D2D1_COLOR_F tint, luminosity; float noiseOpacity=0.02f; };
enum class AcrylicPreset { Legacy, Luminosity, Base, Thin };
struct CaptionMetrics { bool valid; float rightMargin, top, height, width; };
enum class TaskbarProgress { None=0, Indeterminate=1, Normal=2, Error=4, Paused=8 };
enum class ThumbButtonId : UINT { Play=0, Pause=1, Prev=2, Next=3, MaxId=4 };
struct JumpListItem { std::wstring title, arguments, target, iconPath; int iconIndex=0; };
enum class ActivateMode { Raise, Activate, Foreground, All };
enum class OwnedMinimizePolicy { None, Hide, DisableMinimize };
```

## Static configuration

```cpp
inline static Backdrop DefaultBackdrop = Backdrop::None;
inline static DWORD     DefaultBackdropColor = 0xFFFFFFFF;   // pure white default, v1.17.0
static void SetDefaultBackdrop(Backdrop, DWORD tint = 0);
static void SetBackgroundParams(Backdrop which, const BackgroundParams&);
static void SetBackgroundParams(Backdrop which, AcrylicPreset);
static void SetDefaultFrameRateLimit(int fps);   // v1.14.2
static void SetDefaultAppIcon(HICON big, HICON small = nullptr);
static void SetProcessAppUserModelID(const std::wstring& id);
```

## Render driver (v1.27.0)

```cpp
enum class RenderDriver { Auto, Hardware, WARP, Unknown };
void SetRenderDriver(RenderDriver);
RenderDriver GetRequestedRenderDriver();
RenderDriver GetActiveRenderDriver();
bool IsRenderDriverReady();
std::wstring GetRenderDeviceName();
```
- **Call before the first `Window::Create` / D3D device creation**; calling after the device exists only records an error and does not switch.
- `Auto`: hardware first, fall back to WARP on failure; `Hardware`: force hardware; `WARP`: force software rasterization.
- `GetActiveRenderDriver()` returns the driver that actually succeeded; `GetRenderDeviceName()` returns the DXGI adapter name.
- **`Note`**: WARP only changes ZufyUI's own D3D11/D2D content rendering. WinRT Compositor, DWM composition and the Acrylic effect chain may still use the GPU. GPU usage approaches zero on a GPU-less Windows 10 VM because DWM itself is software in that environment.
- The demo accepts `--warp` / `--gpu`; the home page also has a restart-based switcher.
- **`Version`**: `v1.27.0`.

## Creation / lifecycle

```cpp
bool Create(int w, int h, const std::wstring& title, int x=CW_USEDEFAULT, int y=CW_USEDEFAULT);
bool IsValid() const;  HWND GetHwnd() const;  int GetId() const;
void Show(); void ShowNoActivate(); void Hide(); void Raise(); void Close();
void Run();  int RunModal(Window* owner = nullptr);
void SetInputBlocked(bool);  bool IsInputBlocked() const;
std::unique_lock<std::recursive_mutex> LockRender();  void RenderNowSync();
void SetNonBlockingPresent(bool);   bool GetNonBlockingPresent() const;
void SetDisplayFramePacing(bool);   bool GetDisplayFramePacing() const;
double GetDisplayRefreshHz() const;
enum class PresentationState { Hidden, Opening, Open, Closing, Closed };
void SetTransitionDurations(int enterMs, int exitMs);
PresentationState GetPresentationState() const;  float GetPresentationProgress() const;  bool IsTransitionActive() const;
inline static std::function<void(Window&)> DefaultWindowSetup;
```
- `SetNonBlockingPresent` / `SetDisplayFramePacing` are off by default and on for menus by default; pacing is effective only with nonblocking Present. `GetDisplayRefreshHz()` returns the current monitor refresh rate (60 when unknown).

###block_red_start
**Pitfall**

- `Create` does **not** auto-`Show` (since v1.8.0). `RunModal` disables the owner (`EnableWindow(FALSE)`) and deliberately does **not** use `IsDialogMessage`.
###block_red_end


## Temporary key handlers (v1.25.0)

```cpp
using KeyHandler = std::function<bool(int)>;
int  AddKeyHandler(KeyHandler handler);
void RemoveKeyHandler(int id);
```
- Called after `OnWindowKeyDown` and before the focused element; returning true marks the key handled.
- Handlers run in registration order; `AddKeyHandler` returns an id and `RemoveKeyHandler(id)` unregisters it.
- For temporary Esc handling in drawers/popups; remove on close/detach/destruction.
- **`Version`**: `v1.25.0`.

###block_red_start
**Pitfall**

- every key press copies a handler snapshot first; calling `RemoveKeyHandler` inside a callback does not cancel the current pass, and a just-removed handler may still run once.
- returning true swallows the key: the focused element and later handlers never see it. Do not unconditionally consume Tab/Enter/Esc.
- handlers usually capture a raw `this`; the owner must remove them before destruction, otherwise a live window can call back into a dangling object (`Drawer` handles this automatically).
- handlers run on the UI thread; do not block for long and do not add/remove them from other threads.
###block_red_end

## Three ways to create a window (which to pick)

| Way | Code | Ownership | Message loop | Use for |
|---|---|---|---|---|
| Stack value | `Window w; w.Create(...); w.Show(); app.Run();` | You (scope) | shared `Run()` | single main window, simple lifetime |
| `shared_ptr` | `auto w = app.CreateWindow(...); w->Show(); app.Run();` | `shared_ptr` refcount | shared `Run()` | multiple windows, dynamic create/destroy |
| Modal | `int r = w->RunModal(owner);` | same as `shared_ptr` | **nested** loop, blocks until closed | dialogs / confirmations |

###block_red_start
**Pitfall**

- `Window` is **non-copyable**; the stack form must **outlive `Run()`** (otherwise the loop still references a destroyed window).
- the `shared_ptr` from `Application::CreateWindow` **is the ownership** — dropping it destroys the window; `Create` also does not auto-`Show`.
###block_red_end

## Ownership / multi-window / size

```cpp
void SetOwner(Window*);  Window* GetOwner() const;
std::vector<Window*> GetOwnedWindows() const;
void HideOwnedWindows(); void ShowOwnedWindows();
void SetPosition(int x, int y);  void SetSize(int w, int h);   // DIP
void SetMinSize(int w, int h);
void SetOwnedMinimizePolicy(OwnedMinimizePolicy);
```

###block_red_start
**Pitfall**

- set `SetOwner` **before** `Create`, or the window gets its own taskbar button and does not minimize with the owner.
- `SetMinSize` **overrides** the content-based minimum. Without it, the minimum can be blown up by long text/charts (internally `rootElement->Measure(Size(0,0))`; with width 0 a wrapping Label reports its full single-line width). **Chart-bearing debugger windows set `SetMinSize` explicitly.**
###block_red_end

## Root content / capture

```cpp
void SetRootLayout(std::shared_ptr<Layout>);
std::shared_ptr<ColumnBox> GetRootColumnBox() const;   // default root: ColumnBox margin(20) spacing 10
void SetContextMenu(std::shared_ptr<Menu>);  void CloseContextMenu();
UIElement* HitTestElement(float x, float y);
void CollectDragRegions();  bool PointInDragRegion(float,float) const;
void MarkRepaint(UIElement*);   // marks only; does NOT schedule a frame
float GetDpiScale() const;  float GetClientWidthDip/HeightDip() const;
```

###block_red_start
**Pitfall**

- `MarkRepaint` takes a **non-owning** element pointer; do not keep it as a long-lived external pointer.
- `RequestRepaint()` → `MarkRepaint` does **not** schedule a frame. Frames come from the 16 ms `WM_TIMER` (when busy) or animation continuation. Historical note: forcing a frame here once caused a continuous re-render loop (severe stutter) — **reverted**.
###block_red_end

## Appearance / backdrop

```cpp
void SetBackdrop(Backdrop, DWORD tint=0);  Backdrop GetBackdrop() const;
void SetBackgroundColor(Color);
void SetContentOpacity(float opacity);
void SetTitleBarColors(COLORREF caption, COLORREF text, COLORREF border);
void SetResizable(bool);   void SetTitle(const std::wstring&);
void SetSuspendAnimationsWhileResizing(bool);   bool GetSuspendAnimationsWhileResizing() const;
```
- Backdrop is **hand-rolled** (Acrylic = host backdrop + effect chain; Mica = cached wallpaper layer). Change params via `SetBackgroundParams` or `UIZSignals::ReloadAcrylic`.
- Window corners are no longer a public API: Windows 10 keeps square corners to preserve DWM border/shadow, Windows 11 follows system rounding. Call Win32 DWM APIs yourself if you need custom corners, and handle Win10/Snap border/shadow risks yourself.
- **`Version`**: four-layer params `v1.8.1`; `SetContentOpacity` `v1.9.6`.

## Custom title bar

```cpp
void SetCustomTitleBar(std::shared_ptr<UIElement>);  std::shared_ptr<UIElement> GetCustomTitleBar() const;
bool HasCustomTitleBar() const;   void SetTitleBarVisible(bool);
CaptionMetrics QueryCaptionMetrics() const;
void Minimize(); void Maximize(); void Restore(); void MaximizeRestore();
bool IsMaximizedWindow() const;   void BeginSystemDrag();
// top menu bar / bottom status bar (window chrome, v1.19.2)
void SetMenuBar(std::shared_ptr<UIElement>);    std::shared_ptr<UIElement> GetMenuBar() const;
void SetStatusBar(std::shared_ptr<UIElement>);  std::shared_ptr<UIElement> GetStatusBar() const;
void SetMenuBarInTitleBar(bool on = true);      bool IsMenuBarInTitleBar() const;
void SetShowTitleText(bool on);                 bool IsShowTitleText() const;
```
- The menu bar is **overlaid on the custom title bar by default** (leaving room for the left icon and the right caption buttons); the title text is then **hidden by default** (they are mutually exclusive, to avoid overlap). `SetShowTitleText(true)` shows the title and moves the menu bar to the **top of the client area below the bar**; `SetMenuBarInTitleBar(false)` forces it to the client-area top. The status bar is pinned to the bottom and shrinks the root content height.

###block_red_start
**Pitfall**

- the custom title bar **does not participate in layout** — `Window` places it at `(0,0)` and shifts the root down by its measured height. Do not `AddChild` it manually.
###block_red_end

- **`Version`**: `v1.7.0`; `CaptionButton::Kind::Pin` = `v1.17.0`.

## Taskbar / thumbnails / jump list

```cpp
void SetTaskbarProgress(TaskbarProgress, ULONGLONG done=0, ULONGLONG total=0);  void ClearTaskbarProgress();
void SetTaskbarOverlayIcon(HICON, const std::wstring& = L"");  void ClearTaskbarOverlayIcon();
ZSignal<ThumbButtonId> ThumbButtonClicked;
void SetThumbButtons(...);  void UpdateThumbButton(ThumbButtonId, bool enabled);
void SetJumpList(...);  void Flash(int times=5, bool alsoTaskbar=true);  void FlashUntilForeground();
void SetAppUserModelID(const std::wstring&);
```
###block_orange_start

- **`Version`**: all `v1.9.6`.

## DPI

- Per-Monitor-v2 awareness set at static init (fallback `SetProcessDPIAware`).
- `WM_DPICHANGED` rebuilds the whole render chain and clears all caches.

###block_red_start
**Pitfall**

- element caches clear on DPI change, but child layout needs **no** manual re-measure.
###block_red_end

## Accessibility / signals

```cpp
void SetAccessibilityEnabled(bool);   bool IsAccessibilityEnabled() const;   // on by default, v1.17.0
UIElement* GetFocusedElement/HoveredElement/PressedElement() const;
void FocusElement(UIElement*);
ZSignal<> Activated, Deactivated;   ZSignal<bool*> Closing;   ZSignal<> Closed;
ZSignal<float, float> SizeChanged;   // client size in DIP
ZSignal<float> DpiChanged;           // DPI scale (96 = 1.0)
ZSignal<> BackdropUnsupported, DeviceLost;   ZSignal<HRESULT> RenderingError;
std::shared_ptr<Timer> CreateTimer(int intervalMs = 1000);
```
- `SizeChanged` fires on actual client-size changes in DIP (not when minimized); read the initial size with `GetClientWidthDip/HeightDip()`. `DpiChanged` fires first on a DPI change even if device rebuilding later fails; when the DIP client size changes, `SizeChanged` follows.

###block_orange_start

###block_red_start
**Pitfall**

- in `Closing`, set `*cancel = true` to veto the close. The parameter is `bool*` (not a reference).
###block_red_end

## Popup window behavior (v1.27.3)

```cpp
enum class Placement { SystemDefault, CenterOwner, CenterScreen };
enum class MoveBounds { Unrestricted, OwnerClient, MonitorWorkArea };
enum class CloseReason { Programmatic, Caption, Escape, System, Forced };
void SetPlacement(Placement);   Placement GetPlacement() const;
void CenterOnOwner();   void CenterOnScreen();
void SetMovable(bool);   bool IsMovable() const;
void SetCloseEnabled(bool);   bool IsCloseEnabled() const;
void SetCloseOnEscape(bool);   bool GetCloseOnEscape() const;
void SetFollowOwner(bool);   bool GetFollowOwner() const;
void SetMoveBounds(MoveBounds);   MoveBounds GetMoveBounds() const;
void RequestClose(CloseReason = CloseReason::Programmatic);   void ForceClose();
ZSignal<> Opening, Opened, BehaviorChanged;
ZSignal<CloseReason, bool*> CloseRequested;   ZSignal<CloseReason> CloseAccepted, CloseCancelled;
```

- Center placement applies only when no explicit initial position was set; `SetPosition` marks it explicit.
- `FollowOwner` moves owned child windows with the owner; `MoveBounds` constrains drag and monitor/owner-client bounds.
- `CloseRequested` can veto; `ForceClose` bypasses veto but still performs normal HWND cleanup.
- The first `Show` advances a frame before showing, reducing blank first popup frames.
Chapter 8

Window

Window (create, show, backdrop, title bar, taskbar, DPI, frame rate)

Nested public types

cpp
struct BackgroundParams { float blurAmount=30, saturation=1; D2D1_COLOR_F tint, luminosity; float noiseOpacity=0.02f; };
enum class AcrylicPreset { Legacy, Luminosity, Base, Thin };
struct CaptionMetrics { bool valid; float rightMargin, top, height, width; };
enum class TaskbarProgress { None=0, Indeterminate=1, Normal=2, Error=4, Paused=8 };
enum class ThumbButtonId : UINT { Play=0, Pause=1, Prev=2, Next=3, MaxId=4 };
struct JumpListItem { std::wstring title, arguments, target, iconPath; int iconIndex=0; };
enum class ActivateMode { Raise, Activate, Foreground, All };
enum class OwnedMinimizePolicy { None, Hide, DisableMinimize };

Static configuration

cpp
inline static Backdrop DefaultBackdrop = Backdrop::None;
inline static DWORD     DefaultBackdropColor = 0xFFFFFFFF;   // pure white default, v1.17.0
static void SetDefaultBackdrop(Backdrop, DWORD tint = 0);
static void SetBackgroundParams(Backdrop which, const BackgroundParams&);
static void SetBackgroundParams(Backdrop which, AcrylicPreset);
static void SetDefaultFrameRateLimit(int fps);   // v1.14.2
static void SetDefaultAppIcon(HICON big, HICON small = nullptr);
static void SetProcessAppUserModelID(const std::wstring& id);

Render driver (v1.27.0)

cpp
enum class RenderDriver { Auto, Hardware, WARP, Unknown };
void SetRenderDriver(RenderDriver);
RenderDriver GetRequestedRenderDriver();
RenderDriver GetActiveRenderDriver();
bool IsRenderDriverReady();
std::wstring GetRenderDeviceName();

Creation / lifecycle

cpp
bool Create(int w, int h, const std::wstring& title, int x=CW_USEDEFAULT, int y=CW_USEDEFAULT);
bool IsValid() const;  HWND GetHwnd() const;  int GetId() const;
void Show(); void ShowNoActivate(); void Hide(); void Raise(); void Close();
void Run();  int RunModal(Window* owner = nullptr);
void SetInputBlocked(bool);  bool IsInputBlocked() const;
std::unique_lock<std::recursive_mutex> LockRender();  void RenderNowSync();
void SetNonBlockingPresent(bool);   bool GetNonBlockingPresent() const;
void SetDisplayFramePacing(bool);   bool GetDisplayFramePacing() const;
double GetDisplayRefreshHz() const;
enum class PresentationState { Hidden, Opening, Open, Closing, Closed };
void SetTransitionDurations(int enterMs, int exitMs);
PresentationState GetPresentationState() const;  float GetPresentationProgress() const;  bool IsTransitionActive() const;
inline static std::function<void(Window&)> DefaultWindowSetup;

Pitfall

  • Create does not auto-Show (since v1.8.0). RunModal disables the owner (EnableWindow(FALSE)) and deliberately does not use IsDialogMessage.

Temporary key handlers (v1.25.0)

cpp
using KeyHandler = std::function<bool(int)>;
int  AddKeyHandler(KeyHandler handler);
void RemoveKeyHandler(int id);

Pitfall

  • every key press copies a handler snapshot first; calling RemoveKeyHandler inside a callback does not cancel the current pass, and a just-removed handler may still run once.
  • returning true swallows the key: the focused element and later handlers never see it. Do not unconditionally consume Tab/Enter/Esc.
  • handlers usually capture a raw this; the owner must remove them before destruction, otherwise a live window can call back into a dangling object (Drawer handles this automatically).
  • handlers run on the UI thread; do not block for long and do not add/remove them from other threads.

Three ways to create a window (which to pick)

Way Code Ownership Message loop Use for
Stack value Window w; w.Create(...); w.Show(); app.Run(); You (scope) shared Run() single main window, simple lifetime
shared_ptr auto w = app.CreateWindow(...); w->Show(); app.Run(); shared_ptr refcount shared Run() multiple windows, dynamic create/destroy
Modal int r = w->RunModal(owner); same as shared_ptr nested loop, blocks until closed dialogs / confirmations

Pitfall

  • Window is non-copyable; the stack form must outlive Run() (otherwise the loop still references a destroyed window).
  • the shared_ptr from Application::CreateWindow is the ownership — dropping it destroys the window; Create also does not auto-Show.

Ownership / multi-window / size

cpp
void SetOwner(Window*);  Window* GetOwner() const;
std::vector<Window*> GetOwnedWindows() const;
void HideOwnedWindows(); void ShowOwnedWindows();
void SetPosition(int x, int y);  void SetSize(int w, int h);   // DIP
void SetMinSize(int w, int h);
void SetOwnedMinimizePolicy(OwnedMinimizePolicy);

Pitfall

  • set SetOwner before Create, or the window gets its own taskbar button and does not minimize with the owner.
  • SetMinSize overrides the content-based minimum. Without it, the minimum can be blown up by long text/charts (internally rootElement->Measure(Size(0,0)); with width 0 a wrapping Label reports its full single-line width). Chart-bearing debugger windows set SetMinSize explicitly.

Root content / capture

cpp
void SetRootLayout(std::shared_ptr<Layout>);
std::shared_ptr<ColumnBox> GetRootColumnBox() const;   // default root: ColumnBox margin(20) spacing 10
void SetContextMenu(std::shared_ptr<Menu>);  void CloseContextMenu();
UIElement* HitTestElement(float x, float y);
void CollectDragRegions();  bool PointInDragRegion(float,float) const;
void MarkRepaint(UIElement*);   // marks only; does NOT schedule a frame
float GetDpiScale() const;  float GetClientWidthDip/HeightDip() const;

Pitfall

  • MarkRepaint takes a non-owning element pointer; do not keep it as a long-lived external pointer.
  • RequestRepaint() → MarkRepaint does not schedule a frame. Frames come from the 16 ms WM_TIMER (when busy) or animation continuation. Historical note: forcing a frame here once caused a continuous re-render loop (severe stutter) — reverted.

Appearance / backdrop

cpp
void SetBackdrop(Backdrop, DWORD tint=0);  Backdrop GetBackdrop() const;
void SetBackgroundColor(Color);
void SetContentOpacity(float opacity);
void SetTitleBarColors(COLORREF caption, COLORREF text, COLORREF border);
void SetResizable(bool);   void SetTitle(const std::wstring&);
void SetSuspendAnimationsWhileResizing(bool);   bool GetSuspendAnimationsWhileResizing() const;

Custom title bar

cpp
void SetCustomTitleBar(std::shared_ptr<UIElement>);  std::shared_ptr<UIElement> GetCustomTitleBar() const;
bool HasCustomTitleBar() const;   void SetTitleBarVisible(bool);
CaptionMetrics QueryCaptionMetrics() const;
void Minimize(); void Maximize(); void Restore(); void MaximizeRestore();
bool IsMaximizedWindow() const;   void BeginSystemDrag();
// top menu bar / bottom status bar (window chrome, v1.19.2)
void SetMenuBar(std::shared_ptr<UIElement>);    std::shared_ptr<UIElement> GetMenuBar() const;
void SetStatusBar(std::shared_ptr<UIElement>);  std::shared_ptr<UIElement> GetStatusBar() const;
void SetMenuBarInTitleBar(bool on = true);      bool IsMenuBarInTitleBar() const;
void SetShowTitleText(bool on);                 bool IsShowTitleText() const;

Pitfall

  • the custom title bar does not participate in layout — Window places it at (0,0) and shifts the root down by its measured height. Do not AddChild it manually.

Taskbar / thumbnails / jump list

cpp
void SetTaskbarProgress(TaskbarProgress, ULONGLONG done=0, ULONGLONG total=0);  void ClearTaskbarProgress();
void SetTaskbarOverlayIcon(HICON, const std::wstring& = L"");  void ClearTaskbarOverlayIcon();
ZSignal<ThumbButtonId> ThumbButtonClicked;
void SetThumbButtons(...);  void UpdateThumbButton(ThumbButtonId, bool enabled);
void SetJumpList(...);  void Flash(int times=5, bool alsoTaskbar=true);  void FlashUntilForeground();
void SetAppUserModelID(const std::wstring&);

block_orange_start

DPI

Pitfall

  • element caches clear on DPI change, but child layout needs no manual re-measure.

Accessibility / signals

cpp
void SetAccessibilityEnabled(bool);   bool IsAccessibilityEnabled() const;   // on by default, v1.17.0
UIElement* GetFocusedElement/HoveredElement/PressedElement() const;
void FocusElement(UIElement*);
ZSignal<> Activated, Deactivated;   ZSignal<bool*> Closing;   ZSignal<> Closed;
ZSignal<float, float> SizeChanged;   // client size in DIP
ZSignal<float> DpiChanged;           // DPI scale (96 = 1.0)
ZSignal<> BackdropUnsupported, DeviceLost;   ZSignal<HRESULT> RenderingError;
std::shared_ptr<Timer> CreateTimer(int intervalMs = 1000);

block_orange_start

Pitfall

  • in Closing, set *cancel = true to veto the close. The parameter is bool* (not a reference).
cpp
enum class Placement { SystemDefault, CenterOwner, CenterScreen };
enum class MoveBounds { Unrestricted, OwnerClient, MonitorWorkArea };
enum class CloseReason { Programmatic, Caption, Escape, System, Forced };
void SetPlacement(Placement);   Placement GetPlacement() const;
void CenterOnOwner();   void CenterOnScreen();
void SetMovable(bool);   bool IsMovable() const;
void SetCloseEnabled(bool);   bool IsCloseEnabled() const;
void SetCloseOnEscape(bool);   bool GetCloseOnEscape() const;
void SetFollowOwner(bool);   bool GetFollowOwner() const;
void SetMoveBounds(MoveBounds);   MoveBounds GetMoveBounds() const;
void RequestClose(CloseReason = CloseReason::Programmatic);   void ForceClose();
ZSignal<> Opening, Opened, BehaviorChanged;
ZSignal<CloseReason, bool*> CloseRequested;   ZSignal<CloseReason> CloseAccepted, CloseCancelled;
↑