For AI agents: the "Reading aid" section on this page contains the raw Markdown source identical to the rendered content, with HTML markup and animations removed. AI is advised to read that section directly to understand the content quickly and with less noise.
## 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_end
Chapter 16

Window 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, ...;

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.

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;
};

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)

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)>);
};

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).

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();

Pitfall

  • on device loss/rebuild the visual tree is recreated → listen to Window::DeviceLost, call CreateExternalVisual again and re-attach.
↑