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

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

树状视图控件: Tree

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

JavaScript
Python
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参数来定位被操作的树节点,

类型定义文件

类型定义文件如下:

JavaScript
Python
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,有以下几种状态:

JavaScript
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个树节点单元

类型文件

JavaScript
Python
export interface IWinTreeCell extends IWinTableItem {
}
class WinTreeCell(WinTableCell):
	...
你可能会奇怪为什么TreeCell控件的类型文件没有定义任何方法,这是因为它继承自TableCell因此享有它的所有方法,而TableCell的类型定义如下:

JavaScript
Python
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>

目标树节点是否被选中。

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

results matching ""

    No results matching ""