```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
**易错重灾区**
- 自 **v1.15.0** 起三个视图都是**视口虚拟化 + Label 池化**。
- 存在**两套坐标**:**源行号**(稳定,旧 API/信号用它)与**可见序**(隐藏/筛选/排序之后)。**混用是头号 bug 来源。**
- 虚拟模式下每行没有持久 `Label`;`SetTextFast` 是池 rebind 路径。
###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();
// 虚拟化(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;
// 勾选 / 每项元数据
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
**易错**
- `SortItems()` 会重排 `items_` 并**清空多选/勾选**;`SortView` 只改**可见序**。
- 池化下改行文本走 `SetTextFast`,且容器宽度变化必须重测(`v1.18.0` 修:新增 `poolW_`,宽度变也重测,修省略号错位)。
- `SetFilter` / `SetViewComparator` 把 `std::function` **存在控件里**;按引用捕获外部变量会有悬空风险。虚拟模式下比较器每次都会调 `GetItemText`,大表请先快照文本,避免重复哈希查找。
- `SetItemHeight` 会把高度夹到 ≥1;但 `TableView::SetRowHeight` / `TreeView::SetRowHeight` **没有夹取**,传 0 会让行高计算/命中测试失效——行高必须 > 0。
###block_red_end
- **`版本`**:`BeginUpdate` `v1.9.6`;坐标转换 `v1.10.0`;虚拟化/隐藏/筛选/可见序 `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); // 最小 40
void SetColumnAlignment(int, TextHAlign); void SetRowHeight(float); void SetRowHeightAt(int,float);
void SetColumnVisible(int,bool);
// 虚拟化(v1.15.0,全部按“源行”):SetItemHidden/SetFilter/SetViewComparator/SortView/VisibleCount/SourceOfVisible/VisibleOfSource
// 选中 / 勾选 / 元数据
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
**易错**
- 默认 `Cell` 选择;行/单元格元数据随插入/删除/排序**重映射**;隐藏列不参与命中。
- `SetRowHeight` 不会夹取,行高必须 > 0;传 0 会破坏行高计算/命中测试。按行覆盖的 `SetRowHeightAt` 会夹到 ≥8。
###block_red_end
## TreeNode(普通结构体)
```cpp
enum class CheckState { Unchecked, PartiallyChecked, Checked };
std::vector<std::shared_ptr<Label>> columns; // 每列一个真实 Label;col0 = 节点文本
std::weak_ptr<TreeNode> parent; // 弱引用!用 .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); // 行背景,v1.17.0
```
###block_red_start
**易错**
- `parent` 是 `weak_ptr`;行背景用 **`node->bgColor`** 直接字段(**没有** `SetNodeBackgroundColor`)。
###block_red_end
- **`版本`**:`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:延后 BuildVisibleList(避免 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); // 只影响之后插入的节点
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
**易错**
- `Search` 保留命中节点**及其祖先链**;`SetDefaultExpandDepth` 只影响**未来**插入;`CheckMode::Linked` 自动算 `PartiallyChecked`。
- `GetVisibleNodeAt` 按**最新重建**的可见列表索引,不是节点树顺序。
- `MoveNode` 不能把节点移到自己的后代(返回 `false`,树不变);忽略返回值会误以为移动成功。
###block_red_end
- **`版本`**:`BeginUpdate`/`SetNodeText`/tooltip + 并发 `v1.15.0`;首列省略号修 `v1.16.0`;`Get/SetScrollOffsetY` + `ScrollToNode` + 节点 `bgColor` `v1.17.0`;`SetStretchLastColumn` 末列补宽 `v1.27.2`。
- **v1.27.2 列宽补充**:`SetStretchLastColumn(true)`(默认)在内容总宽小于视口时把剩余宽度补给最后一列,避免单列树中文标签被 40px 最小列宽截成 `...`;`SetStretchLastColumn(false)` 恢复固定列宽行为。数据视图
ListView、TableView、TreeView、TreeNode(虚拟化、隐藏/筛选/可见序)
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)>;
易错重灾区
- 自 v1.15.0 起三个视图都是视口虚拟化 + Label 池化。
- 存在两套坐标:源行号(稳定,旧 API/信号用它)与可见序(隐藏/筛选/排序之后)。混用是头号 bug 来源。
- 虚拟模式下每行没有持久
Label;SetTextFast是池 rebind 路径。
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();
// 虚拟化(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;
// 勾选 / 每项元数据
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;
易错
SortItems()会重排items_并清空多选/勾选;SortView只改可见序。- 池化下改行文本走
SetTextFast,且容器宽度变化必须重测(v1.18.0修:新增poolW_,宽度变也重测,修省略号错位)。 SetFilter/SetViewComparator把std::function存在控件里;按引用捕获外部变量会有悬空风险。虚拟模式下比较器每次都会调GetItemText,大表请先快照文本,避免重复哈希查找。SetItemHeight会把高度夹到 ≥1;但TableView::SetRowHeight/TreeView::SetRowHeight没有夹取,传 0 会让行高计算/命中测试失效——行高必须 > 0。
版本:BeginUpdatev1.9.6;坐标转换v1.10.0;虚拟化/隐藏/筛选/可见序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); // 最小 40
void SetColumnAlignment(int, TextHAlign); void SetRowHeight(float); void SetRowHeightAt(int,float);
void SetColumnVisible(int,bool);
// 虚拟化(v1.15.0,全部按“源行”):SetItemHidden/SetFilter/SetViewComparator/SortView/VisibleCount/SourceOfVisible/VisibleOfSource
// 选中 / 勾选 / 元数据
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);
易错
- 默认
Cell选择;行/单元格元数据随插入/删除/排序重映射;隐藏列不参与命中。 SetRowHeight不会夹取,行高必须 > 0;传 0 会破坏行高计算/命中测试。按行覆盖的SetRowHeightAt会夹到 ≥8。
TreeNode(普通结构体)
cpp
enum class CheckState { Unchecked, PartiallyChecked, Checked };
std::vector<std::shared_ptr<Label>> columns; // 每列一个真实 Label;col0 = 节点文本
std::weak_ptr<TreeNode> parent; // 弱引用!用 .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); // 行背景,v1.17.0
易错
parent是weak_ptr;行背景用node->bgColor直接字段(没有SetNodeBackgroundColor)。
版本:bgColorv1.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:延后 BuildVisibleList(避免 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); // 只影响之后插入的节点
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
易错
Search保留命中节点及其祖先链;SetDefaultExpandDepth只影响未来插入;CheckMode::Linked自动算PartiallyChecked。GetVisibleNodeAt按最新重建的可见列表索引,不是节点树顺序。MoveNode不能把节点移到自己的后代(返回false,树不变);忽略返回值会误以为移动成功。
版本:BeginUpdate/SetNodeText/tooltip + 并发v1.15.0;首列省略号修v1.16.0;Get/SetScrollOffsetY+ScrollToNode+ 节点bgColorv1.17.0;SetStretchLastColumn末列补宽v1.27.2。- v1.27.2 列宽补充:
SetStretchLastColumn(true)(默认)在内容总宽小于视口时把剩余宽度补给最后一列,避免单列树中文标签被 40px 最小列宽截成...;SetStretchLastColumn(false)恢复固定列宽行为。