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

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

从这里开始 · 支持全文搜索

框架概览

轻量到几 MB,快到原生合成。 纯头文件、零第三方依赖的 C++20 Windows 自绘 UI 框架,直接构建在 Direct2D 1.1 + DirectComposition 之上。 - 没有 Qt 的打包包袱,没有 Electron 的内存税。 几个头文件,include 即用;应用工程不链

易错点

> 这份文件把散落在代码注释、HANDOFF.md、TODO.md 里的“坑”集中到一处。接手/使用前先扫一遍。 > 优先级:易错 = 违反必踩;注意 = 契约/限制,违反易出问题;约定 = 库的取向;不要 = 明确不做。 --- 1. 链式构造 DSL(ZufyUIDsl.h) | | 状态 |

参考总览

> 本文档覆盖 ZufyUI 框架的全部公开 API,按“使用分类”组织(不是按代码/头文件顺序)。 > 配套阅读:[项目说明与构建](https://github.com/zhc9968/ZufyUI/blob/master/README.md)。 > 阅读方式:本文不是“签名清单”,而是按“它是

约定

颜色与标记 - 红色块:易错——真实踩坑、反直觉行为、会崩溃/UAF/竞争的用法,优先看。 - 橙色块:注意——线程、生命周期、绘制顺序等契约;不一定是错误,但违反后容易出问题。 - 绿色块:推荐——推荐写法、所有权模型、最佳实践。 - 普通项目符号表示普通语义、默认值或版本变化,不代表没有风险。

快速开始

最小程序 cpp include "ZufyUI.h" include "ZufyUIWidgets.h" using namespace ZufyUI; int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) { // Windows 子系

基础类型

Color cpp struct Color { float r, g, b, a; // 分量范围 [0,1],不是 0..255 Color(float r=0, float g=0, float b=0, float a=1.0f); static Color FromArgb(uint8t

事件与信号

何时用信号 - 控件对外通知(点击、选中、值变化)用内置 ZSignal。 - 自定义控件对外事件:自己声明 ZSignal 成员并 Fire。 ConnectionThread cpp enum class ConnectionThread { CurrentThread, NewThread,

语言

API 参考 / v1.29.1

窗口周边

图像、托盘、系统对话框、应用注册

下载 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);   // 从文件/资源/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 会把外部 HWND SetParent 成它的 WS_CHILD 并显式显示。移动/缩放宿主时子窗口由系统一起走;宿主客户区负责裁剪,再叠加 SetWindowRgn(元素矩形 ∩ 主窗口客户区 ∩ 所有祖先 GetClipRect,含 ScrollViewer 视口)。
  • 跨进程风险:跨进程 SetParent 技术合法但不推荐——会串联输入队列(一方卡死拖死另一方)、阻止部分窗口消息、可能出现间歇性不稳定,且目标进程可能不知道窗口被重父化。优先同进程;跨进程仅作最后手段。
  • 约定:需要“内容进合成、无 airspace”的网页/视频 → 用下面的 CreateExternalVisual / WebView2 CompositionController。

易错

  • 主窗口是 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 并重挂。
查看源文件docs/src/API.md