ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

Language

API reference / v1.29.1

Window extras

Images, tray, system dialogs, app registration

Download Markdown

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 id re-Add becomes NIM_MODIFY; auto re-adds after Explorer restart.

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.
  • Version: v1.16.0 fixed 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=true forces 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_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.

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.

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.

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.

Pitfall

  • on device loss/rebuild the visual tree is recreated → listen to Window::DeviceLost, call CreateExternalVisual again and re-attach.
View sourcedocs/src/API.en.md