## 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);
class ImageDeviceCache { /* device bitmaps keyed by render target */ };
```
###block_red_start
**Pitfall**
###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, ...;
```
- Same `id` re-`Add` becomes `NIM_MODIFY`; auto re-adds after Explorer restart.
###block_red_start
**Pitfall**
- with NOTIFYICON_VERSION_4 the right-click arrives as `WM_CONTEXTMENU` inside the callback and **double-click must be timed manually**. The custom callback message is `WM_APP+0x400`.
###block_red_end
- **`Version`**: `v1.16.0` fixed callback-message collision.
## System dialogs — 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;
};
```
- Based on `IFileDialog`/`ChooseColor`; `forceFilesystem=true` forces a filesystem path.
## App registration — AppInfo / RegisterApp
```cpp
struct AppInfo { std::wstring displayName, aumid; std::shared_ptr<Image> icon; };
bool RegisterApp(const AppInfo&); // or Application::Instance().RegisterApp(info)
```
- By default only sets the AUMID (zero file/registry side effects); defining `ZUFYUI_ALLOW_APP_REGISTRATION` writes `%LOCALAPPDATA%\ZufyUI\AppReg\...` and `HKCU\...\AppUserModelId` (so Win10/11 toasts show the app name/icon); auto-cleans on exit.
## Native window host — `HwndView` (v1.23.0)
> Header `ZufyUIHwndView.h` (auto-included at the end of `ZufyUIWindowTool.h`). Embeds a WebView2 HWND controller, camera/capture window, third-party native control, or an out-of-process window into the ZufyUI layout.
```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)>);
};
```
- Implementation: creates a **normal Win32 top-level owned popup** as the host; `SetContentHwnd` re-parents the external HWND as its `WS_CHILD` (cross-thread/cross-process allowed) and shows it explicitly. Moving/resizing the host moves the child natively; the host client clips it, plus `SetWindowRgn` (element rect ∩ window client ∩ every ancestor `GetClipRect`, incl. the `ScrollViewer` viewport).
- **`Cross-process risk`**: cross-process `SetParent` is technically legal but not recommended: it couples the input queues (one stuck process can freeze the other), blocks some window messages, can be intermittently unstable, and the target process may not know its window was re-parented. **Prefer same-process**; use cross-process only as a last resort.
- **`Convention`**: for "content goes into composition, no airspace" (web/video) use `CreateExternalVisual` below / WebView2 `CompositionController`.
###block_red_start
**Pitfall**
- the main window is `WS_EX_NOREDIRECTIONBITMAP + DComp`, so **child HWNDs are not composited**; do not use a normal child control. `HwndView` is an **airspace overlay** — always above the window content; in-window dropdowns/tooltips cannot cover it (menus are separate top-level windows and are unaffected).
###block_red_end
## External visual attachment — `Window::CreateExternalVisual` (v1.23.0)
For WebView2 CompositionController, video/capture, or anything that **renders into 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();
```
- Returns a WinRT `ContainerVisual` (inserted at the top of the root visual) to pass to `controller->put_RootVisualTarget(visual)`; set its position/size in `Arrange` via `SetExternalVisualBounds` (DIP, converted to physical pixels internally).
- `AddOverlaySync/RemoveOverlaySync/SyncOverlays` let external-window hosts (e.g. `HwndView`) register a sync callback; usually not called directly.
###block_red_start
**Pitfall**
- on device loss/rebuild the visual tree is recreated → listen to `Window::DeviceLost`, call `CreateExternalVisual` again and re-attach.
###block_red_endWindow extras
Images, tray, system dialogs, app registration
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);
class ImageDeviceCache { /* device bitmaps keyed by render target */ };
Pitfall
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, ...;
- Same
idre-AddbecomesNIM_MODIFY; auto re-adds after Explorer restart.
Pitfall
- with NOTIFYICON_VERSION_4 the right-click arrives as
WM_CONTEXTMENUinside the callback and double-click must be timed manually. The custom callback message isWM_APP+0x400.
Version:v1.16.0fixed callback-message collision.
System dialogs — 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;
};
- Based on
IFileDialog/ChooseColor;forceFilesystem=trueforces a filesystem path.
App registration — AppInfo / RegisterApp
cpp
struct AppInfo { std::wstring displayName, aumid; std::shared_ptr<Image> icon; };
bool RegisterApp(const AppInfo&); // or Application::Instance().RegisterApp(info)
- By default only sets the AUMID (zero file/registry side effects); defining
ZUFYUI_ALLOW_APP_REGISTRATIONwrites%LOCALAPPDATA%\ZufyUI\AppReg\...andHKCU\...\AppUserModelId(so Win10/11 toasts show the app name/icon); auto-cleans on exit.
Native window host — HwndView (v1.23.0)
Header
ZufyUIHwndView.h(auto-included at the end ofZufyUIWindowTool.h). Embeds a WebView2 HWND controller, camera/capture window, third-party native control, or an out-of-process window into the ZufyUI layout.
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)>);
};
- Implementation: creates a normal Win32 top-level owned popup as the host;
SetContentHwndre-parents the external HWND as itsWS_CHILD(cross-thread/cross-process allowed) and shows it explicitly. Moving/resizing the host moves the child natively; the host client clips it, plusSetWindowRgn(element rect ∩ window client ∩ every ancestorGetClipRect, incl. theScrollViewerviewport). Cross-process risk: cross-processSetParentis technically legal but not recommended: it couples the input queues (one stuck process can freeze the other), blocks some window messages, can be intermittently unstable, and the target process may not know its window was re-parented. Prefer same-process; use cross-process only as a last resort.Convention: for "content goes into composition, no airspace" (web/video) useCreateExternalVisualbelow / WebView2CompositionController.
Pitfall
- the main window is
WS_EX_NOREDIRECTIONBITMAP + DComp, so child HWNDs are not composited; do not use a normal child control.HwndViewis an airspace overlay — always above the window content; in-window dropdowns/tooltips cannot cover it (menus are separate top-level windows and are unaffected).
External visual attachment — Window::CreateExternalVisual (v1.23.0)
For WebView2 CompositionController, video/capture, or anything that renders into 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();
- Returns a WinRT
ContainerVisual(inserted at the top of the root visual) to pass tocontroller->put_RootVisualTarget(visual); set its position/size inArrangeviaSetExternalVisualBounds(DIP, converted to physical pixels internally). AddOverlaySync/RemoveOverlaySync/SyncOverlayslet external-window hosts (e.g.HwndView) register a sync callback; usually not called directly.
Pitfall
- on device loss/rebuild the visual tree is recreated → listen to
Window::DeviceLost, callCreateExternalVisualagain and re-attach.