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;SetTextFastis 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()rearrangesitems_and clears multi-selection/checks;SortViewonly changes visible order.- pooled text uses
SetTextFast, and the container must re-measure on width change (v1.18.0addspoolW_to re-measure on width change, fixing stale ellipsis).SetFilter/SetViewComparatorstore thestd::functioninside the control; captures by reference can dangle. In virtual mode the comparator callsGetItemTextfor every comparison — snapshot text first for large tables to avoid repeated hash lookups.SetItemHeightclamps to ≥1; howeverTableView::SetRowHeight/TreeView::SetRowHeightdo not clamp, so 0 breaks row-height math and hit-testing — row height must be > 0.
Version:BeginUpdatev1.9.6; coordsv1.10.0; virtualization/hide/filter/visible orderv1.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
Cellselection; row/cell metadata remaps with insert/remove/sort; hidden columns don't hit-test.SetRowHeightdoes not clamp; row height must be > 0, or row-height math and hit-testing break. The per-rowSetRowHeightAtclamps 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
parentisweak_ptr; row background is thenode->bgColorfield (noSetNodeBackgroundColor).
Version:bgColorv1.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
Searchkeeps a hit node plus its ancestor chain;SetDefaultExpandDepthaffects only future inserts;CheckMode::Linkedauto-computesPartiallyChecked.GetVisibleNodeAtindexes the visible list rebuilt after the latest update, not the source/tree order.MoveNoderefuses to move a node into its own descendant (returnsfalseand leaves the tree unchanged); ignoring the return value makes the move look successful.
Version:BeginUpdate/SetNodeText/tooltip + concurrencyv1.15.0; first-column ellipsis fixv1.16.0;Get/SetScrollOffsetY+ScrollToNode+bgColorv1.17.0;SetStretchLastColumnlast-column fillv1.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.