Advanced Control Type - Tree

For the tree control and the nodes in the tree, the model manager provides Tree and TreeItem two controls. The Tree control represents the entire tree, and the TreeItem represents individual nodes in the tree. Since the name of a node is not unique, it is unreliable to use the node name as an identification attribute. Therefore, when operating a tree node, TreePath is mostly used to describe the path information of the tree node.

Tree

For the Tree control, most of them pass in TreePath to operate related nodes; while the TreeItem control itself originally represents a node, so its operation usually does not need to pass parameters.

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

The TreePath type is a set of arrays describing the path and location of the node, the string represents the name of the node, and the number represents the index value of the node. For example, if a TreePath array is ['b', 'u', 'f'], then the f node is described.

──b
  └─u
    └─f

Object manipulation API

The following is the object manipulation API for the Tree control.

select(path): Promise<TreeItem>

Select the tree node at the specified position.

  • path: TreePath, The location of the target node.
  • returns: Promise<TreeItem>, Asynchronously returns the TreeItem object of the target tree node

childCount(path): Promise<number>

Get the number of child nodes of the target node. The target node will be expanded, and then the number of expanded child nodes will be counted.

  • path: TreePath, The location of the target node.
  • returns: Promise<number>, Asynchronously count and return the number of child nodes of the target node.

treeNodeText(path): Promise<string>

Get the content of the target node. The target node will be expanded, and then the expanded content will be counted.

  • path: TreePath, The location of the target node.
  • returns: Promise<string>, Asynchronously returns the content of the target node.

expandTo(path): Promise<TreeItem>

Expand to a position where the target tree node is visible. Also scroll to the position of the target node and return the object corresponding to the node.

  • path: TreePath, The location of the target node.
  • returns: Promise<TreeItem>, target node object.

collapseAll(path): Promise<void>

Collapses all nodes on the path. Opposite of the expandTo() method, but returns no object.

  • path: TreePath, The location of the target node.
  • returns: Asynchronous method that returns no value.

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

Scroll horizontally to make the target column visible, and return the TreeItem object at the top of the column.

  • returns: Promise<TreeItem>, Asynchronously returns the object of the target column header.

itemCheckedStatus(path): Promise<boolean>

Get the selected state of the target node.

  • path: TreePath, The location of the target node.
  • returns: Promise<boolean>, is selected.

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

Sets the selected state of the target node.

  • path: TreePath, The location of the target node.
  • Checked: boolean, true means selected, false means unchecked.
  • returns: Asynchronous method that returns no value.

columnHeaders(): Promise<string[]>

Get the names of all properties in the tree. And return as a string array.

  • returns: Promise<string>, Asynchronously returns the names of all properties.

scrollLeft(): Promise<void>

Scroll to the far left of the tree.

  • returns: Asynchronous method that returns no value.

scrollToTop(): Promise<void>

Scroll to the top of the tree.

  • returns: Asynchronous method that returns no value.

scrollTo(path): Promise<void>

Scroll to the position of the target tree node. If the target position has not been expanded, it will be expanded until the target node is visible, similar to the expandTo() method.

  • path: TreePath, The location of the target node.
  • returns: Asynchronous method that returns no value.

scrollToBottom(): Promise<void>

scroll to the bottom of the tree.

  • returns: Asynchronous method that returns no value.

TreeItem

For the automation object TreeItem of each node control in the tree, you can expand or collapse it, get its child nodes, and so on.
Compared to all tree node operations in the previous section, the TreePath parameter is passed in to locate the tree node to be operated.

Typings

The Typings is as follows:

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"

Object manipulation API

scrollIntoView(): Promise<void>

Scroll to the tree node position. If the position where the tree node is located is collapsed, all tree nodes along the path will be expanded.

  • returns: Asynchronous method that returns no value.

select(): Promise<void>

Scroll to the tree node position and select it. If the tree node location is collapsed, all tree nodes along the path will be expanded.

  • returns: Asynchronous method that returns no value.

setSelect(select): Promise<void>

When the tree node contains a check box (to identify the selected state), the setSelect() method can make multiple list items selected at the same time. The most common scenario is the file check box in the Windows file manager. Similar to CheckBox ThetoggleCheck()method of thecontrol.

  • select: Boolean, true means to check the checkbox, false means to uncheck the target checkbox.
  • returns: Asynchronous method that returns no value.

expand(): Promise<void>

Expands a tree node, or has no effect if it is a node that cannot be expanded.

  • returns: Asynchronous method that returns no value.

collapse(): Promise<void>

Expands a tree node, or has no effect if it is a node that cannot be collapsed.

  • returns: Asynchronous method that returns no value.

expandState(): Promise<ExpandCollapseState>

Get the expansion of the current tree node. (UIA only) returns: Return the expanded state ExpandCollapseState, which has the following states:

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

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

Get the path information of the current node.

  • useName: boolean, Whether to use node names to form paths.
  • returns: Promise<string[]> or Promise<number[]>, Depends on the useName input parameter.

rowData(): Promise<string[]>

Get all attributes of tree nodes and return them as an array.

  • returns: string[], An array of strings consisting of the attributes of the tree nodes.

cell(index: number): Promise<CellItem>

Get the content of the specified index attribute in the tree node, and return the CellItem object. Similar to the cell method of the table row object.

  • index: number, The index value of the target attribute.
  • returns: Promise<CellItem>.

    For example, for a file tree, the attributes of a file node may contain [file name, file size, file type, last modification time] these values.

TreeCell

The tree node unit, just like the cell in the table, represents the tree node unit control of a certain attribute of a certain row, and is the smallest unit control in the tree. For example, a tree node has 4 attributes: [file name , file size, file type, last modification time], then there are 4 tree node units under this node.

type file

JavaScript
Python
export interface IWinTreeCell extends IWinTableItem {
}
class WinTreeCell(WinTableCell):
	...
You may wonder why the type file of the TreeCell control does not define any methods, it is because it inherits from TableCell and thus enjoys all its methods, and the type definition of TableCell is as follows:

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

Object Operation API Introduction

select(): Promise<void>

Select the tree node unit control, and the target tree node will be scrolled into the visible area.

  • returns: Asynchronous method that returns no value.

set(value): Promise<void>

Directly modify the value of the tree node cell control, provided that it is itself editable.

  • value: string, expected cell value.
  • returns: Asynchronous method that returns no value.

value(): Promise<string>

Get the value of the tree node cell.

  • returns: string, The value in the target cell.

row(): Promise<TreeItem>

Get the tree node object where the tree node unit is located, that is, its parent object, and return the TreeItem object of the row.

  • returns: Promise<TreeItem>, Asynchronous target tree node object.

selected(): Promise<boolean>

Whether the target tree node is selected.

  • returns: Return selected results asynchronously.

results matching ""

    No results matching ""