布局属性
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。
绘制 / 子元素 / 裁剪 / 缓存
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)现在会立即释放已有位图。
可见性 / 启用 / 提示 / 光标
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,避免闪烁。
右键菜单 / 拖动区 / 布局参与
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且自己管位置。
事件虚函数与元素信号
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
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 调用。
字体(元素级)
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_。
阴影
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 使用。