进阶对象操作API介绍——树

针对树控件以及树中的节点，模型管理器提供了Tree和TreeItem两个控件。Tree控件代表整棵树，而TreeItem代表树中的各个节点。由于节点的名称并不唯一，因此将节点名称作为识别属性是不可靠的，因此在操作树节点的时候，大多使用的是TreePath来描述树节点的路径信息。

树状视图控件: Tree

针对Tree控件，大多是以传入TreePath来操作相关节点；而TreeItem控件自身本来代表的就是节点，因此对其操作通常情况下不需要传参数。

类型文件定义

export interface IWinTree extends IWinControl {

    childCount(path: TreePath): Promise<number>;

    treeNodeText(path: TreePath): Promise<string>;
    select(path: TreePath): Promise<IWinTreeItem>;
    expandTo(path: TreePath): Promise<IWinTreeItem>;
    collapseAll(path: TreePath): Promise<void>;
    showHeader(nameOrIndex: string | number): Promise<IWinTreeItem>;

    itemCheckedStatus(path: TreePath): Promise<boolean>;
    setItemCheckedStatus(path: TreePath, Checked: boolean): Promise<void>;

    scrollLeft(): Promise<void>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;

    columnHeaders(): Promise<string[]>;

    treeNodeCount(path: TreePath): Promise<number>; //obsolete, use childCount
    selectTreeNode(path: TreePath): Promise<IWinTreeItem>; //obsolete, use select
    expandTreeNode(path: TreePath): Promise<IWinTreeItem>; //obsolete, use expandTo
    collapseTreeNode(path: TreePath): Promise<void>; //obsolete, use collapseAll
    dblClickTreeNode(path: TreePath): Promise<void>; //obsolete
    
}
export type TreePath = string | (string | number)[];

class WinTree(WinControl):
	def childCount(path: TypedDict) -> int
	def treeNodeText(path: TypedDict) -> str
	def select(path: TypedDict) -> "WinTreeItem"
	def expandTo(path: TypedDict) -> "WinTreeItem"
	def collapseAll(path: Optional[TypedDict]=None) -> None
	def itemCheckedStatus(path: TypedDict) -> bool
	def setItemCheckedStatus(path: TypedDict, Checked: Union[bool, str]) -> None
	def scrollLeft() -> None
	def scrollToTop() -> None
	def scrollToBottom() -> None
	def columnHeaders() -> List[str]
	def showHeader(nameOrndex: Union[str, int]) -> "WinTreeItem"
	def row(rowndex: int) -> "WinTableRow"

TreePath类型

TreePath类型一组描述节点路径和位置的数组，字符串代表节点的名称，数字代表的是节点的索引值。比如一个TreePath数组为[‘b’,‘u’,‘f’]，那么描述的就是f节点。

──b
  └─u
    └─f

对象操作API

下面是针对Tree控件的对象操作API。

select(path): Promise<TreeItem>

选中指定位置的树节点。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<TreeItem>类型，异步的返回目标树节点的TreeItem对象。

childCount(path): Promise<number>

获取目标节点的子节点数量。会展开目标节点，接着统计展开的子节点数量。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<number>类型，异步的统计并返回目标节点的子节点数量。

treeNodeText(path): Promise<string>

获取目标节点的内容。会展开目标节点，接着统计展开的内容。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<string>类型，异步的返回目标节点的内容。

expandTo(path): Promise<TreeItem>

展开到使目标树节点可见的位置。同时也会滚动到目标节点的位置并返回节点对应的对象。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<TreeItem>，目标节点的对象。

collapseAll(path): Promise<void>

折叠路径上所有的节点。与expandTo()方法相反，但是不返回任何对象。

• path: TreePath类型，目标节点的位置。
• 返回值: 不返回任何值的异步方法。

showHeader(nameOrIndex: string | number): Promise<TreeItem>

水平滚动使得目标列可见，并返回该列顶部的TreeItem对象。

• 返回值: Promise<TreeItem>类型，异步的返回目标列头的对象。

itemCheckedStatus(path): Promise<boolean>

获取目标节点被选中的状态。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<boolean>类型，是否被选中。

setItemCheckedStatus(path, Checked: boolean): Promise<void>

设置目标节点的选中状态。

• path: TreePath类型，目标节点的位置。
• Checked: boolean类型，true代表选中，false代表取消选中。
• 返回值: 不返回任何值的异步方法。

columnHeaders(): Promise<string[]>

获取树中所有属性的名称。并以字符串数组的形式返回。

• 返回值: Promise<string>类型，异步的返回所有属性的名称。

scrollLeft(): Promise<void>

滚动到树最左侧。

• 返回值: 不返回任何值的异步方法。

scrollToTop(): Promise<void>

滚动到树的顶部。

• 返回值: 不返回任何值的异步方法。

scrollTo(path): Promise<void>

滚动到目标树节点的位置。如果目标位置还未展开，会一直展开到目标节点使其可见为止，类似expandTo()方法。

• path: TreePath类型，目标节点的位置。
• 返回值: 不返回任何值的异步方法。

scrollToBottom(): Promise<void>

滚动到树的底部。

• 返回值: 不返回任何值的异步方法。

树节点控件: TreeItem

针对树中每个节点控件的自动化对象TreeItem，可以对它展开或折叠，获取它的子节点等等操作。
相比于上一节中所有大部分树节点操作都要传入TreePath参数来定位被操作的树节点，

类型定义文件

类型定义文件如下:

export interface IWinTreeItem extends IWinCheckBox {
    expand(): Promise<void>;
    collapse(): Promise<void>;
    expandState(): Promise<ExpandCollapseState>;
    setSelect(value: boolean): Promise<void>;
    treePath(useName: boolean): Promise<string[] | number[]>;

    //qt only
    rowData(): Promise<string[]>;
    cell(index: number): Promise<IWinTreeCell>;
}

class WinTreeItem(WinCheckBox):
	def expand() -> None
	def collapse() -> None
	def expandState() -> "ExpandCollapseState"
	def select() -> None
	def selected() -> bool
	def setSelect(value: bool) -> None
	def scrollntoView() -> None
	def treePath(useName: Optional[bool]=None) -> Union[List[str], List[int]]
	def next() -> "WinTreeItem"
	def previous() -> "WinTreeItem"
	def rowData() -> List[str]
	def cell(index: int) -> "WinTreeCell"

对象操作API

scrollIntoView(): Promise<void>

滚动到树节点位置。如果树节点所在的位置被折叠，则会展开所有路径上的树节点。

• 返回值: 不返回任何值的异步方法。

select(): Promise<void>

滚动到树节点位置并选中。如果树节点所在的位置被折叠，则会展开所有路径上的树节点。

• 返回值: 不返回任何值的异步方法。

setSelect(select): Promise<void>

当树节点包含复选框（来标识选中状态）时，setSelect()方法可以使得多个列表项同时被选中。最常见的场景是Windows文件管理器中的文件复选框。类似CheckBox控件的toggleCheck()方法。

• select: Boolean类型，true代表选中复选框，false代表取消选中目标复选框。
• 返回值: 不返回任何值的异步方法。

expand(): Promise<void>

展开树节点，如果是无法展开的节点，则不会有任何效果。

• 返回值: 不返回任何值的异步方法。

collapse(): Promise<void>

展开树节点，如果是无法折叠的节点，则不会有任何效果。

• 返回值: 不返回任何值的异步方法。

expandState(): Promise<ExpandCollapseState>

获取当前树节点的展开情况。 返回值: 返回展开状态ExpandCollapseState，有以下几种状态:

export enum ExpandCollapseState {
    collapsed = 0,
    expanded = 1,
    partiallyExpanded = 2,
    leafNode = 3,
    unknown = -1
}

treePath(useName: boolean): Promise<string[] | number[]>

获取当前节点的路径信息。

• useName: boolean类型，是否使用节点名称组成路径。
• 返回值: Promise<string[]>或Promise<number[]>类型，取决与useName这一输入参数。

rowData(): Promise<string[]>

获取树节点的所有属性，并以数组形式返回。

• 返回值: string[]类型，由树节点的属性构成的字符串数组。

cell(index: number): Promise<CellItem>

获取树节点中指定索引属性的内容，并返回CellItem对象。类似表格行对象的cell方法。

• index: number类型，目标属性的索引值。
• 返回值: Promise<CellItem>类型。

  比如针对文件树，某个文件节点的属性可能包含了[文件名, 文件大小, 文件类型, 最后修改时间]这些值。

树节点单元控件: TreeCell

所谓树节点单元，就像表格中的单元格一样，代表某一行某个属性的树节点单元控件，是树中的最小单元控件。比如一个树节点有4个属性：[文件名, 文件大小, 文件类型, 最后修改时间]，那么这个节点底下就有4个树节点单元。

类型文件

export interface IWinTreeCell extends IWinTableItem {
}

class WinTreeCell(WinTableCell):
	...

export interface IWinTableItem {
    value(): Promise<string>;
    select(): Promise<void>;
    set(value: string): Promise<void>;
    row(): Promise<IWinTableRow>;

    selected(): Promise<boolean>;
}

class WinTableCell(WinControl):
	def value() -> str
	def select() -> None
	def set(value: str) -> None
	def row() -> Union[WinTableRow, WinTreeItem]
	def scrollntoView() -> None

对象操作API介绍

select(): Promise<void>

选中树节点单元控件，并且会将目标树节点滚动到可视区域内。

• 返回值: 不返回任何值的异步方法。

set(value): Promise<void>

直接修改树节点单元控件的值，前提是其自身可编辑。

• value: string类型，期望的单元格值。
• 返回值: 不返回任何值的异步方法。

value(): Promise<string>

获取树节点单元的值。

• 返回值: string类型，目标单元格中的值。

row(): Promise<TreeItem>

获取树节点单元所在的树节点对象，也就是它的父对象，返回所在行的TreeItem对象。

• 返回值: Promise<TreeItem>类型，异步的目标树节点对象。

selected(): Promise<boolean>

目标树节点是否被选中。

• 返回值: 异步的返回选中的结果。