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

基础控件

Label、Button、TextBox、TextEdit、ComboBox

下载 Markdown

本类控件共享的坑:文本布局按 (文本, 盒, 格式) 全局缓存;改内部字符串务必走 setter(否则绕过失效逻辑);Color 分量是 [0,1];SetEnabled(false) ≠ SetVisible(false)。

Label

enum class TextOverflow { Wrap, Ellipsis };
enum class HAlign { Left, Center, Right };   enum class VAlign { Top, Center, Bottom };
Label(const std::wstring& text = L"");   // 默认空文本;不再自动显示 "Label"
void SetText(const std::wstring&);   std::wstring GetText() const;      // 失效布局 + 重绘
void SetTextFast(const std::wstring&);   // 仅池化 rebind:自身脏、不冒泡、不重绘
struct LabelRun { std::wstring text; std::optional<FontSpec> font; Color color = Color(0,0,0,0); bool underline = false; };
void SetRichText(const std::vector<LabelRun>&);  void ClearRichText();  bool HasRichText() const;
enum class RichTextClip { None, Clip, Ellipsis };  void SetRichTextClip(RichTextClip);  RichTextClip GetRichTextClip() const;
void SetTextColor(Color);   void SetTextOverflow(TextOverflow);
void SetAlignment(HAlign, VAlign);   void SetPadding(const Thickness&);
void SetBackgroundColor(Color);  void SetBackgroundCornerRadius(float);
void SetLineSpacing(float);  void SetMaxLines(int);   // 仅在 Wrap 下有意义
void SetImage(std::shared_ptr<Image>);   void SetIcon(Icon, float size=0);
void AddChild(std::shared_ptr<UIElement>);   // 图标/文本之后的内联子元素
std::wstring GetToolTip() const override;   // 省略时自动全量 tooltip(v1.17.0)

易错

  • SetTextFast 不重绘——池化容器(ListView/TableView)用它 + 容器自己重绘。直接用它设文本可能“看不到更新”。
  • 同时设了 image 与 glyph 时 image 优先。
  • GetDesiredSize() 只是上一次 Measure 的结果;用 FLT_MAX 直接测量得到的是理想尺寸,不代表父容器夹取后的尺寸。
  • 省略号判断与 Arrange 统一使用 0.5 DIP 容差,避免小数字号下可容纳文本被误截断。

  • 版本:SetIcon 家族 v1.13.0;省略自动 tooltip v1.17.0。

Button

ZSignal<> Clicked;   ZSignal<bool> Toggled;     // Toggled 需先 SetCheckable(true)
ZSignal<int> DropSelected;   ZSignal<> DropMenuOpened;   // 菜单项索引 / 菜单打开
Button(const std::wstring& text = L"Button");
void SetText/SetIcon/SetIconColor(...);
void SetColors(Color normal, Color hover, Color pressed);   void SetTextColor(Color);
void SetCornerRadius(float);   void SetHoverAnimationSpeed(float);
void SetCheckable(bool);  void SetChecked(bool);  bool IsChecked() const;
void SetAutoRepeat(bool enable, float intervalMs=400);   // 长按重复
void SetAutoSizeToText(bool);   inline static bool AutoSizeToText;   // 默认 true:按文案撑宽
std::shared_ptr<Label> GetLabel();  void SetContent(std::shared_ptr<UIElement>);  void ClearContent();
void SetDropWriteBack(bool);  void SetDropOpenOnClick(bool);   // 两个独立开关(2×2)
void SetDropItems(const std::vector<std::wstring>&, int selected=-1);  void SetDropMenu(std::shared_ptr<Menu>);  void ShowDropMenu();
  • 默认 120×36;按钮按下+抬起都在内部才 Clicked(点击始终回调)。
  • 富文本:内部 Label 已经是真正的子元素,GetLabel()->AddChild(...) 的子元素会被合成/布局/绘制;也可 SetContent 换成任意 UIElement。
  • 下拉 2×2:SetDropWriteBack 控制菜单选中是否回写按钮文字;SetDropOpenOnClick 控制按钮 Clicked 之后是否打开菜单。菜单是单选(上次选中项有标记);选中触发 DropSelected(index),可用 GetDropSelectedIndex/GetDropSelectedText 读取。SetDropItems 是文字列表快捷方式;自定义菜单用 SetDropMenu。
  • 主按钮 / 展开区:主区域点击始终 Clicked;右侧展开区(与主区域之间有一条跟随主题的浅色短分隔线)只打开菜单,不触发 Clicked;点菜单项只触发 DropSelected,不会触发 Clicked。DropOpenOnClick=false 时主区域只回调,菜单仍可由展开区打开。

易错

  • 非 checkable 时 IsChecked() 无意义;SetContent 的内容在扣除 padding 和右侧箭头后的矩形内布局。
  • 版本:v1.21.0 起按钮默认按文案自动撑宽;v1.23.3 支持富文本内容与下拉 2×2 组合。

TextBox(单行)

ZSignal<const std::wstring&> TextChanged;   ZSignal<> ReturnPressed;
void SetText(const std::wstring&);   // 会去掉 \r\n、截断到 maxLength、清撤销
void SetPlaceholder(...);  void SetPasswordMode(bool);  void SetMaxLength(int);   // -1 不限
void SetRevealPassword(bool);  bool IsPasswordRevealed() const;  void TogglePasswordReveal();
void SetPasswordRevealButtonVisible(bool);  bool IsPasswordRevealButtonVisible() const;
void SetReadOnly(bool);    void SetInputFilter(std::function<bool(wchar_t)>);
void SetError(bool);   void SetImeEnabled(bool);        // v1.12.0
void SetCursorBlinkInterval(float);  void SetCursorColor(Color);  void SetCursorThickness(float);
void SetFocusedBackgroundColor(Color);  void ClearFocusedBackgroundColor();
void SetFocusedBorderColor(Color);  void ClearFocusedBorderColor();  void SetIndicatorAlwaysVisible(bool);
void SelectAll/Copy/Cut/Paste/Undo/Redo();
int GetSelectionStart/End/CursorPosition() const;  void SetSelection(int,int);

易错

  • SetImeEnabled(false) 会抑制 IME/屏幕键盘(IsTextInput() 返回 imeEnabled_)。
  • 程序化 SetText 不产生撤销步。
  • 版本:error/indicator/IME v1.12.0;v1.18.0 修 shift+点击语义(无选区时也自锚点扩展)。

密码模式默认隐藏;右侧眼睛按钮可切换明文/密文。代码用 SetRevealPassword / TogglePasswordReveal 控制显示状态,SetPasswordRevealButtonVisible(false) 可隐藏按钮。

TextEdit(多行编辑器 / 只读查看器)— v1.18.0

QPlainTextEdit 风格:行号、换行、Tab 缩进、跨行选择、剪贴板、撤销/重做、查找、只读富文本。

enum class WrapMode { NoWrap, WidgetWidth };
ZSignal<const std::wstring&> TextChanged;   ZSignal<int,int> CursorPositionChanged;  ZSignal<> SelectionChanged;
std::wstring ToPlainText() const;  void SetPlainText(const std::wstring&);   // 清撤销
void AppendPlainText(const std::wstring&);  void InsertPlainText(const std::wstring&);
void SetRichText(const std::vector<std::vector<TextRun>>&);   // 强制只读;TextRun{ text, font, color, underline }
void SetReadOnly(bool);  void SetShowLineNumbers(bool);  void SetShowNewlines(bool);
void SetWrapMode(WrapMode);  void SetTabSize(int);  void SetInsertSpaces(bool);
int GetCursorLine/Column() const;  void SetCursorLineColumn(int,int);   // 0 基
void SelectLine(int);  void SelectWordAt(int);  bool Find(const std::wstring&, bool fwd=true, bool matchCase=false);
void EnsureCursorVisible();  float GetScrollOffsetY() const;  void SetScrollOffsetY(float);
bool UseCache() const override { return false; }
bool AcceptsTab() const override { return !readOnly_; }   // 依赖基类新虚函数
  • 默认 Consolas 14、320×160、tabSize 4。

最小示例:

auto edit = std::make_shared<TextEdit>();
edit->SetPlainText(L"hello\nworld");
edit->SetShowLineNumbers(true);
root->AddChild(edit);                 // 记得给尺寸或让它随布局铺满

易错

  • 换行宽度变化会重建每一行的 layout(ArrangeOverride 检测 wrapWidth_)。
  • 富文本构造即只读。行/列 API 是 0 基。
  • 因 AcceptsTab 为真,Tab 是插入缩进而非切换焦点。

ComboBox

ZSignal<int> SelectionChanged;   ZSignal<> DropDownOpened, DropDownClosed;
void AddItem/SetItems/InsertItem/RemoveItemAt/ClearItems(...);
void SetSelectedIndex(int);  int GetSelectedIndex() const;   // 过滤后“可见序”
void SetSelectedSourceIndex(int);  int GetSelectedSourceIndex() const;   // v1.15.0:源序
void SetItemDisabled(int visibleIndex, bool);   // 按源索引持久
void SetEditable(bool);  void SetFilterEnabled(bool);  void ApplyFilter();

易错

  • 下拉画在全局 DrawOverlay,可超出控件边界。
  • GetSelectedIndex() 是过滤后可见序;SetItemDisabled 按源索引持久(v1.15.0 修)。
  • 版本:下拉几何/状态 v1.12.0;源索引 API v1.15.0;下拉箭头随展开进度旋转(smoothstep,v1.19.0)。
查看源文件docs/src/API.md