## 布局属性
```cpp
virtual Size MeasureOverride(const Size& avail) = 0;
Size Measure(const Size& avail); Size GetDesiredSize() const;
virtual void ArrangeOverride(const Rect&); void Arrange(const Rect&);
Rect GetArrangedRect() const;
void InvalidateLayout(); // 冒泡:向根标脏
void InvalidateLayoutSelf(); // 只标自己(池化/虚拟 rebind 用,不冒泡)
void SetWidth/SetHeight(float); float GetWidth/GetHeight() const;
void SetFillWidth/SetFillHeight(bool); bool GetFillWidth/GetFillHeight() const;
void SetMargin(const Thickness&);
void SetMinWidth/SetMinHeight/SetMaxWidth/SetMaxHeight(float);
void SetMinSize/SetMaxSize(float,float);
void SetStretchWeights(float h, float v);
void SetHorizontalStretchWeight(float); void SetVerticalStretchWeight(float);
virtual float GetDefaultHorizontalStretchWeight() const; // 同理 Vertical
```
- **拉伸权值**:容器(`ColumnBox`/`RowBox`/`GridLayout`)把**剩余空间**按子元素权值分配。`FillWidth/Height` 等价“该轴权值 1”。`GetDefault*` 是类型默认,`Set*` 覆盖它。
###block_red_start
**易错**
- `SetWidth/SetHeight` 是**固定尺寸**;`SetFillWidth/Height` 是**填满父轴**;两者与拉伸权值叠加,行为要分清。
- `GetDesiredSize()` 是上一次 `Measure` 的结果;未测量过/刚改内容时可能是旧值。
###block_red_end
- **`版本`**:`SetStretchWeights`/`GetDefault*` 自初版存在;**`ColumnBox`/`RowBox`/`GridLayout` 真正按显式权值分配剩余空间 = `v1.17.0`**。
## 绘制 / 子元素 / 裁剪 / 缓存
```cpp
virtual void Draw(ID2D1RenderTarget* rt) = 0;
virtual void RefreshChildren(); // 更新阶段(UI 线程)重建可见子列表
virtual const std::vector<UIElement*>& GetChildren() const; // 渲染阶段纯读
virtual bool UseCache() const; void SetUseCache(bool); // 默认 true
virtual std::optional<D2D1_RECT_F> GetClipRect() const;
void SetClipRect(const std::optional<Rect>&);
void SetBleed(float); // 阴影/外发光留边
virtual void ReleaseDeviceResources(); // 只释放自身
void ReleaseDeviceResourcesRecursive(); // 释放整棵子树
virtual D2D1::Matrix3x2F GetChildRenderTransform(UIElement* child) const;
```
- **缓存机制**:`UseCache()==true` 的元素渲染到自身 `ID2D1Bitmap1` 离屏位图;仅当被 `RequestRepaint()` 标记或尺寸变化时重建。出现阴影时自动加 `bleed`。
###block_red_start
**易错**
- **每帧内容在变**(动画、实时文本、旋转)或**实例极多**(上千个)的控件应 `SetUseCache(false)`,否则显存与重建开销爆炸。
- `GetChildren()` 在渲染阶段**必须纯读**;渲染前要保证 `RefreshChildren()` 已调用(窗口在 `AdvanceFrame` 里统一做)。
- `ReleaseDeviceResources()` 只释放自身;释放整棵子树用 `ReleaseDeviceResourcesRecursive()`。
###block_red_end
- **`版本`**:`ReleaseDeviceResourcesRecursive()` = `v1.18.0`(用于隐藏页缓存延迟释放);`SetUseCache(false)` 现在会**立即释放**已有位图。
## 可见性 / 启用 / 提示 / 光标
```cpp
void SetVisible(bool); void SetVisibleNoInvalidate(bool); bool IsVisible() const;
void SetEnabled(bool); bool IsEnabled() const; bool IsEffectivelyEnabled() const; // 沿父链
void SetToolTip(const std::wstring&); virtual std::wstring GetToolTip() const;
void SetCursor(HCURSOR); HCURSOR GetDesiredCursor() const;
void SetPointerCursors(HCURSOR normal, HCURSOR pressed, HCURSOR disabled);
HCURSOR GetPointerCursor(bool pressed) const; virtual HCURSOR GetPointerCursorAt(float x, float y, bool pressed) const;
virtual void OnPointerCancel(); // capture stolen/system cancel
```
- 禁用元素不参与命中/悬停。提示会**向上解析**父级提示(如 Button → Label)。
###block_red_start
**易错**
- `SetCursor` 不直接调 `::SetCursor`,而是延迟到 `WM_SETCURSOR`,避免闪烁。
###block_red_end
## 右键菜单 / 拖动区 / 布局参与
```cpp
void SetContextMenu(std::shared_ptr<Menu>);
void SetContextMenuFactory(std::function<std::shared_ptr<Menu>()>);
std::shared_ptr<Menu> BuildContextMenu() const;
enum class LayoutParticipation { Normal, DrawBeforeLayout, DrawAfterLayout };
void SetLayoutParticipation(LayoutParticipation);
void SetDraggable(bool); void SetDragRegion(const Rect&); void ClearDragRegion();
virtual int NonClientHitTest(float x, float y) const;
```
###block_red_start
**易错**
- `DrawBeforeLayout`/`DrawAfterLayout` 由独立通道绘制,**不要再放进根树**,否则画两遍。自定义标题栏就是 `DrawBeforeLayout` 且自己管位置。
###block_red_end
## 事件虚函数与元素信号
```cpp
virtual UIElement* HitTest(float x, float y);
virtual void OnMouseEnter/Leave/Move/Down/Up(...); virtual bool OnContextMenu(float,float);
virtual void OnKeyDown/Up(WPARAM,LPARAM); virtual void OnChar(wchar_t);
virtual void OnFocus()/OnBlur();
virtual void UpdateAnimation(float dt); virtual bool HasActiveAnimation() const;
virtual bool OnMouseWheel(float dx, float dy);
virtual bool IsTextInput() const; virtual bool AcceptsTab() const; virtual bool IsFocusable() const;
virtual Rect GetImeCandidateRect() const; virtual void SetCompositionText(...);
// 元素内置信号
ZSignal<> MouseEnter, MouseLeave, Focused, Blurred;
ZSignal<float,float> MouseMove, MouseDown, MouseUp;
ZSignal<WPARAM,LPARAM> KeyDown, KeyUp; ZSignal<wchar_t> Char;
```
###block_red_start
**易错**
- 有动画的控件必须让 `HasActiveAnimation()` 正确返回,否则帧循环停了动画就不走。
- 多行编辑器要让 `AcceptsTab()` 返回 true 才会吞掉 Tab 做缩进,否则 Tab 切焦点。
###block_red_end
- **`版本`**:`AcceptsTab()` = `v1.18.0`(配合 `TextEdit`)。
## 无障碍(UIA)— v1.17.0
```cpp
void SetAccessibleName(const std::wstring&); std::wstring GetAccessibleName() const;
void SetAccessibleDescription(const std::wstring&);
void SetAutomationId(const std::wstring&); std::wstring GetAutomationIdOrAuto() const; // 自动 e{n}
void SetAccessibleRole(AccessibleRole); virtual AccessibleRole GetAccessibleRole() const;
virtual std::wstring DefaultAccessibleName() const; virtual bool IsAccessibilityIgnored() const;
std::vector<UIElement*> GetAccessibleChildren() const;
// Pattern 虚函数(按角色分派)
virtual void AccessibilityInvoke();
virtual std::wstring GetAccessibleValue() const; virtual void SetAccessibleValue(const std::wstring&);
virtual bool IsAccessibleReadOnly() const;
virtual int GetAccessibleToggleState() const; virtual void AccessibilityToggle();
virtual int GetAccessibleExpandState() const; virtual void AccessibilityExpand/Collapse();
virtual double GetAccessibleRangeValue() const; virtual void SetAccessibleRangeValue(double);
virtual double GetAccessibleRangeMin/Max/Step() const;
void AccessibilityNotifyFocus/PropertyChanged/StructureChanged();
```
###block_red_start
**易错**
- 角色决定暴露哪些 UIA Pattern:Button/MenuItem→Invoke;Edit/Document→Value;Slider/ProgressBar→RangeValue;toggle 状态 ≥0→Toggle;expand 状态 ≥0→ExpandCollapse。隐藏节点默认不暴露。
###block_red_end
- **`版本`**:整套 = `v1.17.0`(对应 `Window::SetAccessibilityEnabled`,默认开)。`v1.26.0` 起 UIA provider 缓存/context 生命周期与 COM 回调线程同步,避免 provider 已释放后仍被 UIA 调用。
## 字体(元素级)
```cpp
static void SetGlobalFont(const FontSpec&); void SetFont(const FontSpec&);
void SetFontFamily/SetFontSize/SetFontWeight(...); void ClearFont();
virtual std::optional<FontSpec> GetTypeDefaultFont() const; FontSpec GetEffectiveFontSpec() const;
```
- 解析链:**实例覆盖 → 类型默认 → 全局**。
###block_red_start
**易错**
- 写 `fontOverride_`(含 `std::wstring`)必须与渲染串行;已挂载元素的 `StoreFontOverride`/`InvalidateFontCache` 内部会取 `renderLock_`。
###block_red_end
## 阴影
```cpp
void SetShadow(bool); bool HasShadow() const;
void SetShadowColor(Color); SetShadowBlur(float); SetShadowOffset(float,float); SetShadowCornerRadius(float);
float GetShadowExtent() const;
```
- 阴影仅对**开启缓存**的元素生效(`Card` 设阴影会自动开缓存)。
## 调试计数(按元素)
`DebugMeasureCount/ArrangeCount/RepaintCount/DrawCount/CacheValid/CacheBytes/MeasureMs/ArrangeMs/DrawMs/AnimationProgress/ResetCounters` 等。
- **`版本`**:`v1.17.0` 加入的逐元素调试计数,配合调试通道 Top-N 使用。元素基类
UIElement(布局属性、缓存、事件、无障碍、调试)
布局属性
cpp
virtual Size MeasureOverride(const Size& avail) = 0;
Size Measure(const Size& avail); Size GetDesiredSize() const;
virtual void ArrangeOverride(const Rect&); void Arrange(const Rect&);
Rect GetArrangedRect() const;
void InvalidateLayout(); // 冒泡:向根标脏
void InvalidateLayoutSelf(); // 只标自己(池化/虚拟 rebind 用,不冒泡)
void SetWidth/SetHeight(float); float GetWidth/GetHeight() const;
void SetFillWidth/SetFillHeight(bool); bool GetFillWidth/GetFillHeight() const;
void SetMargin(const Thickness&);
void SetMinWidth/SetMinHeight/SetMaxWidth/SetMaxHeight(float);
void SetMinSize/SetMaxSize(float,float);
void SetStretchWeights(float h, float v);
void SetHorizontalStretchWeight(float); void SetVerticalStretchWeight(float);
virtual float GetDefaultHorizontalStretchWeight() const; // 同理 Vertical
- 拉伸权值:容器(
ColumnBox/RowBox/GridLayout)把剩余空间按子元素权值分配。FillWidth/Height等价“该轴权值 1”。GetDefault*是类型默认,Set*覆盖它。
易错
SetWidth/SetHeight是固定尺寸;SetFillWidth/Height是填满父轴;两者与拉伸权值叠加,行为要分清。GetDesiredSize()是上一次Measure的结果;未测量过/刚改内容时可能是旧值。
版本:SetStretchWeights/GetDefault*自初版存在;ColumnBox/RowBox/GridLayout真正按显式权值分配剩余空间 =v1.17.0。
绘制 / 子元素 / 裁剪 / 缓存
cpp
virtual void Draw(ID2D1RenderTarget* rt) = 0;
virtual void RefreshChildren(); // 更新阶段(UI 线程)重建可见子列表
virtual const std::vector<UIElement*>& GetChildren() const; // 渲染阶段纯读
virtual bool UseCache() const; void SetUseCache(bool); // 默认 true
virtual std::optional<D2D1_RECT_F> GetClipRect() const;
void SetClipRect(const std::optional<Rect>&);
void SetBleed(float); // 阴影/外发光留边
virtual void ReleaseDeviceResources(); // 只释放自身
void ReleaseDeviceResourcesRecursive(); // 释放整棵子树
virtual D2D1::Matrix3x2F GetChildRenderTransform(UIElement* child) const;
- 缓存机制:
UseCache()==true的元素渲染到自身ID2D1Bitmap1离屏位图;仅当被RequestRepaint()标记或尺寸变化时重建。出现阴影时自动加bleed。
易错
- 每帧内容在变(动画、实时文本、旋转)或实例极多(上千个)的控件应
SetUseCache(false),否则显存与重建开销爆炸。 GetChildren()在渲染阶段必须纯读;渲染前要保证RefreshChildren()已调用(窗口在AdvanceFrame里统一做)。ReleaseDeviceResources()只释放自身;释放整棵子树用ReleaseDeviceResourcesRecursive()。
版本:ReleaseDeviceResourcesRecursive()=v1.18.0(用于隐藏页缓存延迟释放);SetUseCache(false)现在会立即释放已有位图。
可见性 / 启用 / 提示 / 光标
cpp
void SetVisible(bool); void SetVisibleNoInvalidate(bool); bool IsVisible() const;
void SetEnabled(bool); bool IsEnabled() const; bool IsEffectivelyEnabled() const; // 沿父链
void SetToolTip(const std::wstring&); virtual std::wstring GetToolTip() const;
void SetCursor(HCURSOR); HCURSOR GetDesiredCursor() const;
void SetPointerCursors(HCURSOR normal, HCURSOR pressed, HCURSOR disabled);
HCURSOR GetPointerCursor(bool pressed) const; virtual HCURSOR GetPointerCursorAt(float x, float y, bool pressed) const;
virtual void OnPointerCancel(); // capture stolen/system cancel
- 禁用元素不参与命中/悬停。提示会向上解析父级提示(如 Button → Label)。
易错
SetCursor不直接调::SetCursor,而是延迟到WM_SETCURSOR,避免闪烁。
右键菜单 / 拖动区 / 布局参与
cpp
void SetContextMenu(std::shared_ptr<Menu>);
void SetContextMenuFactory(std::function<std::shared_ptr<Menu>()>);
std::shared_ptr<Menu> BuildContextMenu() const;
enum class LayoutParticipation { Normal, DrawBeforeLayout, DrawAfterLayout };
void SetLayoutParticipation(LayoutParticipation);
void SetDraggable(bool); void SetDragRegion(const Rect&); void ClearDragRegion();
virtual int NonClientHitTest(float x, float y) const;
易错
DrawBeforeLayout/DrawAfterLayout由独立通道绘制,不要再放进根树,否则画两遍。自定义标题栏就是DrawBeforeLayout且自己管位置。
事件虚函数与元素信号
cpp
virtual UIElement* HitTest(float x, float y);
virtual void OnMouseEnter/Leave/Move/Down/Up(...); virtual bool OnContextMenu(float,float);
virtual void OnKeyDown/Up(WPARAM,LPARAM); virtual void OnChar(wchar_t);
virtual void OnFocus()/OnBlur();
virtual void UpdateAnimation(float dt); virtual bool HasActiveAnimation() const;
virtual bool OnMouseWheel(float dx, float dy);
virtual bool IsTextInput() const; virtual bool AcceptsTab() const; virtual bool IsFocusable() const;
virtual Rect GetImeCandidateRect() const; virtual void SetCompositionText(...);
// 元素内置信号
ZSignal<> MouseEnter, MouseLeave, Focused, Blurred;
ZSignal<float,float> MouseMove, MouseDown, MouseUp;
ZSignal<WPARAM,LPARAM> KeyDown, KeyUp; ZSignal<wchar_t> Char;
易错
- 有动画的控件必须让
HasActiveAnimation()正确返回,否则帧循环停了动画就不走。 - 多行编辑器要让
AcceptsTab()返回 true 才会吞掉 Tab 做缩进,否则 Tab 切焦点。
版本:AcceptsTab()=v1.18.0(配合TextEdit)。
无障碍(UIA)— v1.17.0
cpp
void SetAccessibleName(const std::wstring&); std::wstring GetAccessibleName() const;
void SetAccessibleDescription(const std::wstring&);
void SetAutomationId(const std::wstring&); std::wstring GetAutomationIdOrAuto() const; // 自动 e{n}
void SetAccessibleRole(AccessibleRole); virtual AccessibleRole GetAccessibleRole() const;
virtual std::wstring DefaultAccessibleName() const; virtual bool IsAccessibilityIgnored() const;
std::vector<UIElement*> GetAccessibleChildren() const;
// Pattern 虚函数(按角色分派)
virtual void AccessibilityInvoke();
virtual std::wstring GetAccessibleValue() const; virtual void SetAccessibleValue(const std::wstring&);
virtual bool IsAccessibleReadOnly() const;
virtual int GetAccessibleToggleState() const; virtual void AccessibilityToggle();
virtual int GetAccessibleExpandState() const; virtual void AccessibilityExpand/Collapse();
virtual double GetAccessibleRangeValue() const; virtual void SetAccessibleRangeValue(double);
virtual double GetAccessibleRangeMin/Max/Step() const;
void AccessibilityNotifyFocus/PropertyChanged/StructureChanged();
易错
- 角色决定暴露哪些 UIA Pattern:Button/MenuItem→Invoke;Edit/Document→Value;Slider/ProgressBar→RangeValue;toggle 状态 ≥0→Toggle;expand 状态 ≥0→ExpandCollapse。隐藏节点默认不暴露。
版本:整套 =v1.17.0(对应Window::SetAccessibilityEnabled,默认开)。v1.26.0起 UIA provider 缓存/context 生命周期与 COM 回调线程同步,避免 provider 已释放后仍被 UIA 调用。
字体(元素级)
cpp
static void SetGlobalFont(const FontSpec&); void SetFont(const FontSpec&);
void SetFontFamily/SetFontSize/SetFontWeight(...); void ClearFont();
virtual std::optional<FontSpec> GetTypeDefaultFont() const; FontSpec GetEffectiveFontSpec() const;
- 解析链:实例覆盖 → 类型默认 → 全局。
易错
- 写
fontOverride_(含std::wstring)必须与渲染串行;已挂载元素的StoreFontOverride/InvalidateFontCache内部会取renderLock_。
阴影
cpp
void SetShadow(bool); bool HasShadow() const;
void SetShadowColor(Color); SetShadowBlur(float); SetShadowOffset(float,float); SetShadowCornerRadius(float);
float GetShadowExtent() const;
- 阴影仅对开启缓存的元素生效(
Card设阴影会自动开缓存)。
调试计数(按元素)
DebugMeasureCount/ArrangeCount/RepaintCount/DrawCount/CacheValid/CacheBytes/MeasureMs/ArrangeMs/DrawMs/AnimationProgress/ResetCounters 等。
- 版本:v1.17.0 加入的逐元素调试计数,配合调试通道 Top-N 使用。