Basic Control Objects

In the previous article, we learned about container classes and control base classes in CukeTest. Next is the API introduction for various specific control classes. This article will introduce the following basic control classes:

• Button
• Window
• Edit/Document/Text/Spinner
• RadioButton
• CheckBox
• ComboBox
• Spinner
• ScrollBar
• Image
• Hyperlink
• Slider
• MenuBar & Menu & MenuItem
• Tab & TabItem

Since each control class inherits from IWinControl, every control class possesses all action and property methods of Common Controls. Taking CheckBox control class as an example:

The CheckBox control has one action method — toggleCheck() used to set the check state; one property method checkState() used to determine the check state of the CheckBox. true indicates checked, false indicates unchecked, and indeterminate indicates an intermediate state:

export interface IWinCheckBox extends IWinControl {    
	toggleCheck(checkState: boolean | 'indeterminate'): Promise<void>
	checkState(): Promise<boolean | 'indeterminate'>
}

class WinCheckBox(WinControl):
	def check(checked: bool) -> None
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None

But actually, besides these two methods, CheckBox also inherits all methods from the IWinControl base class. So CheckBox methods should effectively include Base Class Methods:

export interface IWinCheckBox extends IWinControl {
	
	// CheckBox action methods
	toggleCheck(checkState: boolean): Promise<void>
	// Inherited base class action methods
	click(x?: number, y?: number, mousekey?: MouseKey): Promise<void>;
	dblClick(x?: number, y?: number, mousekey?: MouseKey): Promise<void>;
	moveMouse(x?: number, y?: number, seconds?: number): Promise<void>
	wheel(value: number): Promise<void>;
	exists(time?: number): Promise<boolean>;
	hScroll(value: number | ScrollAmount): Promise<void>;
	vScroll(value: number | ScrollAmount): Promise<void>;
	property(propertyIds: PropertyIds | string): Promise<string | boolean | number | Rect>;
	checkImage(options?: CompareOptions): Promise<void>;
	checkProperty(propertyName: string, expectedValue: string | number | boolean | RegExp, message: string): Promise<void>;
	checkProperty(propertyName: string, expectedValue: string | number | boolean | RegExp, options: {message: string, operation: any}): Promise<void>;
	waitProperty(propertyIds: PropertyIds, value: string, timeoutSeconds?: number/* default value 5 seconds */): Promise<boolean>;
	drop(x?: number, y?: number, seconds?: number): Promise<void>;
	drag(x?: number, y?: number): Promise<void>;
	pressKeys(keys: string, opt?: PressKeysOptions | number): Promise<void>;
	takeScreenshot(filePath?: string): Promise<void | string>;
	highlight(duration?: number);
	firstChild(controlType?: ControlType): Promise<IWinControl>;
	lastChild(controlType?: ControlType): Promise<IWinControl>;
	next(controlType?: ControlType): Promise<IWinControl>;
	previous(controlType?: ControlType): Promise<IWinControl>;
	parent(): Promise<IWinControl>;
	all(): Promise<IWinControl[]>;
	findControls(...conditions: ConditionFilter[]): Promise<IWinControl[]>; //used to be getControls
	modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string | Buffer>;  //base64 is the default
	modelProperties(all?: boolean): {[x: string]: any};
	allProperties(): Promise<object>;
	doDefaultAction(): Promise<void>;
	rawText(): Promise<string>

	// CheckBox properties
	checkState(): Promise<boolean>
	// Inherited base class property methods
	type(): Promise<string>;
	text(): Promise<string>;
	name(): Promise<string>;
	hwnd(): Promise<number>;
	x(): Promise<number>;
	y(): Promise<number>;
	height(): Promise<number>;
	width(): Promise<number>;
	enabled(): Promise<boolean>;
	focused(): Promise<boolean>;
	helpText(): Promise<string>;
	labeledText(): Promise<string>;
	value(): Promise<string | number>;
	processId(): Promise<number>;
	rect(): Promise<Rect>;
	visible(): Promise<boolean>;
}

If an object does not contain any specific action and property methods, it means it only applies methods from its base class — IWinControl and IWinContainer, without its own unique ones, such as Button Control.

Basic Control Introduction

Button Control: Button

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

export interface IWinButton extends IWinControl {

}

class WinButton(WinControl):
	...

Since the Button control's action and property methods are consistent with the base class IWinControl, having no unique methods of its own, it is empty here. For its action methods, please refer to the Base Class Methods introduction.

Window Control: Window

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

export interface IWinWindow extends IWinControl {
	activate(): Promise<void>;
	close(): Promise<void>;
	maximize(): Promise<void>;
	minimize(): Promise<void>;
	restore(): Promise<void>;
	isModal(): Promise<boolean>;
	interactionState(): Promise<string>;
	visualState(): Promise<string>;
}

class WinWindow(WinControl):
	def activate() -> None
	def close() -> None
	def maximize() -> None
	def minimize() -> None
	def restore() -> None
	def isModal() -> bool
	def interactionState() -> str
	def visualState() -> str

activate()

Activates the target window, bringing it to the top of the desktop to avoid being covered by other windows.

Returns:

• Asynchronous method that returns no value.

Example

// Activate Notepad window, bringing it to front
await model.getWindow("Notepad").activate();

# Activate Notepad window, bringing it to front
model.getWindow("Notepad").activate()

close()

Closes the target window.

Returns:

• Asynchronous method that returns no value.

Example

// Close Notepad window
await model.getWindow("Notepad").close();

# Close Notepad window
model.getWindow("Notepad").close()

maximize()

Maximizes the target window.

Returns:

• Asynchronous method that returns no value.

Example

// Maximize Notepad window
await model.getWindow("Notepad").maximize();

# Maximize Notepad window
model.getWindow("Notepad").maximize()

minimize()

Minimizes the target window.

Returns:

• Asynchronous method that returns no value.

Example

// Minimize Notepad window
await model.getWindow("Notepad").minimize();

# Minimize Notepad window
model.getWindow("Notepad").minimize()

restore()

Restores the target window. Use this method to restore the window to normal state after it has been minimized.

Returns:

• Asynchronous method that returns no value.

Example

// Minimize window first
await model.getWindow("Notepad").minimize();
// Then restore window to normal state
await model.getWindow("Notepad").restore();

# Minimize window first
model.getWindow("Notepad").minimize()
# Then restore window to normal state
model.getWindow("Notepad").restore()

isModal()

Gets whether the specified window is a modal window. isModal returning false does not necessarily mean the window is not a modal window; it is recommended to use interactionState for judgment.

Returns:

• boolean type. Asynchronously returns a boolean value (true or false), indicating whether the window is a modal window. If the return value is true, it means the window is a modal window; if the return value is false, it means the window may not be a modal window.

Example

// Check if File Explorer window is modal
let isModal = await model.getWindow("FileExplorer").isModal();
console.log(`Is window modal: ${isModal}`);

# Check if File Explorer window is modal
is_modal = model.getWindow("FileExplorer").isModal()
print(f"Is window modal: {is_modal}")

interactionState()

Indicates the interaction state of the window.

Returns:

• string type. Return values can be:
  • Running: The window is running. This does not guarantee that the window is ready for user interaction or is responding.
  • ReadyForUserInteraction: The window is ready for user interaction.
  • BlockedByModalWindow: The window is blocked by a modal window.
  • Closing: The window is closing.
  • NotResponding: The window is not responding.

Example

// Check window interaction state
let state = await model.getWindow("Notepad").interactionState();
console.log(`Window interaction state: ${state}`);

# Check window interaction state
state = model.getWindow("Notepad").interactionState()
print(f"Window interaction state: {state}")

visualState()

Indicates the current visual state of the window.

Returns:

• string type, Minimized, Maximized or Normal.

Example

// Get window visual state
let state = await model.getWindow("Notepad").visualState();
console.log(`Window visual state: ${state}`);

# Get window visual state
state = model.getWindow("Notepad").visualState()
print(f"Window visual state: {state}")

Comprehensive Example

Open Notepad in Windows environment, click [File] on the menu bar and select [Open] to open the File Explorer window:

let isModal;
let interactionState;
let visualState;

// Check if File Explorer is a modal window
isModal = await model.getWindow("FileExplorer").isModal();
console.log(isModal); // Returns true

// Check File Explorer interaction state
interactionState = await model.getWindow("FileExplorer").interactionState();
console.log(interactionState); // Returns ReadyForUserInteraction

// Check Notepad interaction state (blocked by modal window)
interactionState = await model.getWindow("Notepad").interactionState();
console.log(interactionState); // Returns BlockedByModalWindow

// Check File Explorer visual state
visualState = await model.getWindow("FileExplorer").visualState();
console.log(visualState); // Returns Normal

# Check if File Explorer is a modal window
is_modal = model.getWindow("FileExplorer").isModal()
print(is_modal)  # Returns True

# Check File Explorer interaction state
interaction_state = model.getWindow("FileExplorer").interactionState()
print(interaction_state)  # Returns ReadyForUserInteraction

# Check Notepad interaction state (blocked by modal window)
interaction_state = model.getWindow("Notepad").interactionState()
print(interaction_state)  # Returns BlockedByModalWindow

# Check File Explorer visual state
visual_state = model.getWindow("FileExplorer").visualState()
print(visual_state)  # Returns Normal

Input Box Control: Edit & Document

For Edit controls used to receive user input, and sometimes Document for multi-line input boxes. The provided action and property methods target the values in the input box.

export interface IWinEdit extends IWinControl {
	set(value: string): Promise<void>;
	clearAll(): Promise<void>;
	readOnly(): Promise<boolean>;
}
export interface IWinDocument extends IWinControl {
	set(value: string): Promise<void>;
	clearAll(): Promise<void>;
	readOnly(): Promise<boolean>;
}

class WinEdit(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool
class WinDocument(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool

export interface IWinText extends IWinControl {
	set(value: string): Promise<void>;
}
export interface IWinPane extends IWinControl {
	set(value: string): Promise<void>;
}

class WinText(WinControl):
	def set(value: str) -> None
class WinPane(WinControl):
	def set(value: str) -> None

set(value)

Sets the value in the input box. Replaces the value in the target input box with the passed string.

Parameters:

• value: string type, the value expected to be written to the input box.

Returns:

• Asynchronous method that returns no value.

Example

// Enter text in username input box
await model.getEdit("Username").set("admin");

# Enter text in username input box
model.getEdit("Username").set("admin")

clearAll()

Clears the value in the input box.

Returns:

• Asynchronous method that returns no value.

Example

// Clear input box content
await model.getEdit("Username").clearAll();

# Clear input box content
model.getEdit("Username").clearAll()

readOnly()

Whether the current input box is read-only. Returns true for read-only, false for writable.

Returns:

• boolean type, asynchronously returns whether the input box is read-only.

Example

// Check if input box is read-only
let isReadOnly = await model.getEdit("Username").readOnly();
if (!isReadOnly) {
	// If not read-only, input content
	await model.getEdit("Username").set("admin");
}

# Check if input box is read-only
is_read_only = model.getEdit("Username").readOnly()
if not is_read_only:
	# If not read-only, input content
	model.getEdit("Username").set("admin")

RadioButton Control: RadioButton

For the RadioButton control, methods for selecting and getting the selection state are provided according to usage logic.

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

class WinRadioButton(WinControl):
	def checked() -> Union[bool, str]
	def check() -> None

check()

Selects the target radio button.

Returns:

• Asynchronous method that returns no value.

Example

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

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

checked()

Gets the selection state of the target radio button, true for selected, false for unselected.

Returns:

• boolean type, asynchronously returns whether the target radio button is selected.

Example

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

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

CheckBox Control: CheckBox

For the CheckBox control, you can directly set the check state, and of course, get the state.

export interface IWinCheckBox extends IWinControl {
	toggleCheck(checkState: boolean | 'indeterminate'): Promise<void>
	checkState(): Promise<boolean | 'indeterminate'>
}

class WinCheckBox(WinControl):
	def check(checked: bool) -> None
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None

toggleCheck(checkState)

Sets the check state of the target checkbox.

Parameters:

• checkState: boolean | 'indeterminate' type. true for checked, false for unchecked, 'indeterminate' for intermediate state.

Returns:

• Asynchronous method that returns no value.

Example

// Check the checkbox
await model.getCheckBox("Remember Password").toggleCheck(true);

// Uncheck the checkbox
await model.getCheckBox("Remember Password").toggleCheck(false);

// Set to intermediate state (if supported)
await model.getCheckBox("Select All").toggleCheck('indeterminate');

# Check the checkbox
model.getCheckBox("Remember Password").toggleCheck(True)

# Uncheck the checkbox
model.getCheckBox("Remember Password").toggleCheck(False)

# Set to intermediate state (if supported)
model.getCheckBox("Select All").toggleCheck('indeterminate')

checkState()

Gets the check state of the target checkbox.

Returns:

• boolean | 'indeterminate' type, asynchronously returns the state of the checkbox.

Example

// Get checkbox state
let state = await model.getCheckBox("Remember Password").checkState();
if (state === true) {
	console.log("Checkbox is checked");
} else if (state === false) {
	console.log("Checkbox is unchecked");
} else {
	console.log("Checkbox is in intermediate state");
}

# Get checkbox state
state = model.getCheckBox("Remember Password").checkState()
if state == True:
	print("Checkbox is checked")
elif state == False:
	print("Checkbox is unchecked")
else:
	print("Checkbox is in intermediate state")

ComboBox Control: ComboBox

For the ComboBox control, which acts as a special input box with a drop-down list, methods for selecting specified drop-down options are provided.

export interface IWinComboBox extends IWinControl {
	open(): Promise<void>;
	select(nameOrIndex: String | number): Promise<void>;
	options(index: number): Promise<string | string[]>;
	itemCount(): Promise<number>;
	selectedName(): Promise<string>;
}

class WinComboBox(WinControl):
	def options(index: Optional[int]=None) -> Union[str, List[str]]
	def itemCount() -> int
	def selectedName() -> str
	def select(value: Union[str, int]) -> None
	def open() -> None

open()

Expands the drop-down list. Can be seen as triggering the ▼ button on the right side of the target.

Returns:

• Asynchronous method that returns no value.

Example

// Expand combo box
await model.getComboBox("City Select").open();

# Expand combo box
model.getComboBox("City Select").open()

select(nameOrIndex)

Selects a specified option in the drop-down list.

Parameters:

• nameOrIndex: number or string type. If it is a number, the option at the corresponding index position in the drop-down list will be selected; if it is a string, the option with the corresponding name in the drop-down list will be selected.

Returns:

• Asynchronous method that returns no value.

Example

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

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

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

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

selectedName()

Gets the currently selected value.

Returns:

• string type, asynchronously returns the currently selected value.

Example

// Get currently selected option
let selected = await model.getComboBox("City Select").selectedName();
console.log(`Currently selected: ${selected}`);

# Get currently selected option
selected = model.getComboBox("City Select").selectedName()
print(f"Currently selected: {selected}")

options()

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

Returns:

• string[] type, asynchronously returns a string array consisting of names of all available options.

Example

// Get all options
let allOptions = await model.getComboBox("City Select").options();
console.log(`Available options: ${allOptions.join(', ')}`);

# Get all options
all_options = model.getComboBox("City Select").options()
print(f"Available options: {', '.join(all_options)}")

itemCount()

Gets the count of all available options in the target combo box. Can be understood as the length of the array returned by options() method.

Returns:

• number type, asynchronously returns the number of options.

Example

// Get item count
let count = await model.getComboBox("City Select").itemCount();
console.log(`Total items: ${count}`);

# Get item count
count = model.getComboBox("City Select").itemCount()
print(f"Total items: {count}")

Spinner Control: Spinner

For the Spinner control with up and down arrows in applications, it provides input, edit, and clear methods similar to the Edit control. It also provides operation APIs for incrementing/decrementing values by a single step.

The type definition of this control is as follows:

export interface IWinSpinner extends IWinEdit {
	set(value: string): Promise<void>;
	clearAll(): Promise<void>;
	readOnly(): Promise<boolean>;
	increment(): Promise<void>;
	decrement(): Promise<void>;
}

class WinSpinner(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool
	def increment() -> None
	def decrement() -> None

set(value)

See set() method. Inputting a string might fail because the control usually only accepts numeric arguments.

You can also use pressKeys() method to complete the input.

clearAll()

See clearAll() method.

readOnly()

See readOnly() method.

increment()

Increments the value of the spinner by one unit. The unit size depends on the setting in the application. It can be understood as triggering the up arrow in the spinner once.

Returns:

• Asynchronous method that returns no value.

Example

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

# Increment value
model.getSpinner("Quantity").increment()
# Increment continuously multiple times
for i in range(5):
	model.getSpinner("Quantity").increment()

decrement()

Decrements the value of the spinner by one unit. The unit size depends on the setting in the application. It can be understood as triggering the down arrow in the spinner once.

Returns:

• Asynchronous method that returns no value.

Example

// Decrement value
await model.getSpinner("Quantity").decrement();
// Decrement continuously multiple times
for (let i = 0; i < 3; i++) {
	await model.getSpinner("Quantity").decrement();
}

# Decrement value
model.getSpinner("Quantity").decrement()
# Decrement continuously multiple times
for i in range(3):
	model.getSpinner("Quantity").decrement()

Slider Control: Slider

Slider control used for sliding to adjust values.

export interface WinSlider extends WinControl {
	setPosition(value: number): Promise<void>;
	position(): Promise<number>;
	maximum(): Promise<number>;
	minimum(): Promise<number>;
	readOnly(): Promise<boolean>;
}

setPosition(value)

Adjusts the value of the slider. Cannot exceed the maximum value.

Parameters:

• value: number type, the target value of the slider.

Returns:

• Asynchronous method that returns no value.

Example

// Set slider value to 50
await model.getSlider("Volume").setPosition(50);

# Set slider value to 50
model.getSlider("Volume").setPosition(50)

position()

Gets the value of the slider.

Returns:

• number type, asynchronously returns the current value of the slider.

Example

// Get current slider value
let currentValue = await model.getSlider("Volume").position();
console.log(`Current Volume: ${currentValue}`);

# Get current slider value
current_value = model.getSlider("Volume").position()
print(f"Current Volume: {current_value}")

maximum()

Gets the maximum value of the slider.

Returns:

• number type, asynchronously returns the maximum value of the slider.

Example

// Get maximum slider value
let maxValue = await model.getSlider("Volume").maximum();
console.log(`Maximum Value: ${maxValue}`);

# Get maximum slider value
max_value = model.getSlider("Volume").maximum()
print(f"Maximum Value: {max_value}")

minimum()

Gets the minimum value of the slider.

Returns:

• number type, asynchronously returns the minimum value of the slider.

Example

// Get minimum slider value
let minValue = await model.getSlider("Volume").minimum();
console.log(`Minimum Value: ${minValue}`);

# Get minimum slider value
min_value = model.getSlider("Volume").minimum()
print(f"Minimum Value: {min_value}")

readOnly()

Whether the slider is adjustable.

Returns:

• boolean type, asynchronously returns whether it is adjustable.

Example

// Check if slider is adjustable
let isReadOnly = await model.getSlider("Volume").readOnly();
if (!isReadOnly) {
	// If adjustable, set value
	await model.getSlider("Volume").setPosition(75);
}

# Check if slider is adjustable
is_read_only = model.getSlider("Volume").readOnly()
if not is_read_only:
	# If adjustable, set value
	model.getSlider("Volume").setPosition(75)

ScrollBar Control: ScrollBar

For scrolling within a scrollable area, recognizing the scrollbar control within that area and then calling methods on the scrollbar to complete the scrolling operation is often a very convenient choice.

The scrollbar control is actually a special type of slider.

The type definition is as follows:

export interface IWinScrollBar extends IWinControl {
	setValue(value: number): void; 
	isTop(): Promise<boolean>;
	isBottom(): Promise<boolean>;
	lineUp(): Promise<void>;
	lineDown(): Promise<void>;
	pageUp(): Promise<void>;
	pageDown(): Promise<void>;
	scrollToTop(): Promise<void>;
	scrollToBottom(): Promise<void>;
}

class WinScrollBar(WinControl):
	def setValue(value: int) -> None
	def isTop() -> bool
	def isBottom() -> bool
	def lineUp() -> None
	def lineDown() -> None
	def pageUp() -> None
	def pageDown() -> None
	def scrollToTop() -> None
	def scrollToBottom() -> None

setValue(value)

Sets the value of the scrollbar, dragging the slider to the position of the specified value, but it will not exceed the maximum value. The unit can be understood as the number of notches.

Parameters:

• value: number type, drag the slider to the specified value position.

Returns:

• Asynchronous method that returns no value.

Example

// Set scrollbar position
await model.getScrollBar("Vertical ScrollBar").setValue(100);

# Set scrollbar position
model.getScrollBar("Vertical ScrollBar").setValue(100)

lineUp()

Scrolls up/left by one unit. The unit can be treated as wheel notches, which is the amount scrolled by pressing the up/left arrow key once.

Returns:

• Asynchronous method that returns no value.

Example

// Scroll up one line
await model.getScrollBar("Vertical ScrollBar").lineUp();

# Scroll up one line
model.getScrollBar("Vertical ScrollBar").lineUp()

lineDown()

Scrolls down/right by one unit. The unit can be treated as wheel notches, which is the amount scrolled by pressing the down/right arrow key once.

Returns:

• Asynchronous method that returns no value.

Example

// Scroll down one line
await model.getScrollBar("Vertical ScrollBar").lineDown();

# Scroll down one line
model.getScrollBar("Vertical ScrollBar").lineDown()

pageUp()

Scrolls up/left by one page, which is the amount scrolled by pressing the PageUp key once.

Returns:

• Asynchronous method that returns no value.

Example

// Page up
await model.getScrollBar("Vertical ScrollBar").pageUp();

# Page up
model.getScrollBar("Vertical ScrollBar").pageUp()

pageDown()

Scrolls down/right by one page, which is the amount scrolled by pressing the PageDown key once.

Returns:

• Asynchronous method that returns no value.

Example

// Page down
await model.getScrollBar("Vertical ScrollBar").pageDown();

# Page down
model.getScrollBar("Vertical ScrollBar").pageDown()

scrollToTop()

Scrolls the scrollbar to the top.

Returns:

• Asynchronous method that returns no value.

Example

// Scroll to top
await model.getScrollBar("Vertical ScrollBar").scrollToTop();

# Scroll to top
model.getScrollBar("Vertical ScrollBar").scrollToTop()

scrollToBottom()

Scrolls the scrollbar to the bottom.

Returns:

• Asynchronous method that returns no value.

Example

// Scroll to bottom
await model.getScrollBar("Vertical ScrollBar").scrollToBottom();

# Scroll to bottom
model.getScrollBar("Vertical ScrollBar").scrollToBottom()

isTop()

Whether the scrollbar is at the top.

Returns:

• boolean type, asynchronously returns whether the scrollbar is at the top.

Example

// Check if at top
let atTop = await model.getScrollBar("Vertical ScrollBar").isTop();
if (atTop) {
	console.log("Already at the top");
}

# Check if at top
at_top = model.getScrollBar("Vertical ScrollBar").isTop()
if at_top:
	print("Already at the top")

isBottom()

Whether the scrollbar is at the bottom.

Returns:

• boolean type, asynchronously returns whether the scrollbar is at the bottom.

Example

// Check if at bottom
let atBottom = await model.getScrollBar("Vertical ScrollBar").isBottom();
if (atBottom) {
	console.log("Already at the bottom");
}

# Check if at bottom
at_bottom = model.getScrollBar("Vertical ScrollBar").isBottom()
if at_bottom:
	print("Already at the bottom")

Image Control: Image

Image control.

export interface IWinImage extends IWinControl {    
	visualText(): Promise<string>;
}

visualText()

Uses OCR to recognize text in the image.

Returns:

• string type, asynchronously returns text content in the image control.

Example

// Use OCR to recognize text in image
let text = await model.getImage("Captcha").visualText();
console.log(`Recognized text: ${text}`);

# Use OCR to recognize text in image
text = model.getImage("Captcha").visualText()
print(f"Recognized text: {text}")

Hyperlink Control: Link/HyperLink

Hyperlink control.

export interface IWinLink extends IWinControl {    
	url(): Promise<string>;
}
export interface IWinHyperlink extends IWinLink {    
}

url()

Gets the address pointed to by the hyperlink.

Returns:

• string type, asynchronously returns the address of the link.

Example

// Get URL of hyperlink
let linkUrl = await model.getHyperlink("Help Docs").url();
console.log(`Link Address: ${linkUrl}`);

# Get URL of hyperlink
link_url = model.getHyperlink("Help Docs").url()
print(f"Link Address: {link_url}")

Menu Related Controls: MenuBar & Menu & MenuItem

For menu-related operations in applications, there are three controls: MenuBar, Menu, and MenuItem. The first two are container controls (Menu Bar container and Expanded Menu container), while the actual clickable options are MenuItem controls.

MenuBar Control Methods:

Menu Control Methods:

MenuItem Control Methods:

export interface IWinMenuBar extends IWinControl {    
	itemNames(index:number) : Promise<string>;
	open(itemNameOrIndex: string | number): Promise<void>;
	//Get the menu item count
	itemCount(): Promise<number>;
}
export interface IWinMenu extends IWinControl {
	select(menuPath: string): Promise<boolean>;  
	
	itemCount(menuPath:string): Promise<number>; 
	itemName(menuPath:string): Promise<string>;
	itemNames(): Promise<string[]>;
}
export interface IWinMenuItem extends IWinControl {
	invoke(): Promise<void>;
	open(): Promise<void>
}

class WinMenuBar(WinControl):
	def itemNames(index: int) -> str
	def open(itemNameOrndex: Union[str, int]) -> None
	def itemCount() -> int
class WinMenu(WinControl):
	def itemCount(menuPath: str) -> int
	def itemName(menuPath: str) -> str
	def itemNames() -> List[str]
	def select(menuPath: str) -> bool
class WinMenuItem(WinControl):
	def invoke() -> None
	def open() -> None

itemNames(index)

Gets the name of the menu item at the target index.

Parameters:

• index: number type, index value of the target menu item.

Returns:

• string type, asynchronously returns the name of the menu item corresponding to the target index.

Example

// Get name of the first menu item
let menuName = await model.getMenuBar("MenuBar").itemNames(0);
console.log(`Menu Item Name: ${menuName}`);

# Get name of the first menu item
menu_name = model.getMenuBar("MenuBar").itemNames(0)
print(f"Menu Item Name: {menu_name}")

open(itemNameOrIndex)

Expands the target menu item.

Parameters:

• itemNameOrIndex: number or string type, the index or name of the target menu item.

Returns:

• Asynchronous method that returns no value.

Example

// Expand menu by name
await model.getMenuBar("MenuBar").open("File");

// Expand menu by index
await model.getMenuBar("MenuBar").open(0);

# Expand menu by name
model.getMenuBar("MenuBar").open("File")

# Expand menu by index
model.getMenuBar("MenuBar").open(0)

itemCount()

Gets the count of menu items in the menu bar.

Returns:

• number type, asynchronously returns the number of menu items.

Example

// Get item count in menu bar
let count = await model.getMenuBar("MenuBar").itemCount();
console.log(`Total Menu Items: ${count}`);

# Get item count in menu bar
count = model.getMenuBar("MenuBar").itemCount()
print(f"Total Menu Items: {count}")

Menu API Introduction

itemCount()

Gets the count of menu items in the menu container.

Returns:

• number type, asynchronously returns the number of menu items.

Example

// Get item count in menu
let count = await model.getMenu("File").itemCount();
console.log(`Total Menu Items: ${count}`);

# Get item count in menu
count = model.getMenu("File").itemCount()
print(f"Total Menu Items: {count}")

itemName(menuPath)

Gets the name of the menu item at the target index.

Parameters:

• menuPath: number type, index of the target menu item.

Returns:

• string type, asynchronously returns the name of the menu item corresponding to the target index.

Example

// Get name of menu item at specific index
let itemName = await model.getMenu("File").itemName(0);
console.log(`Menu Item Name: ${itemName}`);

# Get name of menu item at specific index
item_name = model.getMenu("File").itemName(0)
print(f"Menu Item Name: {item_name}")

itemNames()

Gets the names of all menu items.

Returns:

• string[] type, asynchronously returns names of all menu items in the menu.

Example

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

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

select(menuPath)

Selects the target menu item.

Parameters:

• menuPath: string type, path to the target menu item.

Returns:

• boolean type, asynchronously returns whether the target was successfully selected.

Example

// Select specific menu item
let success = await model.getMenu("File").select("New");
if (success) {
	console.log("Menu Item Selected Successfully");
}

# Select specific menu item
success = model.getMenu("File").select("New")
if success:
	print("Menu Item Selected Successfully")

MenuItem API Introduction

open()

Expands the menu container where the menu item resides.

Returns:

• Asynchronous method that returns no value.

Example

// Expand menu item
await model.getMenuItem("File").open();

# Expand menu item
model.getMenuItem("File").open()

invoke()

Clicks/Triggers the menu item. It is recommended to use open() method to expand the menu first, then click.

Returns:

• Asynchronous method that returns no value.

Example

// Expand menu first, then click menu item
await model.getMenuItem("File").open();
await model.getMenuItem("New").invoke();

# Expand menu first, then click menu item
model.getMenuItem("File").open()
model.getMenuItem("New").invoke()

Clicking Sub-menus: For some sub-menus that require hovering to expand before they can be clicked, you can first call .moveMouse() common method on the parent menu item to move the mouse to that position, then click the sub-menu. This is because the mouse trajectory between two clicks is indeterminate, and some controls' clicks do not move the mouse. If you need the mouse cursor to appear at a specific position, it is best to use .moveMouse() to manually move the cursor.

Tab Related Controls: Tab & TabItem

For tab controls in applications, Tab and TabItem, to switch tabs.

Tab Control Methods:

TabItem Control Methods:

The definition of the tab control is as follows:

export interface IWinTab extends IWinControl {
	activate(nameOrIndex: string | number): Promise<void>;
	tabNames(index: number): Promise<string[] | string>;
	findItem(nameOrIndex: string | number): Promise<IWinTabItem>;

	activeName(): Promise<string>;
	activeIndex(): Promise<number>;
	count(): Promise<number>;
}
export interface IWinTabItem extends IWinControl {
	activate(): Promise<void>;
	text(): Promise<string>;
	itemIndex(): Promise<number>;
}

class WinTab(WinControl):
	def activate(nameOrndex: Union[str, int]) -> None
	def tabNames(index: Optional[int]=None) -> Union[str, List[str]]
	def findItem(nameOrndex: Union[str, int]) -> "WinTabItem"
	def select(item: Union[str, int]) -> None
	def activeName() -> str
	def activendex() -> int
	def count() -> int
class WinTabItem(WinControl):
	def activate() -> None
	def text() -> str
	def itemndex() -> int

findItem(itemNameOrIndex)

Gets the automation object of the specified tab, passing the index or title of the tab.

Parameters:

• itemNameOrIndex: number or string type, index value or title of the target tab.

Returns:

• TabItem type, synchronously returns a TabItem type operation object.

Example

// Get specified tab item object
let tabItem = await model.getTab("TabBar").findItem("Home");

# Get specified tab item object
tab_item = model.getTab("TabBar").findItem("Home")

activate(itemNameOrIndex)

Activates the target tab, passing the index value or title of the tab.

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

Parameters:

• itemNameOrIndex: number or string type, index value or title of the target tab.

Returns:

• Asynchronous method that returns no value.

Example

// Activate tab by name
await model.getTab("TabBar").activate("Settings");

// Activate tab by index
await model.getTab("TabBar").activate(1);

# Activate tab by name
model.getTab("TabBar").activate("Settings")

# Activate tab by index
model.getTab("TabBar").activate(1)

activeIndex()

Gets the index of the currently active tab.

Returns:

• number type, asynchronously returns the tab index.

Example

// Get current active tab index
let index = await model.getTab("TabBar").activeIndex();
console.log(`Current active tab index: ${index}`);

# Get current active tab index
index = model.getTab("TabBar").activeIndex()
print(f"Current active tab index: {index}")

activeName()

Gets the name of the currently active tab.

Returns:

• string type, asynchronously returns the name of the tab.

Example

// Get current active tab name
let name = await model.getTab("TabBar").activeName();
console.log(`Current active tab: ${name}`);

# Get current active tab name
name = model.getTab("TabBar").activeName()
print(f"Current active tab: {name}")

tabNames(index)

Gets the titles of all tabs. If a number is passed, it gets the title of the tab at the corresponding index.

Parameters:

• index: number type, index of the target tab, default is -1, which gets all titles.

Returns:

• When index is -1, it returns string[], which is a string array composed of all tab titles; when index is other values, it returns string, the title of the tab corresponding to the target index.

Example

// Get all tab titles
let allTabs = await model.getTab("TabBar").tabNames(-1);
console.log(`All tabs: ${allTabs.join(', ')}`);

// Get tab title at specific index
let tabName = await model.getTab("TabBar").tabNames(0);
console.log(`First tab: ${tabName}`);

# Get all tab titles
all_tabs = model.getTab("TabBar").tabNames(-1)
print(f"All tabs: {', '.join(all_tabs)}")

# Get tab title at specific index
tab_name = model.getTab("TabBar").tabNames(0)
print(f"First tab: {tab_name}")

count()

Gets the number of tabs in the tab bar.

Returns:

• number type, asynchronously returns the number of tabs.

Example

// Get total count of tabs
let count = await model.getTab("TabBar").count();
console.log(`Total tabs: ${count}`);

# Get total count of tabs
count = model.getTab("TabBar").count()
print(f"Total tabs: {count}")

The following are methods of TabItem object.

activate()

Activates the tab page.

Returns:

• Asynchronous method that returns no value.

Example

// Activate specified tab item
await model.getTabItem("Settings").activate();

# Activate specified tab item
model.getTabItem("Settings").activate()

text()

Overrides the text() method of the base class to get the tab title.

Returns:

• string type, returns the title of the tab.

Example

Verify the obtained tab title:

// Get tab title and verify
let title = await model.getTabItem("One").text();
assert.equal(title, 'One');

# Get tab title and verify
title = model.getTabItem("One").text()
assert title == 'One'

itemIndex()

Gets the index of the tab in the entire tab bar.

Returns:

• number type, asynchronously returns the index of the tab.

Example

// Get index position of the tab
let index = await model.getTabItem("Settings").itemIndex();
console.log(`Tab index: ${index}`);

# Get index position of the tab
index = model.getTabItem("Settings").itemIndex()
print(f"Tab index: {index}")