> 本类控件共享的坑:文本布局按 `(文本, 盒, 格式)` 全局缓存;改内部字符串务必走 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`)。基础控件
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直接测量得到的是理想尺寸,不代表父容器夹取后的尺寸。
-
省略号判断与 Arrange 统一使用 0.5 DIP 容差,避免小数字号下可容纳文本被误截断。
-
版本:SetIcon家族v1.13.0;省略自动 tooltipv1.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时主区域只回调,菜单仍可由展开区打开。
易错
- 非 checkable 时
IsChecked()无意义;SetContent的内容在扣除padding和右侧箭头后的矩形内布局。
版本: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);
易错
SetImeEnabled(false)会抑制 IME/屏幕键盘(IsTextInput()返回imeEnabled_)。- 程序化
SetText不产生撤销步。
版本:error/indicator/IMEv1.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); // 记得给尺寸或让它随布局铺满
易错
- 换行宽度变化会重建每一行的 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 修)。
版本:下拉几何/状态v1.12.0;源索引 APIv1.15.0;下拉箭头随展开进度旋转(smoothstep,v1.19.0)。