## Layout properties
```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(); // bubbles to root
void InvalidateLayoutSelf(); // self only (pool/virtual rebind), no bubble
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; // and Vertical
```
- **Stretch weights**: containers (`ColumnBox`/`RowBox`/`GridLayout`) distribute **leftover** space by child weight. `FillWidth/Height` = "weight 1 on that axis". `GetDefault*` is the type default; `Set*` overrides it.
###block_red_start
**Pitfall**
- `SetWidth/SetHeight` is a **fixed size**; `SetFillWidth/Height` **fills the parent axis**; they compose with stretch weights.
- `GetDesiredSize()` is the result of the last `Measure`; may be stale right after changing content.
###block_red_end
- **`Version`**: `SetStretchWeights`/`GetDefault*` existed since the first release; **actual leftover distribution by explicit weights = `v1.17.0`**.
## Drawing / children / clipping / cache
```cpp
virtual void Draw(ID2D1RenderTarget* rt) = 0;
virtual void RefreshChildren(); // update phase (UI thread)
virtual const std::vector<UIElement*>& GetChildren() const; // render phase: pure read
virtual bool UseCache() const; void SetUseCache(bool); // default true
virtual std::optional<D2D1_RECT_F> GetClipRect() const;
void SetClipRect(const std::optional<Rect>&);
void SetBleed(float);
virtual void ReleaseDeviceResources(); // self only
void ReleaseDeviceResourcesRecursive(); // whole subtree
virtual D2D1::Matrix3x2F GetChildRenderTransform(UIElement* child) const;
```
- **Cache**: `UseCache()==true` renders into a per-element offscreen `ID2D1Bitmap1`; rebuilt only when `RequestRepaint()`-marked or size changes. Shadows add `bleed`.
###block_red_start
**Pitfall**
- controls whose content **changes every frame** (animation, live text, spinners) or with **many instances** (thousands) should `SetUseCache(false)`, or VRAM/rebuild cost explodes.
- `GetChildren()` must be pure-read at render time; `RefreshChildren()` must have run first (the window does this in `AdvanceFrame`).
- `ReleaseDeviceResources()` releases **self only**; use the recursive variant for subtrees.
###block_red_end
- **`Version`**: `ReleaseDeviceResourcesRecursive()` = `v1.18.0`; `SetUseCache(false)` now immediately frees an existing bitmap.
## Visibility / enabled / tooltip / cursor
```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
```
- Disabled elements are excluded from hit-test/hover. Tooltips **walk up** to parents.
###block_red_start
**Pitfall**
- `SetCursor` does not call `::SetCursor` directly; it defers to `WM_SETCURSOR` to avoid flicker.
###block_red_end
## Context menu / drag regions / layout participation
```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
**Pitfall**
- `DrawBeforeLayout`/`DrawAfterLayout` are drawn by separate channels — do **not** also place them in the root tree (double draw). The custom title bar is `DrawBeforeLayout` and manages its own position.
###block_red_end
## Event virtuals & element signals
```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(...);
// element signals
ZSignal<> MouseEnter, MouseLeave, Focused, Blurred;
ZSignal<float,float> MouseMove, MouseDown, MouseUp;
ZSignal<WPARAM,LPARAM> KeyDown, KeyUp; ZSignal<wchar_t> Char;
```
###block_red_start
**Pitfall**
- animated controls must make `HasActiveAnimation()` correct, or the frame loop stops and the animation freezes.
- a multi-line editor must return true from `AcceptsTab()` to consume Tab for indent; otherwise Tab moves focus.
###block_red_end
- **`Version`**: `AcceptsTab()` = `v1.18.0`.
## Accessibility (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; // auto e{n}
void SetAccessibleRole(AccessibleRole); virtual AccessibleRole GetAccessibleRole() const;
virtual std::wstring DefaultAccessibleName() const; virtual bool IsAccessibilityIgnored() const;
std::vector<UIElement*> GetAccessibleChildren() const;
// Pattern virtuals (dispatched by role)
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
**Pitfall**
- the role decides which UIA Patterns are exposed (Button/MenuItem→Invoke; Edit/Document→Value; Slider/ProgressBar→RangeValue; toggle state ≥0→Toggle; expand state ≥0→ExpandCollapse). Hidden nodes are not exposed by default.
###block_red_end
- **`Version`**: UIA provider since `v1.17.0`. `v1.26.0` synchronizes the provider cache/context lifetime with COM callback threads, preventing UIA from invoking a released provider.
## Fonts (element-level)
```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;
```
- Resolution chain: **instance override → type default → global**.
###block_red_start
**Pitfall**
- writing `fontOverride_` (contains `std::wstring`) must be serialized with rendering; `StoreFontOverride`/`InvalidateFontCache` take `renderLock_` for mounted elements.
###block_red_end
## Shadow
```cpp
void SetShadow(bool); bool HasShadow() const;
void SetShadowColor(Color); SetShadowBlur(float); SetShadowOffset(float,float); SetShadowCornerRadius(float);
float GetShadowExtent() const;
```
- Shadows only apply to **cached** elements (`Card` enables cache when a shadow is set).
## Debug counters (per element)
`DebugMeasureCount/ArrangeCount/RepaintCount/DrawCount/CacheValid/CacheBytes/MeasureMs/ArrangeMs/DrawMs/AnimationProgress/ResetCounters`, etc. — **`Version`**: `v1.17.0`, used by the debug channel Top-N.Element base
UIElement (layout props, cache, events, accessibility, debug)
Layout properties
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(); // bubbles to root
void InvalidateLayoutSelf(); // self only (pool/virtual rebind), no bubble
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; // and Vertical
- Stretch weights: containers (
ColumnBox/RowBox/GridLayout) distribute leftover space by child weight.FillWidth/Height= "weight 1 on that axis".GetDefault*is the type default;Set*overrides it.
Pitfall
SetWidth/SetHeightis a fixed size;SetFillWidth/Heightfills the parent axis; they compose with stretch weights.GetDesiredSize()is the result of the lastMeasure; may be stale right after changing content.
Version:SetStretchWeights/GetDefault*existed since the first release; actual leftover distribution by explicit weights =v1.17.0.
Drawing / children / clipping / cache
cpp
virtual void Draw(ID2D1RenderTarget* rt) = 0;
virtual void RefreshChildren(); // update phase (UI thread)
virtual const std::vector<UIElement*>& GetChildren() const; // render phase: pure read
virtual bool UseCache() const; void SetUseCache(bool); // default true
virtual std::optional<D2D1_RECT_F> GetClipRect() const;
void SetClipRect(const std::optional<Rect>&);
void SetBleed(float);
virtual void ReleaseDeviceResources(); // self only
void ReleaseDeviceResourcesRecursive(); // whole subtree
virtual D2D1::Matrix3x2F GetChildRenderTransform(UIElement* child) const;
- Cache:
UseCache()==truerenders into a per-element offscreenID2D1Bitmap1; rebuilt only whenRequestRepaint()-marked or size changes. Shadows addbleed.
Pitfall
- controls whose content changes every frame (animation, live text, spinners) or with many instances (thousands) should
SetUseCache(false), or VRAM/rebuild cost explodes. GetChildren()must be pure-read at render time;RefreshChildren()must have run first (the window does this inAdvanceFrame).ReleaseDeviceResources()releases self only; use the recursive variant for subtrees.
Version:ReleaseDeviceResourcesRecursive()=v1.18.0;SetUseCache(false)now immediately frees an existing bitmap.
Visibility / enabled / tooltip / cursor
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
- Disabled elements are excluded from hit-test/hover. Tooltips walk up to parents.
Pitfall
SetCursordoes not call::SetCursordirectly; it defers toWM_SETCURSORto avoid flicker.
Context menu / drag regions / layout participation
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;
Pitfall
DrawBeforeLayout/DrawAfterLayoutare drawn by separate channels — do not also place them in the root tree (double draw). The custom title bar isDrawBeforeLayoutand manages its own position.
Event virtuals & element signals
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(...);
// element signals
ZSignal<> MouseEnter, MouseLeave, Focused, Blurred;
ZSignal<float,float> MouseMove, MouseDown, MouseUp;
ZSignal<WPARAM,LPARAM> KeyDown, KeyUp; ZSignal<wchar_t> Char;
Pitfall
- animated controls must make
HasActiveAnimation()correct, or the frame loop stops and the animation freezes. - a multi-line editor must return true from
AcceptsTab()to consume Tab for indent; otherwise Tab moves focus.
Version:AcceptsTab()=v1.18.0.
Accessibility (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; // auto e{n}
void SetAccessibleRole(AccessibleRole); virtual AccessibleRole GetAccessibleRole() const;
virtual std::wstring DefaultAccessibleName() const; virtual bool IsAccessibilityIgnored() const;
std::vector<UIElement*> GetAccessibleChildren() const;
// Pattern virtuals (dispatched by role)
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();
Pitfall
- the role decides which UIA Patterns are exposed (Button/MenuItem→Invoke; Edit/Document→Value; Slider/ProgressBar→RangeValue; toggle state ≥0→Toggle; expand state ≥0→ExpandCollapse). Hidden nodes are not exposed by default.
Version: UIA provider sincev1.17.0.v1.26.0synchronizes the provider cache/context lifetime with COM callback threads, preventing UIA from invoking a released provider.
Fonts (element-level)
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;
- Resolution chain: instance override → type default → global.
Pitfall
- writing
fontOverride_(containsstd::wstring) must be serialized with rendering;StoreFontOverride/InvalidateFontCachetakerenderLock_for mounted elements.
Shadow
cpp
void SetShadow(bool); bool HasShadow() const;
void SetShadowColor(Color); SetShadowBlur(float); SetShadowOffset(float,float); SetShadowCornerRadius(float);
float GetShadowExtent() const;
- Shadows only apply to cached elements (
Cardenables cache when a shadow is set).
Debug counters (per element)
DebugMeasureCount/ArrangeCount/RepaintCount/DrawCount/CacheValid/CacheBytes/MeasureMs/ArrangeMs/DrawMs/AnimationProgress/ResetCounters, etc. — Version: v1.17.0, used by the debug channel Top-N.