## 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窗口周边
图像、托盘、系统对话框、应用注册
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 的位图按不透明处理。
易错
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 重启后自动重加。
易错
- NOTIFYICON_VERSION_4 下右键以
WM_CONTEXTMENU在回调里到达,双击需手动计时(没有WM_LBUTTONDBLCLK)。自定义回调消息WM_APP+0x400。
版本: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会把外部 HWNDSetParent成它的WS_CHILD并显式显示。移动/缩放宿主时子窗口由系统一起走;宿主客户区负责裁剪,再叠加SetWindowRgn(元素矩形 ∩ 主窗口客户区 ∩ 所有祖先GetClipRect,含ScrollViewer视口)。 跨进程风险:跨进程SetParent技术合法但不推荐——会串联输入队列(一方卡死拖死另一方)、阻止部分窗口消息、可能出现间歇性不稳定,且目标进程可能不知道窗口被重父化。优先同进程;跨进程仅作最后手段。约定:需要“内容进合成、无 airspace”的网页/视频 → 用下面的CreateExternalVisual/ WebView2CompositionController。
易错
- 主窗口是
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();
- 返回一个 WinRT
ContainerVisual(已插到根视觉最上层),交给controller->put_RootVisualTarget(visual);元素Arrange时用SetExternalVisualBounds设位置/尺寸(DIP,内部换算物理像素)。 AddOverlaySync/RemoveOverlaySync/SyncOverlays供HwndView等“外部窗口宿主”注册同步回调,一般无需直接调用。
易错
- 设备丢失/重建后视觉树会重建 → 监听
Window::DeviceLost,重新CreateExternalVisual并重挂。