面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
## Image / ImageManager / ImageDeviceCache

```cpp
class Image { int Width() const; int Height() const; bool IsNull() const; ... };
static std::shared_ptr<Image> Image::FromHBITMAP(HBITMAP, bool premultipliedAlpha = true);   // 从文件/资源/HICON/流加载
class ImageDeviceCache { /* 按渲染目标缓存的设备位图 */ };
```
- 设备丢失时(`UIZSignals::DeviceReset`)应释放与渲染目标绑定的位图缓存。
- `Image::FromHBITMAP(hbmp, premultipliedAlpha = true)` 默认按 **HBITMAP 的 alpha 通道处理**;Shell 图标或 GDI+ 生成的 alpha 位图可传 `false`;32bpp 无 alpha 的位图按不透明处理。

###block_red_start
**易错**

###block_red_end

## TrayIcon

```cpp
bool Add(HICON icon, const std::wstring& tooltip, UINT id=1);
void SetIcon(HICON);  void SetToolTip(const std::wstring&);  void SetMenu(std::shared_ptr<Menu>);
void SetClickImmediate(bool);   bool IsClickImmediate() const;
void SetBadge(Color = ...);   void ClearBadge();
enum class BalloonIcon : DWORD { None, Info, Warning, Error, Custom };
void ShowBalloon(const std::wstring& title, const std::wstring& text, BalloonIcon = BalloonIcon::Custom, HICON = nullptr, ...);
ZSignal<> Clicked, DoubleClicked, RightClicked, HoverEnter, HoverLeave, BalloonClicked, ...;
```
- 相同 `id` 再次 `Add` 变 `NIM_MODIFY`;Explorer 重启后自动重加。

###block_red_start
**易错**

- NOTIFYICON_VERSION_4 下右键以 `WM_CONTEXTMENU` 在回调里到达,**双击需手动计时**(没有 `WM_LBUTTONDBLCLK`)。自定义回调消息 `WM_APP+0x400`。
###block_red_end

- **`版本`**:`v1.16.0` 修回调消息撞号。

## 系统对话框 — FileDialog / ColorDialog(v1.16.0)

```cpp
struct FileFilter { std::wstring label; std::vector<std::wstring> patterns; };
struct FileDialogOptions {
    std::wstring title, initialDir, defaultFileName, defaultExtension;
    std::vector<FileFilter> filters; int filterIndex = 1;
    bool addAllFiles = true, pickFolders = false, multiSelect = false, save = false, forceFilesystem = true;
};
```
- 基于 `IFileDialog`/`ChooseColor`;`forceFilesystem=true` 强制文件系统路径(否则可能返回虚拟项)。

## 应用注册 AppInfo / RegisterApp

```cpp
struct AppInfo { std::wstring displayName, aumid; std::shared_ptr<Image> icon; };
bool RegisterApp(const AppInfo&);     // 或 Application::Instance().RegisterApp(info)
```
- 默认只设 AUMID(零文件/注册表副作用);定义 `ZUFYUI_ALLOW_APP_REGISTRATION` 才会写 `%LOCALAPPDATA%\ZufyUI\AppReg\...` 与 `HKCU\...\AppUserModelId`(让 Win10/11 toast 显示应用名/图标),退出自动清理。

## 原生窗口宿主 — `HwndView`(v1.23.0)

> 头文件 `ZufyUIHwndView.h`(`ZufyUIWindowTool.h` 末尾会包含)。用于把 WebView2 的 HWND controller、摄像头/采集窗口、第三方原生控件、进程外窗口嵌进 ZufyUI 布局。

```cpp
class HwndView : public UIElement {
public:
    explicit HwndView(HWND owner, bool activate = false);
    HWND GetHostHwnd() const;
    void SetContentHwnd(HWND external, bool own = false);
    HWND GetContentHwnd() const;
    void SetObscured(bool on);
    bool IsObscured() const;
    void SetOnBoundsChanged(std::function<void(HWND, int, int)>);
};
```

- 实现:创建一个**普通 Win32 顶层 owned 弹窗**作为宿主;`SetContentHwnd` 会把外部 HWND `SetParent` 成它的 `WS_CHILD` 并显式显示。移动/缩放宿主时子窗口由系统一起走;宿主客户区负责裁剪,再叠加 `SetWindowRgn`(元素矩形 ∩ 主窗口客户区 ∩ 所有祖先 `GetClipRect`,含 `ScrollViewer` 视口)。
- **`跨进程风险`**:跨进程 `SetParent` 技术合法但不推荐——会串联输入队列(一方卡死拖死另一方)、阻止部分窗口消息、可能出现间歇性不稳定,且目标进程可能不知道窗口被重父化。**优先同进程**;跨进程仅作最后手段。
- **`约定`**:需要“内容进合成、无 airspace”的网页/视频 → 用下面的 `CreateExternalVisual` / WebView2 `CompositionController`。

###block_red_start
**易错**

- 主窗口是 `WS_EX_NOREDIRECTIONBITMAP + DComp`,**子 HWND 不会被合成**,不能用普通子控件;`HwndView` 是 **airspace 浮窗**——永远在主窗口内容之上、窗口内自绘的下拉/ToolTip 压不住它(菜单是独立顶层窗口,不受影响)。
###block_red_end

## 外部视觉挂载 — `Window::CreateExternalVisual`(v1.23.0)

适合 WebView2 CompositionController、视频/采集等**能渲染进 DComp** 的内容。

```cpp
IUnknown* Window::CreateExternalVisual();
void Window::SetExternalVisualBounds(IUnknown* visual, float x, float y, float w, float h);
void Window::RemoveExternalVisual(IUnknown* visual);
int  Window::AddOverlaySync(std::function<void()>);
void Window::RemoveOverlaySync(int id);
void Window::SyncOverlays();
```

- 返回一个 WinRT `ContainerVisual`(已插到根视觉最上层),交给 `controller->put_RootVisualTarget(visual)`;元素 `Arrange` 时用 `SetExternalVisualBounds` 设位置/尺寸(DIP,内部换算物理像素)。
- `AddOverlaySync/RemoveOverlaySync/SyncOverlays` 供 `HwndView` 等“外部窗口宿主”注册同步回调,一般无需直接调用。

###block_red_start
**易错**

- 设备丢失/重建后视觉树会重建 → 监听 `Window::DeviceLost`,重新 `CreateExternalVisual` 并重挂。
###block_red_end
第 16 章

窗口周边

图像、托盘、系统对话框、应用注册

Image / ImageManager / ImageDeviceCache

cpp
class Image { int Width() const; int Height() const; bool IsNull() const; ... };
static std::shared_ptr<Image> Image::FromHBITMAP(HBITMAP, bool premultipliedAlpha = true);   // 从文件/资源/HICON/流加载
class ImageDeviceCache { /* 按渲染目标缓存的设备位图 */ };

易错

TrayIcon

cpp
bool Add(HICON icon, const std::wstring& tooltip, UINT id=1);
void SetIcon(HICON);  void SetToolTip(const std::wstring&);  void SetMenu(std::shared_ptr<Menu>);
void SetClickImmediate(bool);   bool IsClickImmediate() const;
void SetBadge(Color = ...);   void ClearBadge();
enum class BalloonIcon : DWORD { None, Info, Warning, Error, Custom };
void ShowBalloon(const std::wstring& title, const std::wstring& text, BalloonIcon = BalloonIcon::Custom, HICON = nullptr, ...);
ZSignal<> Clicked, DoubleClicked, RightClicked, HoverEnter, HoverLeave, BalloonClicked, ...;

易错

  • NOTIFYICON_VERSION_4 下右键以 WM_CONTEXTMENU 在回调里到达,双击需手动计时(没有 WM_LBUTTONDBLCLK)。自定义回调消息 WM_APP+0x400。

系统对话框 — FileDialog / ColorDialog(v1.16.0)

cpp
struct FileFilter { std::wstring label; std::vector<std::wstring> patterns; };
struct FileDialogOptions {
    std::wstring title, initialDir, defaultFileName, defaultExtension;
    std::vector<FileFilter> filters; int filterIndex = 1;
    bool addAllFiles = true, pickFolders = false, multiSelect = false, save = false, forceFilesystem = true;
};

应用注册 AppInfo / RegisterApp

cpp
struct AppInfo { std::wstring displayName, aumid; std::shared_ptr<Image> icon; };
bool RegisterApp(const AppInfo&);     // 或 Application::Instance().RegisterApp(info)

原生窗口宿主 — HwndView(v1.23.0)

头文件 ZufyUIHwndView.h(ZufyUIWindowTool.h 末尾会包含)。用于把 WebView2 的 HWND controller、摄像头/采集窗口、第三方原生控件、进程外窗口嵌进 ZufyUI 布局。

cpp
class HwndView : public UIElement {
public:
    explicit HwndView(HWND owner, bool activate = false);
    HWND GetHostHwnd() const;
    void SetContentHwnd(HWND external, bool own = false);
    HWND GetContentHwnd() const;
    void SetObscured(bool on);
    bool IsObscured() const;
    void SetOnBoundsChanged(std::function<void(HWND, int, int)>);
};

易错

  • 主窗口是 WS_EX_NOREDIRECTIONBITMAP + DComp,子 HWND 不会被合成,不能用普通子控件;HwndView 是 airspace 浮窗——永远在主窗口内容之上、窗口内自绘的下拉/ToolTip 压不住它(菜单是独立顶层窗口,不受影响)。

外部视觉挂载 — Window::CreateExternalVisual(v1.23.0)

适合 WebView2 CompositionController、视频/采集等能渲染进 DComp 的内容。

cpp
IUnknown* Window::CreateExternalVisual();
void Window::SetExternalVisualBounds(IUnknown* visual, float x, float y, float w, float h);
void Window::RemoveExternalVisual(IUnknown* visual);
int  Window::AddOverlaySync(std::function<void()>);
void Window::RemoveOverlaySync(int id);
void Window::SyncOverlays();

易错

  • 设备丢失/重建后视觉树会重建 → 监听 Window::DeviceLost,重新 CreateExternalVisual 并重挂。
↑