面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
> 本类控件共享的坑:文本布局按 `(文本, 盒, 格式)` 全局缓存;改内部字符串务必走 setter(否则绕过失效逻辑);`Color` 分量是 [0,1];`SetEnabled(false)` ≠ `SetVisible(false)`。

## Label

```cpp
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)
```

###block_red_start
**易错**

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

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

## Button

```cpp
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` 时主区域只回调,菜单仍可由展开区打开。

###block_red_start
**易错**

- 非 checkable 时 `IsChecked()` 无意义;`SetContent` 的内容在扣除 `padding` 和右侧箭头后的矩形内布局。
###block_red_end

- **`版本`**:`v1.21.0` 起按钮**默认按文案自动撑宽**;`v1.23.3` 支持富文本内容与下拉 2×2 组合。

## TextBox(单行)

```cpp
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);
```

###block_red_start
**易错**

- `SetImeEnabled(false)` 会抑制 IME/屏幕键盘(`IsTextInput()` 返回 `imeEnabled_`)。
- 程序化 `SetText` **不产生撤销步**。
###block_red_end

- **`版本`**:error/indicator/IME `v1.12.0`;`v1.18.0` 修 shift+点击语义(无选区时也自锚点扩展)。

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

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

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

```cpp
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。

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

###block_red_start
**易错**

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

## ComboBox

```cpp
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();
```

###block_red_start
**易错**

- 下拉画在全局 `DrawOverlay`,可超出控件边界。
- `GetSelectedIndex()` 是**过滤后可见序**;`SetItemDisabled` 按**源索引**持久(v1.15.0 修)。
###block_red_end

- **`版本`**:下拉几何/状态 `v1.12.0`;源索引 API `v1.15.0`;下拉箭头随展开进度旋转(smoothstep,`v1.19.0`)。
第 9 章

基础控件

Label、Button、TextBox、TextEdit、ComboBox

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

Label

cpp
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 直接测量得到的是理想尺寸,不代表父容器夹取后的尺寸。

Button

cpp
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();

易错

  • 非 checkable 时 IsChecked() 无意义;SetContent 的内容在扣除 padding 和右侧箭头后的矩形内布局。

TextBox(单行)

cpp
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 不产生撤销步。

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

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

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

cpp
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_; }   // 依赖基类新虚函数

最小示例:

cpp
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

cpp
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 修)。
↑