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

拖放与卡片组件

Drag & Drop、Expander、SettingsList(v1.19.0)

下载 Markdown

拖放由 ZufyUIDragDrop.h 提供(ZufyUI.h 末尾已包含)。应用内默认 MOVE,跨应用 COPY。

// ---- 拖放:载荷 / 事件 ----
class DragData {                                   // 拖入方只读访问
    bool HasText() const;   std::wstring GetText() const;
    bool HasFiles() const;  std::vector<std::wstring> GetFiles() const;
    bool HasFormat(const std::wstring& fmt) const;
    bool GetFormatData(const std::wstring& fmt, std::vector<BYTE>& out) const;
};
struct DragEventArgs { const DragData& data; float x, y; DWORD allowed, effect, keyState; };   // x/y 为元素相对 DIP

// ---- 拖放:源端发起 ----
class DragDataBuilder {
    DragDataBuilder& AddText(const std::wstring&);
    DragDataBuilder& AddFile(const std::wstring& path);
    DragDataBuilder& AddFiles(const std::vector<std::wstring>& paths);
    DragDataBuilder& AddCustom(const std::wstring& fmt, const void* bytes, size_t n);
    DragDataBuilder& SetPreferredEffect(DWORD);
};
DWORD Window::BeginDrag(DragDataBuilder&, DWORD allowed = COPY|MOVE|LINK, UIElement* source = nullptr);

// ---- 拖放:目标端(元素)----
void UIElement::SetDropTargetEnabled(bool);   bool IsDropTargetEnabled() const;
DWORD UIElement::GetAllowedDropEffects() const;                   // 默认 COPY|MOVE|LINK
DWORD UIElement::OnDragEnter/OnDragOver(DragEventArgs&);         // 返回 effect
void  UIElement::OnDragLeave(DragEventArgs&);   DWORD UIElement::OnDrop(DragEventArgs&);
void UIElement::SetDragSource(std::function<void(DragDataBuilder&)>, DWORD allowed = COPY|MOVE|LINK);
ZSignal<DragEventArgs&> DragEnter, DragOver, DragLeave, Drop;

// ---- 拖放:整窗接收(光标未命中任何“启用落点”的元素时由窗口接收)----
void Window::SetDropTargetEnabled(bool);   bool Window::IsDropTargetEnabled() const;
ZSignal<DragEventArgs&> Window::DragEnter, DragOver, DragLeave, Drop;   // x/y = 客户区 DIP

// ---- Expander:可折叠卡片 ----
class Expander : public UIElement {
    Expander(const std::wstring& title = L"", const std::wstring& subtitle = L"");
    void SetTitle/SetSubtitle(const std::wstring&);   void SetContent(std::shared_ptr<UIElement>);
    std::shared_ptr<UIElement> GetContent() const;
    void SetExpanded(bool);   bool IsExpanded() const;   void Toggle();
    void SetIcon(Icon, float size = 22.0f);   // 标题前图标(None = 无)
    ZSignal<bool> ExpandedChanged;
};

// ---- SettingsList:设置行列表 ----
class SettingsList : public UIElement {
    void AddRow(Icon, const std::wstring& text, const std::wstring& subtitle, std::function<void()> onClick, const std::wstring& id = {});
    ZSignal<int> RowClicked;
};
  • 同控件内文本拖动:源端先删原选区、再按落点插入并左移修正;目标端检测私有格式 ZufyUI.TextSource 跳过重复插入。

易错

  • DragEventArgs.x/y 是元素相对 DIP(不是屏幕像素)。
  • Expander 的展开高度由动画进度进入 Measure,不再写用户可见的 height_;父布局仍会随动画收拢/推开后续元素。
  • 初始折叠时也会测量一次 content;展开状态的内容始终留在 childrenView_ 中,避免折叠再展开后内容不显示。
  • 内容裁剪会留 at least 4px bleed(并叠加 content 自身 bleed),避免 ComboBox 边框/阴影/焦点环被切。
  • 版本:折叠/展开用与页面切换相同的 smoothstep 缓动;箭头随同一缓动旋转(收起向下 → 展开向上)。v1.26.0 修复首次展开未测量、折叠再展开内容丢失和内容裁剪。
  • 版本:标题条悬停高亮(圆角);ComboBox 下拉箭头同样改为随展开旋转的 chevron。
  • 图片展示用 Label:SetImage + SetImageFit(true)(等比缩放至完整可见)+ SetDragSource(拖出)。
  • 版本:整窗接收——Window::SetDropTargetEnabled(true) + 窗口级 DragEnter/DragOver/DragLeave/Drop(x/y 为客户区 DIP)。
  • 版本:Expander::SetIcon(Icon, size) 在标题前加图标;TextEdit 撤销/重做改为标准方案(撤销/重做都还原当时的选区与光标)。
查看源文件docs/src/API.md