Advanced Control Type - List

For list control and list item control, CukeTest provides List and ListItem two object types. Since the list view is a compound structure, CukeTest provides many methods, which can be understood in combination with table view control Table and tree view control Tree .

List View Control: List

The object type used to describe the list view control - List, because it is a view component of Qt, exists as a container of list items.

Definitions in the types file

export interface IWinList extends IWintControl {
    select(value: string): Promise<void>;
    itemName(index: number): Promise<string>;
    columnName(index: number): Promise<string>;
    columnItemValue(item: string | number, column: string | number): Promise<string>;
    scrollTo(value: number | string): Promise<IWinListItem>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;
    
    findItem(value: string | ((value: string) => Promise<boolean>)): Promise<IWinListItem>;
    
    data(): Promise<string[]>;
    columnCount(): Promise<number>;
    columnHeaders(): Promise<string[]>;
    selectedName(): Promise<string>;
    itemCount(): Promise<number>;
}

class WinList(WinControl):
	def itemName(index: int) -> str
	def columnName(index: int) -> str
	def columnHeaders() -> List[str]
	def columnItemValue(item: Union[str, int], column: Union[str, int]) -> str
	def columnCount() -> int
	def data() -> List[str]
	def findItem(value: str) -> "WinListItem"
	def itemCount() -> int
	def select(value: str) -> "WinListItem"
	def selectedName() -> str
	def scrollTo(value: Union[str, int]) -> "WinListItem"
	def scrollToTop() -> None
	def scrollToBottom() -> None

Object manipulation API

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

findItem(text): Promise<IWinListItem | null>

Searches for the target list item by name, returns the automation object for the target list item, or null if none is found.

• text: string, Expect the content or text of the target list item;
• returns: Promise<IWinListItem> or Promise<null>, Asynchronously searches the target list item in the application, and returns null if no search is found.

findItem(callback(value)): Promise<IWinListItem | null>

An advanced search method for list items, but when directly looking for the name of the target list item is not enough to meet the needs, you can pass in a function as the search condition.
For example, query the list item containing the string "Ltd.", or query is a list item of mobile phone number, and verify whether it conforms to the regular expression /\d{11}/, etc.

• callback: The function used to test the name of each item in the list will traverse the current list until the function returns true, the input and output are as follows:
  • value: string, Input to the callback function, the name string of the list item currently being processed.
  • output: Promise<boolean>, Accepts an asynchronous boolean return value. Stops traversal when the output is true. false or no return will continue to traverse the list until the bottom of the list is reached.
• returns: Promise<IWinListItem|null>, Asynchronously returns the list item that satisfies the test function (test function returns true), returns null if not found.

select(index): Promise<void>

Selects the list item at the specified index. For a long list, it will scroll to the top first, and then scroll to the target list item position.

• index: number, Represents the number of the list item in the list. 0 if it is the first item.
• returns: An asynchronous method that returns no value.

itemName(index: number): Promise<string>

Get the list item name of the target index value.

• index: number, The index value of the target list item.
• returns: Promise<string>, Asynchronously returns the list item name corresponding to the target index value.

columnName(index: number): Promise<string>

Get the name of the head of the list (if any) for the target index value.

• index: number, The index value of the head of the target list (the head of the indexth column).
• returns: Promise<string>, Asynchronously returns the name of the head of the list corresponding to the target index value.

scrollTo(index): Promise<void>

Scroll to target index position. If the target location has not been loaded, it will be loaded until the target index location.

• index: number, Represents the number of the list item in the list. 0 if it is the first item.
• returns: An asynchronous method that returns no value.

scrollToTop(): Promise<void>

Scroll to the top of the list.

• returns: An asynchronous method that returns no value.

scrollToBottom(): Promise<void>

Scroll to the bottom of the list. The bottom of the list here refers to the bottom of the loaded list, in order to avoid performance problems caused by very long lists.

• returns: An asynchronous method that returns no value.

data(): Promise<string[]>

Get the data in the list view and return it. It will automatically scroll the list to the bottom until all list items are traversed. If the list view adopts batch loading (or it can be understood as lazy loading), only the loaded data will be obtained, and the unloaded data will not be obtained.

• returns: Promise<string[]>, A string array of list option values. You need to use the await keyword to retrieve the result.

columnItemValue(item: string | number, column: string | number): Promise<string>

Gets the value (usually the name of the list item) of the list item at the specified row and column.

• item: number or string, Specifies a row, which can be a list item name or an item index. So does the column parameter below.
• column: number or string, Specify a column, which can be a target column name or an item index.
• returns: Promise<string>, Asynchronously returns the value of the target list item.

columnCount(): Promise<number>

Get the number of columns.

• returns: Promise<number>, Asynchronously returns the number of columns in the list.

columnHeaders(): Promise<string[]>

Get the names of all columns.

• returns: Promise<string[]>, Asynchronously returns the names of all columns in the list.

selectedName(): Promise<string>

Get the name of the currently selected column.

• returns: Promise<string>, Asynchronously returns the name of the selected list item.

itemCount(): Promise<number>

Get the number of data in the list view. It will automatically scroll the list to the bottom until all list items are traversed. If the list view adopts batch loading (or it can be understood as lazy loading), only the loaded data will be obtained, and the unloaded data will not be obtained.

• returns: Promise<number>, Asynchronously returns the number of list items.

ListItem Control: ListItem

For the list item control in the list, the model manager provides ListItem type. Different from the methods of operating list items provided by the List object. such as scrollTo(), select(), the list item control itself contains position information, so its methods do not need to pass in additional parameters .

type file definition

export interface IWinListItem extends IWintControl {
    scrollIntoView(): Promise<void>;
    setSelect(select: boolean): Promise<void>; //add to selection, works on some controls like file explorer
    select(select: boolean): Promise<void>;

    selected(): Promise<boolean>;
}

class WinListItem(WinControl):
	def scrollntoView() -> None
	def select() -> None
	def selected() -> bool
	def setSelect(select: bool) -> None

Object manipulation API

• returns: An asynchronous method that returns no value.

select(): Promise<void>

Check list item. If the item is not within the visible range, it will automatically scroll to the position where the item is located.

• returns: An asynchronous method that returns no value.

setSelect(select): Promise<void>

When the list item supports multiple selection by default, or each list item contains a checkbox (to identify the selected state), then the setSelect() method can make multiple list items selected at the same time. The most common scenario is file checkboxes in the Windows file manager. Similar to the toggleCheck() method of the CheckBox control.

• select: Boolean, true means checkbox is checked, false means to uncheck the target checkbox.
• returns: An asynchronous method that returns no value.

scrollIntoView(): Promise<void>

Scroll to list item position.

• returns: An asynchronous method that returns no value.

selected(): Promise<boolean>

Whether the target list item is selected.

• returns: Asynchronously returns the selected result.