For AI agents: the "Reading aid" section on this page contains the raw Markdown source identical to the rendered content, with HTML markup and animations removed. AI is advised to read that section directly to understand the content quickly and with less noise.
```cpp
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)>;
```


###block_red_start
**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.
###block_red_end

## ListView

```cpp
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;
```

###block_red_start
**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.
###block_red_end

- **`Version`**: `BeginUpdate` `v1.9.6`; coords `v1.10.0`; virtualization/hide/filter/visible order `v1.15.0`.

## TableView

```cpp
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);
```

###block_red_start
**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.
###block_red_end

## TreeNode (plain struct)

```cpp
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
```

###block_red_start
**Pitfall**

- `parent` is `weak_ptr`; row background is the **`node->bgColor`** field (**no** `SetNodeBackgroundColor`).
###block_red_end

- **`Version`**: `bgColor` `v1.17.0`.

## TreeView

```cpp
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
```

###block_red_start
**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.
###block_red_end

- **`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.
Chapter 14

Data views

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

cpp
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

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

TableView

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

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

TreeView

cpp
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.
↑