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);
class ImageDeviceCache { /* device bitmaps keyed by render target */ };
Pitfall
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, ...;
- 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)
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
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.
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.
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.