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

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

Language

API reference / v1.29.1

Containers & scrolling

ScrollViewer, ScrollBar, SplitView, Drawer, TabView

Download Markdown

ScrollViewer

enum class ScrollBarVisibility { Auto, Always, Hidden };
ZSignal<float,float> ScrollChanged;
void SetContent(std::shared_ptr<UIElement>);
void SetVertical/HorizontalScrollEnabled(bool);
void SetVertical/HorizontalScrollBarVisibility(ScrollBarVisibility);
void SetScrollBarWidth(float);  void SetScrollWheelStep(float);  void SetAnimationSpeed(float);
void ScrollTo(float x,float y,bool animated=true);  void ScrollBy(...);
float GetScrollOffsetX/Y() const;

Pitfall

  • Hidden still allows programmatic/wheel scrolling.
  • Version: v1.18.0 — ScrollViewer::UseCache()==false.

ScrollBar (standalone, reusable)

std::function<void(float value, bool animate)> ValueChanged;
explicit ScrollBar(bool vertical);
void SetRange(float value, float maxValue, float viewportSize);   // host pushes each frame
void SetBarWidth(float);  void SetMinLength(float);  void SetHitExtra(float);
void SetColors(D2D1_COLOR_F thumb, D2D1_COLOR_F hoverThumb, D2D1_COLOR_F track);
void SetIdleDelay(float);  void SetAutoShrink(bool);  void MarkActive();
inline static float ShrunkWidthRatio;   // default 0.30
  • Drag → animate=false; track click → animate=true. Hover expands, idle shrinks; hosts reserve gutter space via ShrunkWidthRatio.

Pitfall

  • ValueChanged is a std::function (not ZSignal), signature (float, bool).
  • the idle-shrink countdown is not counted as an active animation — otherwise it put the whole window into animation mode and stopped data repaints from landing. Cost: idle shrink is lazy (triggered by the next frame).
  • Version: reusable since v1.11.0; ShrunkWidthRatio v1.13.0.

SplitView

enum class Orientation { Vertical, Horizontal };   // Vertical = left/right panes + vertical splitter
ZSignal<float> SplitChanged;
void SetFirst/SetSecond(std::shared_ptr<UIElement>);
void SetSplitRatio(float);  void SetSplitterWidth(float);  void SetMinFirst/MinSecond(float);
void SetInsufficientSpaceDefaultSide(int);  int GetInsufficientSpaceDefaultSide() const;
void SetAutoCollapseOnInsufficientSpace(bool);  bool GetAutoCollapseOnInsufficientSpace() const;
ZSignal<int> CollapsedChanged;   // 0=expanded 1=first pane 2=second pane
void SetCollapseEnabled(bool);   bool IsCollapseEnabled() const;   void SetCollapseThreshold(float);
void CollapseFirst/CollapseSecond();   void Expand();   bool IsFirstCollapsed/IsSecondCollapsed() const;
void SetExpandButtonColors(Color,Color,Color);   void SetExpandButtonSize(float w,float h);
void SwitchToFirst/SwitchToSecond(bool animate = true);  void SwitchToPane(int side, bool animate = true);
void SetSwitchAnimationDuration(float);  void SetSwitchAnimationEasing(Easing);
bool IsSwitching() const;  float GetSwitchProgress() const;  int GetActivePane() const;
ZSignal<int> ActivePaneChanged;   // 1=first, 2=second
bool UseCache() const override { return false; }
  • Collapse (v1.21.0): drag the splitter to within CollapseThreshold (default 28px) of one side's edge → a translucent accent overlay plus an arrow pointing in the collapse direction fades in ON TOP OF that pane's content (the content is not changed yet); the pane actually collapses on mouse release (its size eases from the current value to 0). Once collapsed, a small button appears at that edge (rounded light grey + arrow pointing in the expand direction + hover easing); clicking it eases that side from 0 to its minimum limit (SetMinFirst/MinSecond, or back to the pre-collapse ratio if no minimum is set). The whole feature can be turned off with SetCollapseEnabled(false).
  • Full-pane switch (v1.28.0): SwitchToFirst/Second slides from one fully expanded pane to the other (PageHost-style) even when both panes cannot fit at once; duration/easing are configurable, and the collapse state is committed with ActivePaneChanged when the transition finishes.
  • When the available space cannot fit minFirst + minSecond, the expand button stays visible but is greyed out and non-interactive; it becomes enabled again when enough space returns.

Pitfall

  • Orientation naming is counter-intuitive (Vertical = vertical splitter, horizontal arrangement).
  • the overlay is an internal Overlay child element placed last (the framework draws children in order), which is why it naturally ends up above both panes; do not try to paint such decorations from SplitView::Draw (the children would cover them).
  • Version: v1.12.0; NaN/Inf guard v1.14.0; collapse + expand button v1.21.0.

Drawer (v1.25.0)

enum class DrawerSide { Left, Right, Top, Bottom };
enum class DrawerMode { Overlay, Push, Permanent };
ZSignal<bool> OpenChanged;  ZSignal<> Opened, Closed, ScrimClicked;
void SetContent/SetPanel(std::shared_ptr<UIElement>);
void SetSide(DrawerSide);  void SetMode(DrawerMode);  void SetPanelSize(float);
void SetPanelPadding(const Thickness&);  void SetPanelCornerRadius(float);
void SetPanelBackgroundColor(Color);  void SetPanelBorderColor(Color);
void SetPanelShadow(bool);  void SetPanelShadowColor(Color);
void SetContentBorder(bool);  void SetContentBorderColor(Color);  void SetContentBorderCornerRadius(float);
void SetScrimColor(Color);  void SetScrimOpacity(float);  void SetModal(bool);
void SetDismissOnScrimClick(bool);  void SetDismissOnEscape(bool);
void SetFocusOnOpen(std::shared_ptr<UIElement>);
void SetAnimationDuration(float);  void SetAnimationEasing(Easing);
void Open/Close/Toggle();  bool IsOpen/IsAnimating() const;  float GetOpenProgress() const;

Overlay

Rounded scrim over content; dismiss with outside click or Esc. Good for navigation and filters.

Push

Content yields while the panel is open and participates in layout; good for list + detail side by side.

Permanent

Always open, no animation/scrim, Close ignored; good for persistent navigation or settings.

Recommended

Use Drawer as the root layout or a GridLayout cell; Overlay for temporary content, Push when content should shrink, Permanent for long-lived navigation. Put panel content in SetPanel and the main content in SetContent.

Pitfall

  • SetContent is the main content (covered/yielded by the drawer); SetPanel is the drawer panel. Putting panel content in SetContent skips the panel background, padding, rounded corners and shadow.
  • SetPanelSize is the outer panel size; the default 16 px padding is subtracted from the panel content (e.g. outer 200 leaves 168 for content). Increase SetPanelSize or reduce SetPanelPadding when the panel needs more room.
  • Drawer is a layout control and covers only its own arranged rect (the root layout or one GridLayout cell), not the window title bar/menu bar. Put it at the outermost level of the area you want to dim.
  • Open() sets the target state and raises OpenChanged immediately; Opened/Closed fire only after the animation ends. IsOpen() returns the target state, not the current progress; use IsAnimating() / GetOpenProgress() during a transition.
  • Permanent forces open, progress 1, no animation/scrim; Close() / SetOpen(false) are ignored. Switching back to Overlay/Push does not auto-close; call Close() explicitly.
  • the scrim exists only in Overlay; SetDismissOnScrimClick / ScrimClicked work only with SetModal(true) and progress > 0. With SetModal(false), clicks reach the content and ScrimClicked never fires.
  • SetScrimOpacity(0) makes the scrim visually transparent but keeps modal hit-testing (clicks are still blocked); use SetModal(false) for click-through.
  • SetContentBorder is drawn only in Overlay; Push/Permanent have no content border. The inner layers of SetPanelShadow are covered by the opaque panel background; only the outer shadow remains, and the border is painted last.
  • Esc handling and SetFocusOnOpen require the Drawer to be attached to a Window; before attach, no Esc handler is registered and focus is not applied.
  • Version: v1.25.0.

TabView

struct Tab { std::shared_ptr<Label> label; std::shared_ptr<Page> page; bool closable; ... };
ZSignal<int> SelectionChanged;   ZSignal<int> TabCloseRequested;
int  AddTab(const std::wstring&, std::shared_ptr<UIElement> content=nullptr, bool closable=false, int id=-1);
int  AddTab(std::shared_ptr<Label>, ...);  int FindTabById(int) const;  int GetTabId(int) const;  bool RemoveTabById(int);
void InsertTab(int, ...);  void RemoveTab(int);  void ClearTabs();
void SetTabTitle(int, const std::wstring&);  void SetTabLabel(int, std::shared_ptr<Label>);  void SetTabContent(int, ...);
void SetSelectedIndex(int);  int GetSelectedIndex() const;
void SetTransitionDirection(PageHost::TransitionDirection);  void SetAutoTransitionDirection(bool);

Pitfall

  • content is hosted by an internal PageHost; AddTab auto-selects the first tab and raises SelectionChanged.
  • SetSelectedIndex/switching is asynchronous (settles after the transition); GetSelectedContent()/index may be stale during it.
  • Version: v1.11.0; Label-based titles + SetTabLabel v1.13.0; locking v1.15.0.
View sourcedocs/src/API.en.md