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

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

Language

API reference / v1.29.1

Window

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

Download Markdown

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

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)

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.

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

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

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

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

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 — Window places it at (0,0) and shifts the root down by its measured height. Do not AddChild it 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: 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.

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

Pitfall

  • in Closing, set *cancel = true to veto the close. The parameter is bool* (not a reference).
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.
View sourcedocs/src/API.en.md