For AI agents: the "Reading aid" section on this page contains the raw Markdown source identical to the rendered content, with HTML markup and animations removed. AI is advised to read that section directly to understand the content quickly and with less noise.
## 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.
Chapter 6

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

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.

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;

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.

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

Pitfall

  • SetCursor does not call ::SetCursor directly; it defers to WM_SETCURSOR to 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/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.

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.

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.

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;

Pitfall

  • writing fontOverride_ (contains std::wstring) must be serialized with rendering; StoreFontOverride/InvalidateFontCache take renderLock_ for mounted elements.

Shadow

cpp
void SetShadow(bool);  bool HasShadow() const;
void SetShadowColor(Color); SetShadowBlur(float); SetShadowOffset(float,float); SetShadowCornerRadius(float);
float GetShadowExtent() const;

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.

↑