Image / ImageManager / ImageDeviceCache
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
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)
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
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 布局。
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 的内容。
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并重挂。