## 嵌套公开类型
```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 };
```
## 静态配置
```cpp
inline static Backdrop DefaultBackdrop = Backdrop::None;
inline static DWORD DefaultBackdropColor = 0xFFFFFFFF; // 默认纯白,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);
```
## 渲染驱动(v1.27.0)
```cpp
enum class RenderDriver { Auto, Hardware, WARP, Unknown };
void SetRenderDriver(RenderDriver);
RenderDriver GetRequestedRenderDriver();
RenderDriver GetActiveRenderDriver();
bool IsRenderDriverReady();
std::wstring GetRenderDeviceName();
```
- **必须在第一次 `Window::Create` / D3D 设备创建之前调用**;设备创建后再调用只记录错误,不会切换。
- `Auto`:硬件优先,失败回退 WARP;`Hardware`:强制硬件,失败即不可用;`WARP`:强制软件光栅化。
- `GetActiveRenderDriver()` 返回实际创建成功的驱动,`GetRenderDeviceName()` 返回 DXGI 适配器名称。
- **`注意`**:WARP 只改变 ZufyUI 自己的 D3D11/D2D 内容渲染;WinRT Compositor、DWM 合成和 Acrylic 效果仍可能使用 GPU。Win10 无 GPU 虚拟机中 DWM 整体软件化时,GPU 才接近 0。
- demo 支持 `--warp` / `--gpu`,首页底部也有重启进程的切换按钮。
- **`版本`**:`v1.27.0`。
## 创建 / 生命周期
```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` 默认关,菜单默认开;`SetDisplayFramePacing` 仅在非阻塞 Present 下生效。`GetDisplayRefreshHz()` 返回当前显示器刷新率(未知时为 60)。
###block_red_start
**易错**
- `Create` **不自动 `Show`**(v1.8.0 起)。`RunModal` 用 `EnableWindow(FALSE)` 禁用 owner、**不使用** `IsDialogMessage`。
###block_red_end
## 临时键处理器(v1.25.0)
```cpp
using KeyHandler = std::function<bool(int)>;
int AddKeyHandler(KeyHandler handler);
void RemoveKeyHandler(int id);
```
- 在 `OnWindowKeyDown` 之后、焦点元素之前调用;返回 true 表示已处理。
- 按注册顺序调用;`AddKeyHandler` 返回 id,`RemoveKeyHandler(id)` 注销。
- 供抽屉/浮层临时拦截 Esc;组件关闭/detach/析构时必须移除。
- **`版本`**:`v1.25.0`。
###block_red_start
**易错**
- 每次按键会先复制一份 handler 快照;在回调里 `RemoveKeyHandler` 不会取消当前这一轮,已经被移除的 handler 仍可能再执行一次。
- 返回 true 会吞掉按键,焦点元素和后续 handler 都收不到;不要无条件拦截 Tab/Enter/Esc。
- handler 通常捕获裸 `this`;宿主必须在销毁前移除,否则窗口还活着时会回调悬空对象(`Drawer` 已自动处理)。
- 键处理器在 UI 线程调用;不要在 handler 里长时间阻塞,也不要在其他线程增删。
###block_red_end
## 三种建窗方式(选哪个)
| 方式 | 代码 | 所有权 | 消息循环 | 适用场景 |
|---|---|---|---|---|
| 栈上值 | `Window w; w.Create(...); w.Show(); app.Run();` | 你自己(作用域) | 共享 `Run()` | 单一主窗口、生命周期简单 |
| `shared_ptr` | `auto w = app.CreateWindow(...); w->Show(); app.Run();` | `shared_ptr` 引用计数 | 共享 `Run()` | 多窗口、需动态创建/销毁 |
| 模态 | `int r = w->RunModal(owner);` | 同 `shared_ptr` | **嵌套**循环,阻塞至关闭 | 对话框 / 确认框 |
###block_red_start
**易错**
- `Window` **不可拷贝**;栈上用法要保证它**活得比 `Run()` 久**(否则消息循环仍在引用已析构窗口)。
- `Application::CreateWindow` 返回的 `shared_ptr` **就是所有权**——丢掉指针窗口就销毁;`Create` 也不会自动 `Show`。
###block_red_end
## 所有权 / 多窗口 / 尺寸
```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
**易错**
- `SetOwner` 要在 `Create` **之前**,否则会自带任务栏按钮、且不随 owner 最小化。
- `SetMinSize` 会**覆盖**基于内容的最小尺寸计算。含长文本/图表的窗口若不设,最小尺寸可能被内容撑大(内部用 `rootElement->Measure(Size(0,0))`,宽度 0 时换行 Label 会按整行宽度上报)。**含图表的调试器窗口已显式 `SetMinSize`。**
###block_red_end
## 根内容 / 捕获
```cpp
void SetRootLayout(std::shared_ptr<Layout>);
std::shared_ptr<ColumnBox> GetRootColumnBox() const; // 默认根: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*); // 标脏;只记录,不定帧(帧由定时器/动画驱动)
float GetDpiScale() const; float GetClientWidthDip/HeightDip() const;
```
###block_red_start
**易错**
- `MarkRepaint` 存**裸指针**,元素析构会自动注销;不要跨销毁持有外部指针。
- `RequestRepaint()` → `MarkRepaint` **不会**主动排一帧。帧由 16ms `WM_TIMER`(忙时)或动画续帧驱动。历史教训:曾在这里强制排帧,导致“每次重绘都出一帧”的持续重渲染(严重卡顿),**已回退**。
###block_red_end
## 外观 / 背景
```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;
```
- 背景是**自绘**:Acrylic = 宿主背景 + 自带效果链;Mica = 缓存壁纸层。改参数用 `SetBackgroundParams` 或 `UIZSignals::ReloadAcrylic`。
- 窗口圆角不再提供公开 API:Win10 保持系统直角以保留 DWM 边框/阴影,Win11 跟随系统圆角。需要自定义圆角时请自行调用 Win32 DWM API,并自行处理 Win10/Snap 的边框阴影风险。
- `DefaultBackdropColor` 默认纯白(v1.17.0)。`SetContentOpacity` 需合成后端就绪。
- **`版本`**:四层参数 `v1.8.1`;`SetContentOpacity` `v1.9.6`。
## 自定义标题栏
```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();
// 顶部菜单栏 / 底部状态栏(窗口级 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;
```
- 菜单栏默认**叠在自定义标题栏上**(让开左侧图标、右侧系统按钮);此时标题文字**默认隐藏**(与菜单互斥,避免重叠)。`SetShowTitleText(true)` → 显示标题、菜单栏**自动移到标题栏下方的客户区顶部**;`SetMenuBarInTitleBar(false)` 强制放到客户区顶部。状态栏固定贴底,根内容高度相应收缩。
###block_red_start
**易错**
- 自定义标题栏**不参与布局**——`Window` 把它放 `(0,0)`,并把根内容下移它测量出的高度。别手动 `AddChild`。
###block_red_end
- **`版本`**:`v1.7.0` 起;`CaptionButton::Kind::Pin` = `v1.17.0`。
## 任务栏 / 缩略图 / 跳转列表
```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
- **`版本`**:均 `v1.9.6`。
## DPI
- 进程级 Per-Monitor-v2 在静态初始化设置(回退 `SetProcessDPIAware`)。
- `WM_DPICHANGED` 会重建整条渲染链并清空所有缓存。
###block_red_start
**易错**
- 元素缓存会在 DPI 变更时被清;但子布局**不需要**你手动重测。
###block_red_end
## 无障碍 / 信号
```cpp
void SetAccessibilityEnabled(bool); bool IsAccessibilityEnabled() const; // 默认开,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` 在客户端 DIP 尺寸实际变化时触发(最小化时不触发);初始尺寸用 `GetClientWidthDip/HeightDip()` 读取。`DpiChanged` 在 DPI 变化时先触发,即使后续设备重建失败;DIP 客户端尺寸变化时会再触发 `SizeChanged`。
###block_orange_start
###block_red_start
**易错**
- `Closing` 里把 `*cancel = true` 可取消关闭。`Closing` 的参数是 `bool*`(不是引用)。
###block_red_end
## 弹窗窗口行为(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;
```
- `CenterOwner` 仅在未显式设置初始位置时生效;`SetPosition` 会标记为显式位置。
- `FollowOwner` 让 owned 子窗口在 owner 移动时跟随;`MoveBounds` 同时用于拖动和屏幕/工作区裁剪。
- 关闭优先级:`CloseRequested` 可拦截;`ForceClose` 跳过拦截但仍走正常 HWND 清理。
- 首次 `Show` 前会推进一帧,减少弹窗首帧空白。窗口
Window(创建、显示、背景、标题栏、任务栏、DPI、帧率)
嵌套公开类型
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 };
静态配置
cpp
inline static Backdrop DefaultBackdrop = Backdrop::None;
inline static DWORD DefaultBackdropColor = 0xFFFFFFFF; // 默认纯白,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);
渲染驱动(v1.27.0)
cpp
enum class RenderDriver { Auto, Hardware, WARP, Unknown };
void SetRenderDriver(RenderDriver);
RenderDriver GetRequestedRenderDriver();
RenderDriver GetActiveRenderDriver();
bool IsRenderDriverReady();
std::wstring GetRenderDeviceName();
- 必须在第一次
Window::Create/ D3D 设备创建之前调用;设备创建后再调用只记录错误,不会切换。 Auto:硬件优先,失败回退 WARP;Hardware:强制硬件,失败即不可用;WARP:强制软件光栅化。GetActiveRenderDriver()返回实际创建成功的驱动,GetRenderDeviceName()返回 DXGI 适配器名称。注意:WARP 只改变 ZufyUI 自己的 D3D11/D2D 内容渲染;WinRT Compositor、DWM 合成和 Acrylic 效果仍可能使用 GPU。Win10 无 GPU 虚拟机中 DWM 整体软件化时,GPU 才接近 0。- demo 支持
--warp/--gpu,首页底部也有重启进程的切换按钮。 版本:v1.27.0。
创建 / 生命周期
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默认关,菜单默认开;SetDisplayFramePacing仅在非阻塞 Present 下生效。GetDisplayRefreshHz()返回当前显示器刷新率(未知时为 60)。
易错
Create不自动Show(v1.8.0 起)。RunModal用EnableWindow(FALSE)禁用 owner、不使用IsDialogMessage。
临时键处理器(v1.25.0)
cpp
using KeyHandler = std::function<bool(int)>;
int AddKeyHandler(KeyHandler handler);
void RemoveKeyHandler(int id);
- 在
OnWindowKeyDown之后、焦点元素之前调用;返回 true 表示已处理。 - 按注册顺序调用;
AddKeyHandler返回 id,RemoveKeyHandler(id)注销。 - 供抽屉/浮层临时拦截 Esc;组件关闭/detach/析构时必须移除。
版本:v1.25.0。
易错
- 每次按键会先复制一份 handler 快照;在回调里
RemoveKeyHandler不会取消当前这一轮,已经被移除的 handler 仍可能再执行一次。 - 返回 true 会吞掉按键,焦点元素和后续 handler 都收不到;不要无条件拦截 Tab/Enter/Esc。
- handler 通常捕获裸
this;宿主必须在销毁前移除,否则窗口还活着时会回调悬空对象(Drawer已自动处理)。 - 键处理器在 UI 线程调用;不要在 handler 里长时间阻塞,也不要在其他线程增删。
三种建窗方式(选哪个)
| 方式 | 代码 | 所有权 | 消息循环 | 适用场景 |
|---|---|---|---|---|
| 栈上值 | Window w; w.Create(...); w.Show(); app.Run(); |
你自己(作用域) | 共享 Run() |
单一主窗口、生命周期简单 |
shared_ptr |
auto w = app.CreateWindow(...); w->Show(); app.Run(); |
shared_ptr 引用计数 |
共享 Run() |
多窗口、需动态创建/销毁 |
| 模态 | int r = w->RunModal(owner); |
同 shared_ptr |
嵌套循环,阻塞至关闭 | 对话框 / 确认框 |
易错
Window不可拷贝;栈上用法要保证它活得比Run()久(否则消息循环仍在引用已析构窗口)。Application::CreateWindow返回的shared_ptr就是所有权——丢掉指针窗口就销毁;Create也不会自动Show。
所有权 / 多窗口 / 尺寸
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);
易错
SetOwner要在Create之前,否则会自带任务栏按钮、且不随 owner 最小化。SetMinSize会覆盖基于内容的最小尺寸计算。含长文本/图表的窗口若不设,最小尺寸可能被内容撑大(内部用rootElement->Measure(Size(0,0)),宽度 0 时换行 Label 会按整行宽度上报)。含图表的调试器窗口已显式SetMinSize。
根内容 / 捕获
cpp
void SetRootLayout(std::shared_ptr<Layout>);
std::shared_ptr<ColumnBox> GetRootColumnBox() const; // 默认根: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*); // 标脏;只记录,不定帧(帧由定时器/动画驱动)
float GetDpiScale() const; float GetClientWidthDip/HeightDip() const;
易错
MarkRepaint存裸指针,元素析构会自动注销;不要跨销毁持有外部指针。RequestRepaint()→MarkRepaint不会主动排一帧。帧由 16msWM_TIMER(忙时)或动画续帧驱动。历史教训:曾在这里强制排帧,导致“每次重绘都出一帧”的持续重渲染(严重卡顿),已回退。
外观 / 背景
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;
- 背景是自绘:Acrylic = 宿主背景 + 自带效果链;Mica = 缓存壁纸层。改参数用
SetBackgroundParams或UIZSignals::ReloadAcrylic。 - 窗口圆角不再提供公开 API:Win10 保持系统直角以保留 DWM 边框/阴影,Win11 跟随系统圆角。需要自定义圆角时请自行调用 Win32 DWM API,并自行处理 Win10/Snap 的边框阴影风险。
DefaultBackdropColor默认纯白(v1.17.0)。SetContentOpacity需合成后端就绪。版本:四层参数v1.8.1;SetContentOpacityv1.9.6。
自定义标题栏
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();
// 顶部菜单栏 / 底部状态栏(窗口级 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;
- 菜单栏默认叠在自定义标题栏上(让开左侧图标、右侧系统按钮);此时标题文字默认隐藏(与菜单互斥,避免重叠)。
SetShowTitleText(true)→ 显示标题、菜单栏自动移到标题栏下方的客户区顶部;SetMenuBarInTitleBar(false)强制放到客户区顶部。状态栏固定贴底,根内容高度相应收缩。
易错
- 自定义标题栏不参与布局——
Window把它放(0,0),并把根内容下移它测量出的高度。别手动AddChild。
版本:v1.7.0起;CaptionButton::Kind::Pin=v1.17.0。
任务栏 / 缩略图 / 跳转列表
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
版本:均v1.9.6。
DPI
- 进程级 Per-Monitor-v2 在静态初始化设置(回退
SetProcessDPIAware)。 WM_DPICHANGED会重建整条渲染链并清空所有缓存。
易错
- 元素缓存会在 DPI 变更时被清;但子布局不需要你手动重测。
无障碍 / 信号
cpp
void SetAccessibilityEnabled(bool); bool IsAccessibilityEnabled() const; // 默认开,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在客户端 DIP 尺寸实际变化时触发(最小化时不触发);初始尺寸用GetClientWidthDip/HeightDip()读取。DpiChanged在 DPI 变化时先触发,即使后续设备重建失败;DIP 客户端尺寸变化时会再触发SizeChanged。
block_orange_start
易错
Closing里把*cancel = true可取消关闭。Closing的参数是bool*(不是引用)。
弹窗窗口行为(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;
CenterOwner仅在未显式设置初始位置时生效;SetPosition会标记为显式位置。FollowOwner让 owned 子窗口在 owner 移动时跟随;MoveBounds同时用于拖动和屏幕/工作区裁剪。- 关闭优先级:
CloseRequested可拦截;ForceClose跳过拦截但仍走正常 HWND 清理。 - 首次
Show前会推进一帧,减少弹窗首帧空白。