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

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

Language

API reference / v1.29.1

Data views

ListView, TableView, TreeView, TreeNode (virtualization, hide/filter/visible order)

Download Markdown
struct ViewLabelData { std::wstring text; std::vector<LabelRun> runs; Icon icon = Icon::None; float iconSize = 0; Color iconColor, textColor; };
struct AsyncLabelBatch { int first = 0; std::vector<ViewLabelData> rows; };
struct AsyncCellBatch { int first = 0; int cols = 0; std::vector<std::vector<ViewLabelData>> rows; };
using AsyncLabelFetcher = std::function<AsyncLabelBatch(int, int, AsyncCancelToken, AsyncProgress)>;
using AsyncCellFetcher = std::function<AsyncCellBatch(int, int, AsyncCancelToken, AsyncProgress)>;

Pitfall-heavy chapter

  • Since v1.15.0 all three views are viewport-virtualized + Label-pooled.
  • There are two coordinate systems — source row index (stable; legacy APIs/signals) and visible order (post hide/filter/sort). Mixing them is the #1 bug source.
  • In virtual mode rows have no persistent Label; SetTextFast is the pool rebind path.

ListView

enum class SelectionMode { Single, Extended, Multi, None };
ZSignal<int> SelectionChanged, ItemClicked, ItemDoubleClicked, ItemRightClicked;
ZSignal<std::vector<int>> SelectionChangedMulti;   ZSignal<int,bool> ItemCheckStateChanged;
float ContentToLocalX/Y(float) const;   float LocalToContentX/Y(float) const;   // v1.10.0
void AddItem(const std::wstring&);   void AddItemWidget(std::shared_ptr<Label> rich);   void SetItem(int, const std::wstring&);
std::wstring GetItemText(int) const;   int GetItemCount() const;
void SortItems(std::function<bool(const std::wstring&,const std::wstring&)>);   void ScrollToItem(int);
void BeginUpdate();   void EndUpdate();
// virtualization (v1.15.0)
void SetItemCount(int n);
void SetItemProvider(int n, std::function<std::wstring(int)>);
using AsyncRowFetcher = std::function<AsyncRowBatch(int first, int count, AsyncCancelToken, AsyncProgress)>;
void SetAsyncItemProvider(int n, AsyncRowFetcher);  void NotifyReset(int n = -1);  void NotifyChanged(int first, int count);
using ItemLabelProvider = std::function<void(int, Label&)>;   void SetItemLabelProvider(int n, ItemLabelProvider);
void SetAsyncLabelProvider(int n, AsyncLabelFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetItemHidden(int src, bool=true);   bool IsItemHidden(int src) const;   void ClearHidden();
void SetFilter(std::function<bool(int)>);  void ClearFilter();
void SetViewComparator(std::function<bool(int,int)>);  void SortView(bool ascending=true);  void ClearViewSort();
int  VisibleCount() const;   int SourceOfVisible(int vi) const;   int VisibleOfSource(int src) const;
std::wstring TextAtVisible(int vi) const;   void SetSelectedVisible(int vi);   int GetSelectedVisible() const;
// check / per-item metadata
void SetCheckable(bool);  void SetItemChecked(int src,bool);  std::vector<int> GetCheckedIndices() const;
void SetItemDisabled(int src,bool=true);  void SetItemTextColor(int src,Color);  void SetItemToolTip(int src,const std::wstring&);
void SelectAll();  void ClearSelection();  void ClearMultiSelection();
std::vector<int> GetSelectedIndices() const;  std::vector<bool> GetSelectionStates() const;  bool IsIndexSelected(int) const;

Pitfall

  • SortItems() rearranges items_ and clears multi-selection/checks; SortView only changes visible order.
  • pooled text uses SetTextFast, and the container must re-measure on width change (v1.18.0 adds poolW_ to re-measure on width change, fixing stale ellipsis).
  • SetFilter / SetViewComparator store the std::function inside the control; captures by reference can dangle. In virtual mode the comparator calls GetItemText for every comparison — snapshot text first for large tables to avoid repeated hash lookups.
  • SetItemHeight clamps to ≥1; however TableView::SetRowHeight / TreeView::SetRowHeight do not clamp, so 0 breaks row-height math and hit-testing — row height must be > 0.
  • Version: BeginUpdate v1.9.6; coords v1.10.0; virtualization/hide/filter/visible order v1.15.0.

TableView

enum class SelectionMode { Cell, Row, Column, None };
static long long CellKey(int r,int c); static int CellKeyRow(long long); static int CellKeyCol(long long);
ZSignal<int,int> CellClicked, CellDoubleClicked, CurrentCellChanged, CellRightClicked;
ZSignal<int> HeaderClicked;  ZSignal<std::vector<std::pair<int,int>>> SelectionChangedCells;
void SetRowCount(int);  void SetColumnCount(int);  void BeginUpdate();  void EndUpdate();  void AppendRow/Column(); InsertRow/Column(int); RemoveRow/Column(int);
void SetItem(int row,int col,const std::wstring&);  std::wstring GetItemText(int r,int c) const;
using CellLabelProvider = std::function<void(int,int, Label&)>;   void SetCellLabelProvider(int rows,int cols,CellLabelProvider);
void SetAsyncCellLabelProvider(int rows, int cols, AsyncCellFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetHeaderLabel(int,const std::wstring&);  void SetColumnWidth(int,float);   // min 40
void SetColumnAlignment(int, TextHAlign);   void SetRowHeight(float);  void SetRowHeightAt(int,float);
void SetColumnVisible(int,bool);
// virtualization (v1.15.0; all by source row): SetItemHidden/SetFilter/SetViewComparator/SortView/VisibleCount/SourceOfVisible/VisibleOfSource
// selection / check / metadata
void SetSelectionMode(SelectionMode);  void SetCurrentCell(int,int);  void SelectRow/Column(int);
void SelectAll();  void ClearSelection();  std::vector<std::pair<int,int>> GetSelectedCells() const;  std::vector<int> GetSelectedRows() const;
void SetCheckable(bool);  void SetRowChecked(int,bool);  void SetRowDisabled(int,bool);
void SetCellTextColor(int,int,Color);   void SetCellToolTip(int,int,const std::wstring&);
void SetColumnComparator(int, std::function<bool(const std::wstring&,const std::wstring&)>);  void SortByColumn(int,bool=true);

Pitfall

  • default Cell selection; row/cell metadata remaps with insert/remove/sort; hidden columns don't hit-test.
  • SetRowHeight does not clamp; row height must be > 0, or row-height math and hit-testing break. The per-row SetRowHeightAt clamps to ≥8.

TreeNode (plain struct)

enum class CheckState { Unchecked, PartiallyChecked, Checked };
std::vector<std::shared_ptr<Label>> columns;   // one real Label per column; col0 = node text
std::weak_ptr<TreeNode> parent;                // weak! use .lock()
std::vector<std::shared_ptr<TreeNode>> children;
bool expanded;  int depth;  void* userData;
bool hasChildren;  bool hasChildrenHinted;
std::wstring icon;  bool checkable;  CheckState checkState;  bool selected;  bool enabled;
std::wstring tooltip;   Color bgColor = Color(0,0,0,0);   // row background, v1.17.0

Pitfall

  • parent is weak_ptr; row background is the node->bgColor field (no SetNodeBackgroundColor).
  • Version: bgColor v1.17.0.

TreeView

enum class SelectionMode { Single, Extended, Multi };   enum class CheckMode { Linked, Independent };
ZSignal<std::shared_ptr<TreeNode>> SelectionChanged, NodeClicked, ItemDoubleClicked, ItemRightClicked;
ZSignal<std::shared_ptr<TreeNode>,bool> ExpandChanged;   ZSignal<int> HeaderClicked;
ZSignal<std::shared_ptr<TreeNode>, TreeNode::CheckState> ItemCheckStateChanged;
void SetColumnCount(int);  void SetHeaderLabels(const std::vector<std::wstring>&);  void SetColumnWidth(int,float);
using NodeLabelProvider = std::function<void(const std::shared_ptr<TreeNode>&, int, Label&)>;
void SetNodeLabelProvider(NodeLabelProvider);   void RefreshNodeLabels();
void SetAsyncNodeLabelProvider(AsyncCellFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetStretchLastColumn(bool);  bool GetStretchLastColumn() const;   // v1.27.2
std::shared_ptr<TreeNode> AddRoot(const std::wstring&);   std::shared_ptr<TreeNode> AddChild(parent, const std::wstring&);
void RemoveNode(node);  void RemoveChildren(node);  void MoveNode(node, newParent, int index);  void Clear();
void BeginUpdate();  void EndUpdate();                       // v1.15.0: defer BuildVisibleList (avoids O(N^2))
void SetLazyLoader(std::function<void(std::shared_ptr<TreeNode>)>);   // called before expanding a node
void SetNodeText(node,int col,const std::wstring&);   void SetNodeTooltip(node, ...);   void SetNodeIcon(node, ...);   void SetNodeHasChildren(node, bool);
void ExpandNode(node,bool);  void ExpandAll();  void CollapseAll();  void ExpandToDepth(int);
void SetDefaultExpandDepth(int);                             // affects only future inserts
void SetFilter(std::function<bool(const std::shared_ptr<TreeNode>&)>);   void Search(const std::wstring&);
void SetSelectionMode(SelectionMode);  void SetSelectedNode(node);  std::vector<std::shared_ptr<TreeNode>> GetSelectedNodes() const;
void SetCheckable(bool enable);  void SetCheckableShallow(bool enable);  void SetCheckMode(CheckMode);
void SetNodeCheckable(node, bool);   void SetNodeCheckableRecursive(node, bool);
void SetNodeEnabled(node, bool);     void SetNodeEnabledRecursive(node, bool);
void SetNodeCheckState(node, TreeNode::CheckState);
void SetNodeCheckStateFull(node, TreeNode::CheckState, bool updateChildren, bool updateParent);
float GetScrollOffsetY() const;   void SetScrollOffsetY(float);   void ScrollToNode(node);   // v1.17.0

Pitfall

  • Search keeps a hit node plus its ancestor chain; SetDefaultExpandDepth affects only future inserts; CheckMode::Linked auto-computes PartiallyChecked.
  • GetVisibleNodeAt indexes the visible list rebuilt after the latest update, not the source/tree order.
  • MoveNode refuses to move a node into its own descendant (returns false and leaves the tree unchanged); ignoring the return value makes the move look successful.
  • Version: BeginUpdate/SetNodeText/tooltip + concurrency v1.15.0; first-column ellipsis fix v1.16.0; Get/SetScrollOffsetY + ScrollToNode + bgColor v1.17.0; SetStretchLastColumn last-column fill v1.27.2.
  • v1.27.2 column fill: SetStretchLastColumn(true) (default) gives the remaining width to the last column when total content is narrower than the viewport, preventing single-column Chinese labels from being truncated to ... by the 40px minimum width; SetStretchLastColumn(false) restores fixed widths.
View sourcedocs/src/API.en.md