Layout properties
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
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
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
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
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
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)
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
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.