Basic Control Types

In the previous article, we learned about container classes and control base classes in CukeTest. This article introduces the APIs for various control types, covering the following basic controls:

• Button Control
• Window Control
• Label Control
• Edit Control
• RadioButton Control
• CheckBox Control
• ComboBox Control
• SpinBox Control
• Application Control
• ProgressBar Control
• Dial Control
• Slider Control
• ScrollArea Control
• MenuBar & MenuBarItem Controls
• Menu & MenuItem Controls
• TabBar, Tab & TabItem Controls
• QuickItem Control
• Qt WebEngine

For more complex control classes with extensive methods, please refer to the following separate documents:

• List Controls: Introduces List and ListItem controls
• Tree Controls: Introduces Tree and TreeItem controls
• Table Controls: Introduces Table and TableItem controls

For custom views derived from AbstractView in Qt applications, see:

• Custom View Controls: Introduces ItemView and ItemViewItem controls

Since each control class inherits from IQtControl, each control class has all the operations and property methods of Common Control. Take the CheckBox control class as an example:

The CheckBox control has an operation method - toggleCheck() used to set whether to check or clear the check; a property method checkState() used to determine the checked status of the CheckBox. true means checked, false means unchecked:

export interface IQCheckBox extends IQtControl {
    toggleCheck(checkState: boolean): Promise<void>
    checkState(): Promise<boolean>
}

class QCheckBox(QtControl):
    def checkState() -> bool
    def toggleCheck(checkState: bool) -> None

export interface IQCheckBox extends IQtControl {
    toggleCheck(checkState: boolean): Promise<void>
    checkState(): Promise<boolean>
    // From IQtControl  
    click(x?: number, y?: number, mousekey?: number): Promise<void>;
    dblClick(x?: number, y?: number, mousekey?: number): Promise<void>;
    moveMouse(x?: number, y?: number): Promise<void>;
    wheel(value: number): Promise<void>;
    takeScreenshot():Promise<string>;

    rect(): Promise<Rect> 
}

Basic Control Classes

Button Control

For standard button controls, the Model Manager provides the Button object type.

export interface IQButton extends IQtControl {
    text(): Promise<string>;
}

class QButton(QtControl):
    def text() -> str

text()

Gets the text content displayed on the button.

Returns:

• string - The text content of the button.

Example:

// Get button text and verify
let text = await model.getButton("Button").text();
assert.equal(text, 'Button');

# Get button text and verify
text = model.getButton("Button").text()
assert text == 'Button'

Window Control

For application window controls, the Model Manager provides the Window object type.

export interface IQWindow extends IQtControl {
    activate(): Promise<void>;
    close(): Promise<void>;
    maximize(): Promise<void>;
    minimize(): Promise<void>;
    restore(): Promise<void>;
}

class QWindow(QtControl):
    def activate() -> None
    def close() -> None
    def maximize() -> None
    def minimize() -> None
    def restore() -> None

activate()

Activates the target window, making it appear at the very top of the desktop to avoid being covered by other windows.

Returns:

• An asynchronous method that returns no value.

Example:

// Activate Qt application window
await model.getWindow("MainWindow").activate();

# Activate Qt application window
model.getWindow("MainWindow").activate()

Note: Since automation between CukeTest and Qt is implemented via communication, automated operations will not fail even if the Qt window is covered.

close()

Closes the target window.

Returns:

• An asynchronous method that returns no value.

Example:

// Close Qt application window
await model.getWindow("MainWindow").close();

# Close Qt application window
model.getWindow("MainWindow").close()

maximize()

Maximizes the target window.

Returns:

• An asynchronous method that returns no value.

Example:

// Maximize Qt application window
await model.getWindow("MainWindow").maximize();

# Maximize Qt application window
model.getWindow("MainWindow").maximize()

minimize()

Minimizes the target window.

Returns:

• An asynchronous method that returns no value.

Example:

// Minimize Qt application window
await model.getWindow("MainWindow").minimize();

# Minimize Qt application window
model.getWindow("MainWindow").minimize()

restore()

Restores the target window. This method can be used to return the window to its normal state after it has been minimized.

Returns:

• An asynchronous method that returns no value.

Example:

// Minimize first
await model.getWindow("MainWindow").minimize();
// Then restore
await model.getWindow("MainWindow").restore();

# Minimize first
model.getWindow("MainWindow").minimize()
# Then restore
model.getWindow("MainWindow").restore()

Label Control

For label controls used to identify other controls or display fixed content, there are no operation methods, only one property method:

export interface IQLabel extends IQtControl {
    text(): Promise<string>
}

class QLabel(QtControl):
    def text() -> str

text()

Gets the current text value of the label.

Returns:

• string - The text content of the label.

Example:

// Get label text and verify
let text = await model.getLabel("Line_1:").text();
assert.equal(text, 'Line_1');

# Get label text and verify
text = model.getLabel("Line_1:").text()
assert text == 'Line_1'

----

Edit Control

For input box controls that receive user input. There is no distinction between single-line and multi-line input boxes. The provided methods focus on managing the text value.

export interface IQEdit extends IQtControl {
    set(value: String): Promise<void>;
    clearAll(): Promise<void>;
    value(): Promise<string>;
}

class QEdit(QtControl):
    def value() -> str
    def set(value: str) -> None
    def clearAll() -> None

set(value)

Sets the text value in the input box, replacing any existing content.

Parameters:

• value: string - The text to write to the input box.

Returns:

• An asynchronous method that returns no value.

Example:

// Set text in edit box
await model.getEdit("Edit").set("Hello World!");

# Set text in edit box
model.getEdit("Edit").set("Hello World!")

clearAll()

Clears all text from the input box.

Returns:

• An asynchronous method that returns no value.

Example:

// Clear edit content
await model.getEdit("Edit").clearAll();

# Clear edit content
model.getEdit("Edit").clearAll()

value()

Gets the current text value from the input box.

Returns:

• string - The text content in the input box.

Example:

// Get and verify edit content
let actual = await model.getEdit("Edit").value();
let expected = 'Hello World!';
assert.equal(actual, expected);

# Get and verify edit content
actual = model.getEdit("Edit").value()
expected = 'Hello World!'
assert actual == expected

RadioButton Control

For radio button controls, methods are provided to select the button and check its selection state.

export interface IQRadioButton extends IQtControl {
    check(): Promise<void>;
    checked(): Promise<boolean>;
}

class QRadioButton(QtControl):
    def check() -> None
    def checked() -> bool

check()

Selects the target radio button.

Returns:

• An asynchronous method that returns no value.

Example:

// Select radio button
await model.getRadioButton("Male").check();

# Select radio button
model.getRadioButton("Male").check()

checked()

Gets the selection state of the radio button.

Returns:

• boolean - true if selected, false if not selected.

Example:

// Check if selected
let isChecked = await model.getRadioButton("Male").checked();
console.log(`Is checked: ${isChecked}`);

# Check if selected
is_checked = model.getRadioButton("Male").checked()
print(f"Is checked: {is_checked}")

CheckBox Control

For checkbox controls, you can directly set the checked state or retrieve it.

export interface IQCheckBox extends IQtControl {
    checkState(): Promise<boolean | 'partial'>
    toggleCheck(checkState: boolean | 'partial'): Promise<void>
}

class QCheckBox(QtControl):
    def checkState() -> bool
    def toggleCheck(checkState: bool) -> None

toggleCheck(checkState)

Sets the checked state of the checkbox.

Parameters:

• checkState: boolean | 'partial' - true to check the checkbox, false to uncheck it, 'partial' for indeterminate state (rarely used).

Returns:

• An asynchronous method that returns no value.

Example:

// Check the box
await model.getCheckBox("Remember Me").toggleCheck(true);

// Uncheck the box
await model.getCheckBox("Remember Me").toggleCheck(false);

# Check the box
model.getCheckBox("Remember Me").toggleCheck(True)

# Uncheck the box
model.getCheckBox("Remember Me").toggleCheck(False)

checkState()

Gets the checked state of the checkbox.

Returns:

• boolean | 'partial' - true if checked, false if unchecked, 'partial' for indeterminate state.

Example:

// Get checkbox state
let state = await model.getCheckBox("Remember Me").checkState();
if (state === true) {
    console.log("Checked");
} else if (state === false) {
    console.log("Unchecked");
}

# Get checkbox state
state = model.getCheckBox("Remember Me").checkState()
if state == True:
    print("Checked")
elif state == False:
    print("Unchecked")

ComboBox Control

For combo box controls with dropdown lists, methods are provided to open the dropdown and select specific options.

export interface IQComboBox extends IQtControl {
    open(): Promise<void>;
    select(nameOrIndex: String | number): Promise<void>;

    selectedIndex(): Promise<number>;
    selectedName(): Promise<string>;
    items(): Promise<string[]>;
}

class QComboBox(QtControl):
    def open() -> None
    def select(nameOrIndex: Union[str, int]) -> None
    def selectedIndex() -> int
    def selectedName() -> str
    def items() -> List[str]

open()

Expands the dropdown list, equivalent to clicking the ▼ button on the right side.

Returns:

• An asynchronous method that returns no value.

Example:

// Open the dropdown
await model.getComboBox("City").open();

// Close it using invoke
await model.getComboBox("City").invoke("hidePopup");

# Open the dropdown
model.getComboBox("City").open()

# Close it using invoke
model.getComboBox("City").invoke("hidePopup")

select(nameOrIndex)

Selects a specific option from the dropdown list.

Parameters:

• nameOrIndex: number | string - If a number, selects the option at that index position; if a string, selects the option with that name.

Returns:

• An asynchronous method that returns no value.

Example:

// Select by index
await model.getComboBox("City").select(0);

// Select by name
await model.getComboBox("City").select("Beijing");

# Select by index
model.getComboBox("City").select(0)

# Select by name
model.getComboBox("City").select("Beijing")

selectedIndex()

Gets the index position of the currently selected item in the dropdown list.

Returns:

• number - The index position of the currently selected value.

Example:

let index = await model.getComboBox("City").selectedIndex();
console.log(`Selected Index: ${index}`);

# Get selected index
index = model.getComboBox("City").selectedIndex()
print(f"Selected Index: {index}")

selectedName()

Gets the name of the currently selected item.

Returns:

• string - The currently selected value.

Example:

let selected = await model.getComboBox("City").selectedName();
console.log(`Selected: ${selected}`);

# Get selected name
selected = model.getComboBox("City").selectedName()
print(f"Selected: {selected}")

items()

Gets the names of all available options in the combo box.

Returns:

• string[] - Array of all available option names.

Example:

let allItems = await model.getComboBox("City").items();
console.log(`Options: ${allItems.join(', ')}`);

# Get all options
all_items = model.getComboBox("City").items()
print(f"Options: {', '.join(all_items)}")

----

SpinBox Control

For spin box controls with up/down arrows for value adjustment.

Note: The SpinBox control inherits from the Edit control, meaning it can use all Edit control methods in addition to the following methods.

export interface IQSpinBox extends IQEdit {
    increment(): Promise<void>;
    decrement(): Promise<void>;
}

class QSpinBox(QEdit):
    def increment() -> None
    def decrement() -> None

increment()

Increases the spin box value by one unit. The unit size depends on the application settings. Equivalent to clicking the up arrow once.

Returns:

• An asynchronous method that returns no value.

Example:

// Increment once
await model.getSpinBox("Quantity").increment();

// Increment multiple times
for (let i = 0; i < 5; i++) {
    await model.getSpinBox("Quantity").increment();
}

# Increment once
model.getSpinBox("Quantity").increment()

# Multiple increments
for i in range(5):
    model.getSpinBox("Quantity").increment()

decrement()

Decreases the spin box value by one unit. The unit size depends on the application settings. Equivalent to clicking the down arrow once.

Returns:

• An asynchronous method that returns no value.

Example:

// Decrement once
await model.getSpinBox("Quantity").decrement();

# Decrement once
model.getSpinBox("Quantity").decrement()

Application Control

Represents the application itself, typically exists as the top-level control. Provides methods to get application properties and control the application.

export interface IQApplication extends IQtControl {
    launch(waitSeconds?: number): Promise<IQApplication>
    launch(appPath?: string, waitSeconds?: number): Promise<IQApplication>
    quit(): Promise<void>;
    exists(seconds?: number): Promise<boolean>
    appInfo(): Promise<AppInfo>;
    pid(): Promise<number>;
    topControls(): Promise<IQtControl[]>;
    findAll(): Promise<IQtControl[]>;
    fromPoint(x: number, y: number): Promise<IQtControl[]>;
}

export interface AppInfo {
    appName: string,
    appPath: string,
    appVersion: string,
    pid: number,
}

class QApplication(QtContainer):
    def launch(appPath=None, waitSeconds=10) -> "QApplication":
    def quit() -> None
    def exists(seconds=5) -> bool
    def appInfo() -> "AppInfo"
    def pid() -> int
    def topControls() -> List[QtControl]
    def findAll() -> List[QtControl]
    def fromPoint(x: int, y: int) -> List[QtControl]

class AppInfo(TypedDict):
    appName: str
    appPath: str
    appVersion: str
    pid: int

appInfo()

Gets application information such as name, version, path, and process ID.

Returns:

• AppInfo - Object containing application name, path, version, and process ID.

Example:

let info = await model.getApplication("App").appInfo();
console.log(`Name: ${info.appName}, Path: ${info.appPath}`);

# Get app info
info = model.getApplication("App").appInfo()
print(f"Name: {info['appName']}, Path: {info['appPath']}")

pid()

Gets the application process ID.

Returns:

• number - The process ID.

Example:

let processId = await model.getApplication("App").pid();
console.log(`PID: ${processId}`);

# Get PID
process_id = model.getApplication("App").pid()
print(f"PID: {process_id}")

launch(appPath?, waitSeconds?)

Launches the application. If appPath is not provided, it automatically uses the appPath property from the Application object in the model. Waits for the application process to start, with the maximum wait time controlled by waitSeconds (default 10 seconds). If the process is not detected within this time, an error is thrown.

Parameters:

• appPath: (Optional) Application path. If not provided, uses the appPath property from the model.
• waitSeconds: (Optional) Timeout for waiting for the application process to appear, default is 10 seconds.

Returns:

• Promise<IQApplication> - The launched application object.

Example:

Assuming the model model1.tmodel contains an Application node named basiclayouts with appPath property set to C:/Program Files/LeanPro/CukeTest/bin/basiclayouts.exe, the following two approaches are equivalent:

const { QtAuto } = require("leanpro.qt");
(async () => {
    let modelQt = QtAuto.loadModel("model1.tmodel");

    // Method 1: Launch process first, then wait for app to be ready
    await QtAuto.launchQtProcessAsync("C:/Program Files/LeanPro/CukeTest/bin/basiclayouts.exe");
    await modelQt.getApplication("basiclayouts").exists(10);

    // Method 2: Use launch() method directly
    await modelQt.getApplication("basiclayouts").launch();
    
    // Can also specify app path and timeout
    await modelQt.getApplication("basiclayouts").launch("C:/Program Files/LeanPro/CukeTest/bin/basiclayouts.exe", 15);
})()

from leanproAuto import QtAuto
modelQt = QtAuto.loadModel("model1.tmodel")

# Method 1: Launch process first, then wait for app to be ready
QtAuto.launchQtProcessAsync("C:/Program Files/LeanPro/CukeTest/bin/basiclayouts.exe")
modelQt.getApplication("basiclayouts").exists(10)

# Method 2: Use launch() method directly
modelQt.getApplication("basiclayouts").launch()

# Can also specify app path and timeout
modelQt.getApplication("basiclayouts").launch("C:/Program Files/LeanPro/CukeTest/bin/basiclayouts.exe", 15)

quit()

Quits the application, closing all windows belonging to the application.

Returns:

• An asynchronous method that returns no value.

Example:

await model.getApplication("App").quit();

# Quit app
model.getApplication("App").quit()

exists(seconds?)

Checks if the application process exists.

Parameters:

• seconds: (Optional) number - Maximum time to wait in seconds. Defaults to 5 seconds.

Returns:

• boolean - true if the process exists, false otherwise.

Example:

// Check if app exists
let exists = await model.getApplication("basiclayouts").exists(10);

# Check if app exists
exists = model.getApplication("basiclayouts").exists(10)

topControls()

Gets the top-level controls of the application.

Returns:

• IQtControl[] - Array of top-level control objects.

Example:

// Get all top-level controls
let controls = await model.getApplication("basiclayouts").topControls();

# Get all top-level controls
controls = model.getApplication("basiclayouts").topControls()

findAll()

Finds all processes with the same name.

Returns:

• Array of all matching application objects, allowing continued calls to model nodes on returned objects.

Example:

// Get all processes with the same name
const apps = await modelQt.getApplication("standarddialogs").findAll()

// Find process with smallest PID
let appsPID = await Promise.all(apps.map(async (app) => app.pid()))
const minimalPID = appsPID.slice().sort()[0]
const app = apps[appsPID.indexOf(minimalPID)]
const currentAppPID = await app.pid()
assert.equal(currentAppPID, minimalPID);

// Iterate and operate on all processes
// Note: Can continue calling model nodes on returned objects
for (let app of apps) {
    // Activate window
    await app.getWindow("Standard_Dialogs").activate()
    
    // Click "QInputDialog::getInt()" button
    await app.getButton("QInputDialog::getInt()").click();
    await app.getButton("OK").click()
    
    // Click "QInputDialog::getMultiLineText" button
    await app.getButton("QInputDialog::getMultiLineText").click();
    await app.getButton("OK").click()
    await app.getButton("QInputDialog::getMultiLineText").click();
}

// Close all processes
for (let app of apps) {
    await app.quit()
}

# Get all processes with the same name
apps = modelQt.getApplication("standarddialogs").findAll()

# Find process with smallest PID
apps_pid = [app.pid() for app in apps]
minimal_pid = sorted(apps_pid)[0]
app = apps[apps_pid.index(minimal_pid)]
current_app_pid = app.pid()
assert current_app_pid == minimal_pid

# Iterate and operate on all processes
for app in apps:
    # Activate window
    app.getWindow("Standard_Dialogs").activate()
    
    # Click "QInputDialog::getInt()" button
    app.getButton("QInputDialog::getInt()").click()
    app.getButton("OK").click()
    
    # Click "QInputDialog::getMultiLineText" button
    app.getButton("QInputDialog::getMultiLineText").click()
    app.getButton("OK").click()
    app.getButton("QInputDialog::getMultiLineText").click()

# Close all processes
for app in apps:
    app.quit()

fromPoint(x, y)

Gets control from screen coordinates.

Parameters:

• x: number - Horizontal pixel position on the entire screen.
• y: number - Vertical pixel position on the entire screen.

Returns:

• Control at the specified screen position. Returns empty if coordinates are outside the application window.

Example:

Example: Find the control 100 pixels to the right of a button named button1:

JavaScript

Python

// Get screen position coordinates of button1
let rect = await model.getButton("button1").rect();
// Calculate button1 center coordinates and add 100 pixels horizontally
let x = Math.floor(rect.x + rect.width / 2) + 100; 
let y = Math.floor(rect.y + rect.height / 2);
// Find control by screen coordinates and print properties
let wid = await model.getApplication("app_name").fromPoint(x, y);
let prop = await wid.allProperties();
console.log(prop);

# Get screen position coordinates of button1
rect = model.getButton("button1").rect()
# Calculate button1 center coordinates and add 100 pixels horizontally
x = int(rect.x + rect.width / 2) + 100
y = int(rect.y + rect.height / 2)
# Find control by screen coordinates and print properties
wid = model.getApplication("app_name").fromPoint(x, y)
prop = wid.allProperties()
print(prop)

MenuBar & MenuBarItem Controls

For interacting with the application's menu bar and its menu bar items. The MenuBar control is used to operate the menu bar, and MenuBarItem represents buttons in the menu bar, typically used to click or open menu buttons to expand the menu. If you need to directly operate menu options, it's recommended to read the invoke() method of Menu & MenuItem.

MenuBar Methods:

MenuBarItem Methods:

export interface IQMenuBar extends IQtControl {
    open(itemName: String): Promise<void>;
    items(): Promise<IQMenuBarItem[]>;
}
export interface IQMenuBarItem extends IQtControl {
    open(): Promise<void>;
    text(): Promise<string>;
}

class QMenuBar(QtControl):
    def open(itemName: str) -> None
    def items() -> List[QMenuBarItem]
class QMenuBarItem(QtControl):
    def itemIndex() -> int
    def open(itemName: str) -> None
    def text() -> str

The following are methods provided by the MenuBar control:

open(itemName)

Opens the target menu bar item by passing in the name of the target menu bar item.

If using the open() method on MenuBarItem, no parameters are needed.

Parameters:

• itemName: string - The name of the target menu bar item.

Returns:

• An asynchronous method that returns no value.

Example:

// Open "File" menu from MenuBar
await model.getMenuBar("MainMenuBar").open("File");

# Open "File" menu from MenuBar
model.getMenuBar("MainMenuBar").open("File")

items()

Gets all menu bar item control objects.

Returns:

• IQMenuBarItem[] - Array of all menu bar item control objects.

Example:

// Get all menu bar items
let menuItems = await model.getMenuBar("MainMenuBar").items();
console.log(`Number of menu bar items: ${menuItems.length}`);

// Iterate through all menu bar items
for (let item of menuItems) {
    let itemText = await item.text();
    console.log(`Menu item: ${itemText}`);
}

# Get all menu bar items
menu_items = model.getMenuBar("MainMenuBar").items()
print(f"Number of menu bar items: {len(menu_items)}")

# Iterate through all menu bar items
for item in menu_items:
    item_text = item.text()
    print(f"Menu item: {item_text}")

The following are methods provided by the MenuBarItem control:

open()

Opens the menu item.

Returns:

• An asynchronous method that returns no value.

Example:

// Get menu item via items() then open
let menuItems = await model.getMenuBar("MainMenuBar").items();
await menuItems[0].open();

# Get menu item via items() then open
menu_items = model.getMenuBar("MainMenuBar").items()
menu_items[0].open()

text()

Gets the menu item text.

Returns:

• string - The text of the menu item.

Example:

Verify getting the text of the menu bar item File:

// Get menu item text and verify
let text = await model.getMenuItem("File").text();
assert.equal(text, 'File');

# Get menu item text and verify
text = model.getMenuItem("File").text()
assert text == 'File'

Menu & MenuItem Controls

For interacting with application menus and menu items. The Menu and MenuItem controls are used to operate menu selection, expansion, and hiding.

Menu Methods:

MenuItem Methods:

The menu control definition is as follows, but the most commonly used and key method is the invoke() operation method, which is introduced later:

export interface IQMenu extends IQtControl {
    invoke(itemName: string): Promise<void>;
    show(): Promise<void>;
    hide(): Promise<void>;
    itemNames(): Promise<string[]>;
    items(): Promise<IQMenuItem[]>;
}

export interface IQMenuItem extends IQtControl {
    invoke(): Promise<void>;
    toggleCheck(value: boolean): Promise<void>;
    checked(): Promise<boolean>;
    checkable(): Promise<boolean>;
    text(): Promise<string>;
    itemIndex(): Promise<number>;
    hover(): Promise<void>;
}

class QMenu(QtControl):
    def invoke(itemName: str) -> None
    def show() -> None
    def hide() -> None
    def itemNames() -> List[str]
    def items() -> List[QMenuItem]
class QMenuItem(QtControl):
    def invoke() -> None
    def toggleCheck(value: bool) -> None
    def checked() -> bool
    def checkable() -> bool
    def text() -> str
    def itemIndex() -> int
    def hover() -> None

invoke(itemName)

Directly triggers a menu item in the target menu. For the Menu control, you need to pass in the name of the target menu item; for the MenuItem control, no parameters are needed.

This method does not expand the menu but directly triggers the target menu item function through communication, so users will not observe menu changes.

Parameters:

• itemName: The name of the target menu item, must be a first-level menu item of the target menu.

Returns:

• An asynchronous method that returns no value.

Example:

// Directly trigger "New" menu item from "File" menu
await model.getMenu("File").invoke("New");

# Directly trigger "New" menu item from "File" menu
model.getMenu("File").invoke("New")

show()

Expands the target menu.

Returns:

• An asynchronous method that returns no value.

Example:

// Show menu
await model.getMenu("File").show();

# Show menu
model.getMenu("File").show()

hide()

Hides the target menu.

Returns:

• An asynchronous method that returns no value.

Example:

// Hide menu
await model.getMenu("File").hide();

# Hide menu
model.getMenu("File").hide()

itemNames()

Gets the names of all items in the target menu.

Returns:

• string[]: Asynchronously returns an array of item names.

Example:

// Get all menu item names
let names = await model.getMenu("File").itemNames();
console.log(`Menu Items: ${names.join(', ')}`);

# Get all menu item names
names = model.getMenu("File").itemNames()
print(f"Menu Items: {', '.join(names)}")

items()

Gets all menu item objects in the target menu.

Returns:

• MenuItem[] - Array of all menu item objects.

Example:

// Get all menu item objects and iterate
let items = await model.getMenu("File").items();
for (let item of items) {
    let text = await item.text();
    console.log(`Menu item: ${text}`);
}

# Get all menu item objects and iterate
items = model.getMenu("File").items()
for item in items:
    text = item.text()
    print(f"Menu item: {text}")

The following are methods for the MenuItem object:

invoke()

Directly triggers the target menu item.

This method does not expand the menu but directly triggers the target menu item function through communication, so users will not observe menu changes.

Returns:

• An asynchronous method that returns no value.

Example:

// Directly trigger menu item
await model.getMenuItem("New").invoke();

# Directly trigger menu item
model.getMenuItem("New").invoke()

checkable()

Gets whether the menu item can be checked. Some menu items toggle their checked state through clicking, this method is used to get whether the menu item is checkable.

Returns:

• boolean - Whether the menu item is checkable.

Example:

// Check if menu item is checkable
let canCheck = await model.getMenuItem("ShowToolbar").checkable();
console.log(`Menu item checkable: ${canCheck}`);

# Check if menu item is checkable
can_check = model.getMenuItem("ShowToolbar").checkable()
print(f"Menu item checkable: {can_check}")

toggleCheck(value)

Changes the menu item checked state. Some menu items toggle their checked state through clicking, this method is used to modify the checked state. Only menu items where checkable() returns true can use this method.

Parameters:

• value: boolean - The checked state.

Returns:

• An asynchronous method that returns no value.

Example:

// Set menu item to checked state
await model.getMenuItem("ShowToolbar").toggleCheck(true);
// Uncheck menu item
await model.getMenuItem("ShowToolbar").toggleCheck(false);

# Set menu item to checked state
model.getMenuItem("ShowToolbar").toggleCheck(True)
# Uncheck menu item
model.getMenuItem("ShowToolbar").toggleCheck(False)

checked()

Gets the menu item checked state.

Returns:

• boolean - The checked state.

Example:

// Get menu item checked state
let isChecked = await model.getMenuItem("ShowToolbar").checked();
console.log(`Menu item checked: ${isChecked}`);

# Get menu item checked state
is_checked = model.getMenuItem("ShowToolbar").checked()
print(f"Menu item checked: {is_checked}")

text()

Gets the menu item text content.

Returns:

• string - The menu item text.

Example:

Click the Menu control, verify getting the text content of the menu item About_Qt:

// Click menu and get menu item text
model.getMenu("Help").click();
let text = await model.getMenuItem("About_Qt").text();
assert.equal(text, 'About_Qt');

# Click menu and get menu item text
model.getMenu("Help").click()
text = model.getMenuItem("About_Qt").text()
assert text == 'About_Qt'

itemIndex()

Gets the menu item index, which is the itemIndex value in the identification properties.

Returns:

• number - The menu item index.

Example:

// Get menu item index
let index = await model.getMenuItem("New").itemIndex();
console.log(`Menu item index: ${index}`);

# Get menu item index
index = model.getMenuItem("New").itemIndex()
print(f"Menu item index: {index}")

hover()

Hovers the mouse over the target menu item, can be used to expand sub-menu items.

Returns:

• An asynchronous method that returns no value.

Example:

// Hover to expand
await model.getMenuItem("File").hover();

# Hover to expand
model.getMenuItem("File").hover()

ProgressBar Control

For progress bar controls in applications. You can get the progress bar value by calling the value() method.

Note: Since progress bar values are usually controlled by internal logic or other controls, directly modifying their values is not supported.

Appearance:

export interface IQProgressBar extends IQtControl {
    value(): Promise<number>;
}

class QProgressBar(QtControl):
    def value() -> int

value()

Gets the current value of the progress bar and returns it. Since the return value is a number, the percentage % sign is omitted.

Returns:

• number - The current value of the progress bar.

Example:

// Get current progress bar value
let progress = await model.getProgressBar("downloadProgress").value();
console.log(`Current progress: ${progress}%`);

# Get current progress bar value
progress = model.getProgressBar("downloadProgress").value()
print(f"Current progress: {progress}%")

Dial Control

For dial/knob controls used to manually adjust values, similar in function to Slider controls. This control was introduced by Qt for touch-screen applications.

Appearance:

export interface IQDial extends IQtControl {
    value(): Promise<number>;
    setValue(value: number): Promise<void>;
}

class QDial(QtControl):
    def value() -> int
    def setValue(value: int) -> None

value()

Gets the current value of the dial and returns it.

Returns:

• number - The current value of the dial.

Example:

// Get current dial value
let dialValue = await model.getDial("volumeDial").value();
console.log(`Dial value: ${dialValue}`);

# Get current dial value
dial_value = model.getDial("volumeDial").value()
print(f"Dial value: {dial_value}")

setValue(value)

Sets the value of the dial, rotating the dial to the specified value position without exceeding the maximum value.

Parameters:

• value: number - Rotates the dial to the specified value position.

Returns:

• An asynchronous method that returns no value.

Example:

// Set dial value to 50
await model.getDial("volumeDial").setValue(50);

# Set dial value to 50
model.getDial("volumeDial").setValue(50)

Slider Control

For slider controls used to receive user-set values.

export interface IQSlider extends IQtControl {
    value(): Promise<number>;
    setValue(value: number): Promise<void>;
}

class QSlider(QtControl):
    def value() -> int
    def setValue(value: int) -> None

value()

Gets the current value of the slider and returns it.

Returns:

• number - The current value of the slider.

Example:

// Get current slider value
let sliderValue = await model.getSlider("volumeSlider").value();
console.log(`Slider value: ${sliderValue}`);

# Get current slider value
slider_value = model.getSlider("volumeSlider").value()
print(f"Slider value: {sliderValue}")

setValue(value)

Sets the value of the slider, dragging the slider to the specified value position without exceeding the maximum value.

Parameters:

• value: number - Drags the slider to the specified value position.

Returns:

• An asynchronous method that returns no value.

Example:

// Set slider value to 75
await model.getSlider("volumeSlider").setValue(75);

# Set slider value to 75
model.getSlider("volumeSlider").setValue(75)

ScrollArea Control

As a container, when there is a lot of content in the container, it can be scrolled for browsing. Since this control is sometimes set to not display scrollbars, an additional method for scrolling is supported - the ensureVisible() method.

export interface IQScrollArea extends IQtControl {
    ensureVisible(x: number, y: number): Promise<void>;
}

class QScrollArea(QtControl):
    def ensureVisible(x: int, y: int) -> None

ensureVisible(x, y)

Scrolls to the target position (relative to the top-left corner of the scroll area).

Parameters:

• x: number - Horizontal pixel count.
• y: number - Vertical pixel count.

Returns:

• An asynchronous method that returns no value.

Example:

// Scroll to specified position
await model.getScrollArea("contentArea").ensureVisible(100, 200);

# Scroll to specified position
model.getScrollArea("contentArea").ensureVisible(100, 200)

----

TabBar, Tab & TabItem Controls

For tab controls in applications. Tab and TabItem are used to switch tabs. Also provides control for the tab bar where tabs are located - the TabBar control.

TabBar Methods:

Tab Methods:

TabItem Methods:

The tab bar control definition is as follows:

export interface IQTabBar extends IQtControl {
    activate(itemNameOrIndex: string | number): Promise<void>;
    closeTab(itemNameOrIndex: string | number): Promise<void>;

    count(): Promise<string[]>;
    activeIndex(): Promise<number>;
    activeName(): Promise<string>;
    tabNames(): Promise<string[]>;
}

export interface IQTab extends IQtControl {
    getItem(itemNameOrIndex: string | number): IQTabItem;
    activate(itemNameOrIndex: string | number): Promise<void>;
    closeTab(itemNameOrIndex: string | number): Promise<void>;

    activeName(): Promise<string>;
    activeIndex(): Promise<number>;
    count(): Promise<string[]>;
    items(): Promise<string[]>;
}

export interface IQTabItem extends IQtControl {
    activate(): Promise<void>;
    closeTab(): Promise<void>;

    text(): Promise<string>;
    itemIndex(): Promise<number>;
}

class QTabBar(QtControl):
    def activate(itemNameOrIndex: Union[str, int]) -> None
    def count() -> List[str]
    def activeIndex() -> int
    def activeName() -> str
    def tabNames() -> List[str]
    def closeTab(itemNameOrIndex: Union[str, int]) -> None

class QTab(QTabBar):
    def getItem(itemNameOrIndex: Union[str, int]) -> "QTabItem"
    
class QTabItem(QtControl):
    def activate() -> None
    def text() -> str
    def itemIndex() -> int
    def closeTab() -> None

getItem(itemNameOrIndex)

Gets the automation object for the specified tab by passing in the tab index or title.

Parameters:

• itemNameOrIndex: number or string - The index or title of the target tab.

Returns:

• TabItem - Synchronously returns a TabItem operation object.

Example:

// Get tab by index
let tab = model.getTab("MainTab").getItem(0);
// Get tab by name
let tab2 = model.getTab("MainTab").getItem("Home");

# Get tab by index
tab = model.getTab("MainTab").getItem(0)
# Get tab by name
tab2 = model.getTab("MainTab").getItem("首页")

activate(itemNameOrIndex)

Activates the target tab by passing in the tab index or title.

If using the activate() method on TabItem, no parameters are needed.

Parameters:

• itemNameOrIndex: number or string - The index or title of the target tab.

Returns:

• An asynchronous method that returns no value.

Example:

// Activate tab by index
await model.getTab("MainTab").activate(0);
// Activate tab by name
await model.getTab("MainTab").activate("Home");

# Activate tab by index
model.getTab("MainTab").activate(0)
# Activate tab by name
model.getTab("MainTab").activate("首页")

closeTab(itemNameOrIndex)

Closes the target tab by passing in the tab index or title.

If using the closeTab() method on TabItem, no parameters are needed.

Parameters:

• itemNameOrIndex: number or string - The index or title of the target tab.

Returns:

• An asynchronous method that returns no value.

Example:

// Close tab by index
await model.getTab("MainTab").closeTab(1);
// Close tab by name
await model.getTab("MainTab").closeTab("Settings");

# Close tab by index
model.getTab("MainTab").closeTab(1)
# Close tab by name
model.getTab("MainTab").closeTab("设置")

activeIndex()

Gets the index of the currently activated tab.

Returns:

• number - The tab index.

Example:

// Get currently active tab index
let index = await model.getTab("MainTab").activeIndex();
console.log(`Currently active tab index: ${index}`);

# Get currently active tab index
index = model.getTab("MainTab").activeIndex()
print(f"Currently active tab index: {index}")

activeName()

Gets the name of the currently activated tab.

Returns:

• string - The tab name.

Example:

// Get currently active tab name
let name = await model.getTab("MainTab").activeName();
console.log(`Currently active tab: ${name}`);

# Get currently active tab name
name = model.getTab("MainTab").activeName()
print(f"Currently active tab: {name}")

count()

Gets the number of tabs in the tab bar.

Returns:

• number - The number of tabs.

Example:

// Get tab count
let tabCount = await model.getTab("MainTab").count();
console.log(`Tab count: ${tabCount}`);

# Get tab count
tab_count = model.getTab("MainTab").count()
print(f"Tab count: {tab_count}")

activate()

Activates the tab.

Returns:

• An asynchronous method that returns no value.

Example:

// Activate specified tab
let tab = model.getTab("MainTab").getItem(1);
await tab.activate();

# Activate specified tab
tab = model.getTab("MainTab").getItem(1)
tab.activate()

closeTab()

Closes the tab.

Returns:

• An asynchronous method that returns no value.

Example:

// Close specified tab
let tab = model.getTab("MainTab").getItem(1);
await tab.closeTab();

# Close specified tab
tab = model.getTab("MainTab").getItem(1)
tab.closeTab()

text()

Gets the tab title.

Returns:

• string - Returns the tab title.

Example:

// Get tab title
let tab = model.getTab("MainTab").getItem(0);
let title = await tab.text();
console.log(`Tab title: ${title}`);

# Get tab title
tab = model.getTab("MainTab").getItem(0)
title = tab.text()
print(f"Tab title: {title}")

itemIndex()

Gets the tab's position in the entire tab bar.

Returns:

• number - Returns the tab index.

Example:

// Get tab index
let tab = model.getTab("MainTab").getItem("Home");
let index = await tab.itemIndex();
console.log(`Tab index: ${index}`);

# Get tab index
tab = model.getTab("MainTab").getItem("首页")
index = tab.itemIndex()
print(f"Tab index: {index}")

QuickItem Control

In Qt automation, there is a special type of control that is displayed with the Quick prefix in the Model Manager. This represents that the control is developed based on Qt Quick technology, as opposed to other controls introduced in this document which are based on Qt Widget technology.

export interface QuickItem extends QtControl {
    text(): Promise<string>;
    set(text:string): Promise<void>;
}

class QuickItem(QtControl):
    def text() -> str
    def set(text) -> None

The following are methods provided by Quick controls:

text()

Gets the text in the current Quick control. Equivalent to calling property("text").

Returns:

• string - The text inside the Quick control.

Example:

The following two calls return the same result:

// Method 1: Using text() method
let buttonText = await modelQt.getQuick("Button").text();
// Method 2: Using property() method
let buttonText2 = await modelQt.getQuick("Button").property("text");
console.log(`Button text: ${buttonText}`);

# Method 1: Using text() method
button_text = modelQt.getQuick("Button").text()
# Method 2: Using property() method
button_text2 = modelQt.getQuick("Button").property("text")
print(f"Button text: {button_text}")

set(text)

Sets the text or value in the current Quick control.

Parameters:

• text: string - The value to be set.

Returns:

• An asynchronous method that returns no value.

Example:

// Set Quick control text
await modelQt.getQuick("InputField").set("New text content");

# Set Quick control text
modelQt.getQuick("InputField").set("新的文本内容")

If you're unsure about the specific development framework of the application under test, you can refer to How to determine the technology used by Qt applications.

Qt WebView/WebEngine

Qt WebEngine is a browser engine integrated into Qt applications, allowing developers to embed and display web content in applications. The following are methods provided by the Qt WebEngine control for interacting with embedded web pages:

export interface IQWebEngine extends IQtControl {
    runJavaScript(code: string): Promise<string>;
    html(): Promise<string>;
    text(): Promise<string>;
    url(): Promise<string>;
    setUrl(url: string): Promise<void>;
    clickElement(selector: string): Promise<void>;
    highlightElement(selector: string): Promise<void>;
    loaded(seconds?: number): Promise<boolean>;
}

class IQWebEngine(IQtControl):
    def runJavaScript(code: str) -> str
    def html() -> str
    def text() -> str
    def url() -> str
    def setUrl(url: str) -> None
    def clickElement(selector: str) -> None
    def highlightElement(selector: str) -> None
    def loaded(seconds: Optional[int]=None) -> bool

runJavaScript(code)

Executes the specified JavaScript code.

Parameters:

• code: string - The JavaScript code to execute.

Returns:

• String type, returns the execution result of the JavaScript code.

Example:

// Execute JavaScript code to click a button
let script = 'document.querySelector("button.ant-btn-primary").click()';
await modelQt.getWebEngine("WebView2").runJavaScript(script);

// Execute JavaScript code and get return value
let titleScript = 'document.title';
let title = await modelQt.getWebEngine("WebView2").runJavaScript(titleScript);
console.log(`Page title: ${title}`);

# Execute JavaScript code to click a button
script = 'document.querySelector("button.ant-btn-primary").click()'
modelQt.getWebEngine("WebView2").runJavaScript(script)

# Execute JavaScript code and get return value
title_script = 'document.title'
title = modelQt.getWebEngine("WebView2").runJavaScript(title_script)
print(f"Page title: {title}")

html()

Gets the HTML content of the current page.

Returns:

• String type, contains the HTML content of the page.

Example:

// Get page HTML content and verify
const html = await modelQt.getWebEngine("WebView2").html();
assert.ok(html.includes('<html>'));

# Get page HTML content and verify
html = modelQt.getWebEngine("WebView2").html()
assert "<html>" in html

text()

Gets the text content of the current page.

Returns:

• String type, contains the text content of the page.

Example:

// Get page text content and verify
const text = await modelQt.getWebEngine("WebView2").text();
assert.ok(text.includes('Login'));

# Get page text content and verify
text = modelQt.getWebEngine("WebView2").text()
assert "Login" in text

url()

Gets the URL of the current page.

Returns:

• String type, represents the page URL.

Example:

// Get current page URL
const url = await modelQt.getWebEngine("WebView2").url();
assert.equal(url, 'http://localhost:21477/user/login/');

# Get current page URL
url = modelQt.getWebEngine("WebView2").url()
assert url == 'http://localhost:21477/user/login/'

setUrl(url)

Sets the URL of the current page and loads that page.

Parameters:

• url: string - The URL to load.

Returns:

• An asynchronous method that returns no value.

Example:

// Set and load new URL
const url = 'http://localhost:21477/user/login/';
await modelQt.getWebEngine("WebView2").setUrl(url);

# Set and load new URL
url = 'http://localhost:21477/user/login/'
modelQt.getWebEngine("WebView2").setUrl(url)

clickElement(selector)

Clicks the specified element.

Parameters:

• selector: string - The CSS selector of the element to click.

Returns:

• An asynchronous method that returns no value.

Example:

// Click password input box
await modelQt.getWebEngine("WebView2").clickElement("#password");
// Click login button
await modelQt.getWebEngine("WebView2").clickElement("button.login-btn");

# Click password input box
modelQt.getWebEngine("WebView2").clickElement("#password")
# Click login button
modelQt.getWebEngine("WebView2").clickElement("button.login-btn")

highlightElement(selector)

Highlights the specified element.

Parameters:

• selector: string - The CSS selector of the element to highlight.

Returns:

• An asynchronous method that returns no value.

Example:

// Highlight password input box
await modelQt.getWebEngine("WebView2").highlightElement("#password");
// Highlight login button
await modelQt.getWebEngine("WebView2").highlightElement("button.login-btn");

# Highlight password input box
modelQt.getWebEngine("WebView2").highlightElement("#password")
# Highlight login button
modelQt.getWebEngine("WebView2").highlightElement("button.login-btn")

loaded(seconds)

Waits for the page to load, or checks if the page has finished loading.

Parameters:

• seconds: (Optional) number - Maximum wait time (timeout), in seconds. Default is 0, which means only check once and return immediately without waiting or retrying.

Returns:

• boolean - Asynchronously returns the page loading result.

Example:

// Wait for page to finish loading, maximum 5 seconds
await modelQt.getWebEngine("WebView").loaded(5);

// Immediately check if page is loaded
let isLoaded = await modelQt.getWebEngine("WebView").loaded();
console.log(`Page loaded: ${isLoaded}`);

# Wait for page to finish loading, maximum 5 seconds
modelQt.getWebEngine("WebView").loaded(5)

# Immediately check if page is loaded
is_loaded = modelQt.getWebEngine("WebView").loaded()
print(f"Page loaded: {is_loaded}")