Nested public types
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
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)
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
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/SetDisplayFramePacingare 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).
Pitfall
Createdoes not auto-Show(since v1.8.0).RunModaldisables the owner (EnableWindow(FALSE)) and deliberately does not useIsDialogMessage.
Temporary key handlers (v1.25.0)
using KeyHandler = std::function<bool(int)>;
int AddKeyHandler(KeyHandler handler);
void RemoveKeyHandler(int id);
- Called after
OnWindowKeyDownand before the focused element; returning true marks the key handled. - Handlers run in registration order;
AddKeyHandlerreturns an id andRemoveKeyHandler(id)unregisters it. - For temporary Esc handling in drawers/popups; remove on close/detach/destruction.
Version:v1.25.0.
Pitfall
- every key press copies a handler snapshot first; calling
RemoveKeyHandlerinside 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 (Drawerhandles 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
Windowis non-copyable; the stack form must outliveRun()(otherwise the loop still references a destroyed window).- the
shared_ptrfromApplication::CreateWindowis the ownership — dropping it destroys the window;Createalso does not auto-Show.
Ownership / multi-window / size
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
SetOwnerbeforeCreate, or the window gets its own taskbar button and does not minimize with the owner.SetMinSizeoverrides the content-based minimum. Without it, the minimum can be blown up by long text/charts (internallyrootElement->Measure(Size(0,0)); with width 0 a wrapping Label reports its full single-line width). Chart-bearing debugger windows setSetMinSizeexplicitly.
Root content / capture
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
MarkRepainttakes a non-owning element pointer; do not keep it as a long-lived external pointer.RequestRepaint()→MarkRepaintdoes not schedule a frame. Frames come from the 16 msWM_TIMER(when busy) or animation continuation. Historical note: forcing a frame here once caused a continuous re-render loop (severe stutter) — reverted.
Appearance / backdrop
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
SetBackgroundParamsorUIZSignals::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 paramsv1.8.1;SetContentOpacityv1.9.6.
Custom title bar
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.
Pitfall
- the custom title bar does not participate in layout —
Windowplaces it at(0,0)and shifts the root down by its measured height. Do notAddChildit manually.
Version:v1.7.0;CaptionButton::Kind::Pin=v1.17.0.
Taskbar / thumbnails / jump list
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&);
Version: allv1.9.6.
DPI
- Per-Monitor-v2 awareness set at static init (fallback
SetProcessDPIAware). WM_DPICHANGEDrebuilds the whole render chain and clears all caches.
Pitfall
- element caches clear on DPI change, but child layout needs no manual re-measure.
Accessibility / signals
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);
SizeChangedfires on actual client-size changes in DIP (not when minimized); read the initial size withGetClientWidthDip/HeightDip().DpiChangedfires first on a DPI change even if device rebuilding later fails; when the DIP client size changes,SizeChangedfollows.
Pitfall
- in
Closing, set*cancel = trueto veto the close. The parameter isbool*(not a reference).
Popup window behavior (v1.27.3)
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;
SetPositionmarks it explicit. FollowOwnermoves owned child windows with the owner;MoveBoundsconstrains drag and monitor/owner-client bounds.CloseRequestedcan veto;ForceClosebypasses veto but still performs normal HWND cleanup.- The first
Showadvances a frame before showing, reducing blank first popup frames.