Tree Widget API

For the tree control and the nodes in the tree, the model manager provides two controls, Tree and TreeItem. The Tree control represents the entire tree, and the TreeItem represents each node in the tree. Since the name of the node is not unique, it is unreliable to use the node name as the identification attribute. The model manager provides an identification attribute describing the location of the node-itemPath.

Corresponding walkthroughs are also provided for the list controls-Walkthrough: Operating Tree in Qt Applications, which can greatly deepen the understanding of the API.

Tree view control: Tree

For the Tree control, most of the related nodes are operated by passing in the itemPath; and the TreeItem control itself originally represents the node, so it is usually not necessary to pass parameters for its operation.

JavaScript
Python
export interface IQTree extends IQtControl {
    getItem(itemPath: ItemPath): IQTreeItem;
    findItem(text: string): Promise<IQTreeItem | null>;
    scrollTo(itemPath: ItemPath): Promise<void>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;
    collapseAll(itemPath: ItemPath): Promise<void>;

    children(): Promise<IQTreeItem[]>;
    childCount(): Promise<number>;
    rowData(itemPath: ItemPath): Promise<string[]>;
    columnCount(): Promise<number>;
    columnHeaders(): Promise<string[]>;
}
export type ItemPath = (number | [number, number])[];
class QTree(QtControl):
	def columnHeaders() -> List[str]
	def collapseAll(itemPath: TypedDict) -> None
	def getItem(itemPath: TypedDict) -> "QTreeItem"
	def findItem(text: str, options: Optional[FindItemOptional]=None) -> "QTreeItem"
	def rowData(itemPath: TypedDict) -> List[str]
	def columnData(nameOrIndex: Union[str, int]) -> List[str]
	def select(itemPath: TypedDict) -> "QTreeItem"
	def childCount() -> int
	def children() -> "List[QTreeItem]"
	def columnCount() -> int
	def scrollToTop() -> None
	def scrollTo(itemPath: TypedDict) -> "QTreeItem"
	def scrollToBottom() -> None

Object manipulation API

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

getItem(itemPath): IQTreeItem

Get the automation object corresponding to the tree node at the specified itemPath location.

  • itemPath: ItemPath type, representing the location of the node.
  • Return value: IQTreeItem type, which is the automation object of the ListItem control. Note that this is a synchronous method and does not require the await keyword, nor will it match the controls in the application. Matches are only performed when an asynchronous method on the object is executed.

findItem(text: string): Promise<IQTreeItem | null>

Search the target tree node based on the name in the tree, return the automation object of the target tree node, or return null if it is not found. Since it needs to search the tree in the application in real time, it is an asynchronous method.

  • text: string type, the content or text of the desired target tree node;
  • Return value: Promise<IQTreeItem> or Promise<null> type, asynchronously search the target tree node in the application, and return null if it is not found.

    findItem() search strategy: The findItem() method adopts a "breadth first" search strategy, that is, first search for the tree node that satisfies the condition (ie the tree node that meets the name) in the current level; if none Satisfaction will lead to the next level. If it is an unexpanded node, it will usually not be searched, so if you need to get a deeper tree node, the best way is to call the findItem() method layer by layer to ensure all The nodes can be searched correctly. For this, the tree node also provides the findItem() method.

select(itemPath): Promise<void>

Select the tree node at the specified location.

  • index: ItemPath type, the location of the target node.
  • Return value: Asynchronous method that does not return any value.

scrollToTop(): Promise<void>

Scroll to the top of the tree.

  • Return value: Asynchronous method that does not return any value.

scrollTo(itemPath): Promise<void>

Scroll to the location of the target tree node. If the target location has not been expanded, it will be expanded until the target node is made visible.

  • itemPath: ItemPath type, the location of the target node.
  • Return value: Asynchronous method that does not return any value.

scrollToBottom(): Promise<void>

Scroll to the top of the tree.

  • Return value: Asynchronous method that does not return any value.

collapseAll(itemPath: ItemPath): Promise<void>

Collapse all tree nodes on the specified path.

  • itemPath: ItemPath type, the location of the target node.
  • Return value: Asynchronous method that does not return any value.

children(): Promise<IQTreeItem[]>

Asynchronously get all the immediate child nodes of the current tree and return them in the form of an array.

  • Return value: an array composed of automation objects of type TreeItem. And it is an asynchronous method, which requires the use of the await keyword.

childCount(): Promise<number>

Asynchronously get the number of all the immediate child nodes of the current tree, and return the number.

  • Return value: number type, the number of immediate child nodes, which can be understood as the length of the array returned by the children() method. And it is an asynchronous method, which requires the use of the await keyword.

rowData(itemPath: ItemPath): Promise<string[]>

Get all the attributes of the target tree node and return it as an array.

  • itemPath: ItemPath type, the location of the target node.
  • Return value: string[] type, a string array composed of tree node attributes.

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

columnHeaders(): Promise<string[]>

Get the attribute name of the tree, that is, the column header content of each column in the tree, and return it in the form of a string array.

  • Return value: string[] type, a string array composed of attribute names.

columnCount(): Promise<number>

Get the number of attributes of the tree, that is, how many columns there are in the tree. It is numerically equal to the length of the array returned by the columnHeaders() method.

  • Return value number type, the number of attributes.

Tree node control: 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 itemPath parameter must be passed in to locate the tree node being manipulated.

Type definition file

The type definition file is as follows:

JavaScript
Python
export interface IQTreeItem extends IQtControl {
    select(): Promise<void>;
    getItem(itemPath: ItemPath): IQTreeItem;
    findItem(text: string): Promise<IQTreeItem | null>;  
    expand(): Promise<void>;
    collapse(): Promise<void>;
    scrollIntoView(): Promise<void>;
    set(value: string): Promise<void>;
    toggleCheck(checkState: boolean | 'partial'): Promise<void>;
    data(roleId?: number): Promise<string|int>;
    
    exists(seconds: number): Promise<boolean>;
    value(): Promise<string>;
    rowData(): Promise<string[]>;
    expandable(): Promise<boolean>;
    editable(): Promise<boolean>;
    selected(): Promise<boolean>;
    expanded(): Promise<boolean>;
    childCount(): Promise<number>;
    children(): Promise<IQTreeItem[]>;
    rowIndex(): Promise<number>;
    columnIndex(): Promise<number>;
    itemPath(): Promise<ItemPath>;
    checkState(): Promise<boolean | 'partial'>;
}
class QTreeItem(QItemViewItem):
	def expand() -> None
	def collapse() -> None
	def exists(seconds: int) -> bool
	def value() -> str
	def rowData() -> List[str]
	def scrollIntoView() -> None
	def set(value: str) -> None
	def data(roleId: int = None) -> Union[str, int]
	def select() -> None
	def expandable() -> bool
	def expanded() -> bool
	def childCount() -> int
	def children() -> List[QTreeItem]
	def rowIndex() -> int
	def columnIndex() -> int
	def itemPath() -> TypedDict
	def getItem(itemPath: TypedDict) -> "QTreeItem"
	def findItem(text: str, options: Optional[FindItemOptional]=None) -> "QTreeItem"
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None

Object manipulation API

value(): Promise<string>

Get the name of the tree node.

  • Return value: Promise<string> type, representing the name of the tree node. You need to use the await keyword to retrieve the results.

Calibration gets the control value of the temp control of the tree node.

JavaScript
Python
let value = await model.getTreeItem("temp").value();
assert.equal(value,'temp');
value = model.getTreeItem("temp").value()
assert value == 'temp'

getItem(itemPath): IQTreeItem

Gets the automation object corresponding to the tree node at the specified itemPath location, starting at the current node. Compared to the getItem() method on the Tree object, which needs to pass in the full itemPath to index the target node, the getItem() method on the TreeItem object automatically splices the incoming itemPath with the itemPath attribute of the current tree node before indexing it to achieve a similar relative path effect.

  • itemPath: ItemPath type, representing the position of the target node relative to the current node.
  • Return value: IQTreeItem type, the automation object for the TreeItem control. Note that this is a synchronous method that does not require the await keyword and does not match controls in the application. It will only match if an asynchronous method on the object is executed.

Assuming that TreeItem object A has an itemPath property of [0,1], the script call to getTreeItem("A").getItem([2,3]) will stitch the itemPath of the two, which is equivalent to getTree("Tree").getItem([0,1 ,2,3]).

findItem(text: string): Promise<IQTreeItem | null>

Search for the target tree node based on the name in the current tree node, return the automation object of the target tree node, or return null if it is not found. Since it needs to search the tree in the application in real time, it is an asynchronous method.

  • text: string type, expect the content or text of the target tree node;
  • Return value: Promise<IQTreeItem> or Promise<null> type, asynchronously search the target tree node in the application, and return null if it is not found.

    Expand the current node before searching to avoid the situation that the child node cannot be found.

scrollIntoView(): Promise<void>

Scroll to the tree node position. If the location of the tree node is collapsed, all tree nodes on the path will be expanded.

  • Return value: Asynchronous method that does not return any value.

select(): Promise<void>

Select the tree node. If the node is not in the visible range, it will automatically scroll to the location of the item.

This method will automatically execute the scrollIntoView() method to expand and scroll to the target node when the node is not in the visible range.

  • Return value: Asynchronous method that does not return any value.

expand(): Promise<void>

Expanding the tree node, if it is a node that cannot be expanded, there will be no effect.

  • Return value: Asynchronous method that does not return any value.

collapse(): Promise<void>

Expand the tree node, if it is a node that cannot be collapsed, there will be no effect.

  • Return value: Asynchronous method that does not return any value.

set(value: string): Promise<void>

Modify the value of the tree node. If it is a node that cannot be edited, there will be no results.

  • Return value: Asynchronous method that does not return any value.

toggleCheck(checkState: boolean | 'partial'): Promise<void>

Checks or unchecks the checkboxes in the tree nodes.

  • checkState: boolean type or partial string. true means checked, false means unchecked, and "partial" means partially checked (common for checkboxes with sub-options).
  • Return Value: Asynchronous method that does not return any value.

data(roleId?:number): Promise<string|int>

Pass in role to return the tree node data content, do not pass in role=DisplayRole by default.

  • Return value: string type or int type data content.

The role value can be referred toenum Qt::ItemDataRole

Gets the text data content of the tree node:

JavaScript
Python
const { RunSettings } = require("leanpro.common");
const { QtAuto } = require("leanpro.qt");
(async () => {
  await RunSettings.set({slowMo: 1000, reportSteps: true});

  let modelQt = QtAuto.loadModel(__dirname + "/recording_1.tmodel");
  await QtAuto.launchQtProcessAsync("C:\\Program Files\\LeanPro\\CukeTest\\bin/dirview.exe");
  const role = 0;

  console.log(await modelQt.getTreeItem("C:").data(role).catch((e) => { }));
  console.log(await modelQt.getTreeItem("TreeItem").data(role));
  console.log(await modelQt.getTreeItem("Drive").data(role));
  console.log(await modelQt.getTreeItem("2023/7/24_18:40:46").data(role));
})();
import os
from leanproAuto import RunSettings, QtAuto

RunSettings.set({"slowMo": 1000, "reportSteps": True})

modelQt = QtAuto.loadModel(os.path.dirname(os.path.realpath(__file__)) + "/recording_4.tmodel")

QtAuto.launchQtProcessAsync("C:\\Program Files\\LeanPro\\CukeTest\\bin\\dirview.exe")
role = 0

modelQt.getApplication("dirview").exists(10)

print(modelQt.getTreeItem("C:").data(role))
print(modelQt.getTreeItem("TreeItem").data(role))
print(modelQt.getTreeItem("Drive").data(role))
print(modelQt.getTreeItem("2023/7/24_18:40:46").data(role))

exists(seconds: number): Promise<boolean>

Whether the current tree node is in the expanded tree, the input parameter is the waiting time.

  • seconds: number type, waiting time, if it is still false after the waiting time, it will return.
  • Return value: boolean type, whether it exists.

children(): Promise<IQTreeItem[]>

Asynchronously get all the immediate child nodes of the current tree node and return them in the form of an array.

  • Return value: an array composed of automation objects of type TreeItem. And it is an asynchronous method, which requires the use of the await keyword.

rowIndex(): Promise<number>

Gets the row index position in the immediate parent of the current tree node.

  • Return value: number type, the row index position in the cell.

columnIndex(): Promise<number>

Gets the column index position in the immediate parent of the current tree node.

  • Return value: number type, the position of the column index in the cell.

childCount(): Promise<number>

Asynchronously get the number of all immediate child nodes of the current tree node, and return the number.

  • Return value: number type, the number of immediate child nodes, which can be understood as the length of the array returned by the children() method. And it is an asynchronous method, which requires the use of the await keyword.

rowData(): Promise<string[]>

Get all the attributes of the tree node and return it as an array.

  • Return value: string[] type, a string array composed of tree node attributes.

    For example, for a file tree, a file node's attribute may contain the values of [file name, file size, file type, last modified time].

expandable(): Promise<boolean>

Whether the tree node can be expanded, it can be expanded to true, but not to be expanded to false.

  • Return value: boolean type, whether it can be expanded.

expanded(): Promise<boolean>

The expanded condition of the tree node is true if expanded, and false if not expanded (collapsed).

  • Return value: boolean type, whether it has been expanded.

itemPath(): Promise<ItemPath>

The location of the tree node.

  • Return value L: ItemPath type, representing the location of the tree node.

selected(): Promise<boolean>

The selection status of the tree node, true for selected, false for unselected (collapsed).

  • Return value: boolean type, whether the node is selected or not.

checkState(): Promise<boolean | 'partial'>

Gets the selected status of the tree node in the list item.

  • Return value: boolean type or partial string. true means checked, false means unchecked, "partial" means partially checked (common for checkboxes with sub-options).

Chinese version click here.