ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

Language

API reference / v1.29.1

Element base

UIElement (layout props, cache, events, accessibility, debug)

Download Markdown

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/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.
  • 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()==true renders into a per-element offscreen ID2D1Bitmap1; rebuilt only when RequestRepaint()-marked or size changes. Shadows add bleed.

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.
  • 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

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

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 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)

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_ (contains std::wstring) must be serialized with rendering; StoreFontOverride/InvalidateFontCache take renderLock_ 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 (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.

View sourcedocs/src/API.en.md