Basic Controls' API

In the previous article, we learned about the container class and control base class in CukeTest, and then introduced the APIs for various control classes. This article will introduce the following basic control classes:

• Button
• Window
• Label
• Edit
• RadioButton
• CheckBox
• ComboBox
• SpinBox
• Application
• ProgressBar
• Dial
• Slider
• ScrollArea
• MenuBar & MenuBarItem
• Menu & MenuItem
• Tab & TabItem
• GraphicsView & GraphicsItem

The relatively complex control classes are as follows. Since they contain many methods, they are placed in other documents. Please click the link to jump according to your needs:

• list type object: Introducing the list control List and the list item control ListItem;
• tree type object: Introducing the tree control Tree and the tree node control TreeItem;
• table type object: Introducing the table control Table and the cell control TableItem;

As well as the base class custom view ItemView control of the above three complex controls, for the custom components derived from the AbstractView abstract view in Qt applications, the introduction is as follows:

• custom view object: Introducing the custom view control ItemView and the custom item control ItemViewItem;

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 - check() is used to set whether to check or clear the check; a property method checked() is 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> 
}

Introduction to Basic Controls' API

Button

For common 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(): Promise<string>

Get the content on the button.

• Return value: Promise<string> type, you need to use the await keyword to retrieve the result.

Window

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(): Promise<void>

Activate the target window so that the target window appears at the top of the desktop and avoids being covered by other windows.

• Return value: an asynchronous method that does not return any value.

  Since the desktop operation automation between CukeTest and Qt is realized through communication, the automatic operation will not fail because the Qt window is covered.

close(): Promise<void>

Close the target window.

• Return value: an asynchronous method that does not return any value.

maximize(): Promise<void>

Maximizes the target window.

• Return value: an asynchronous method that does not return any value.

minimize(): Promise<void>

Minimizes the target window.

• Return value: an asynchronous method that does not return any value.

restore(): Promise<void>

Restores the target window. This method can be used to restore the normal state after the target is minimized.

• Return value: an asynchronous method that does not return any value.

Label

For the label control Label used to mark other controls or display fixed content, there is no operation method, only one own property method:

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

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

text(): Promise<string>

Get the current value of the tag.

• Return value: Promise<string> type, you need to use the await keyword to retrieve the result.

Edit

For the input box control Edit used to receive user input, there is no distinction between a single-line input box and a multi-line input box. The provided operation method and attribute method are all for the value in the input box.

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): Promise<void>

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

• value: String type, the value expected to be written into the input box;
• Return value: an asynchronous method that does not return any value.

clearAll(): Promise<void>

Clears the value in the input box.

• Return value: an asynchronous method that does not return any value.

value(): Promise<string>

Get the value in the current input box and return it.

• Return value: Promise<string> type, you need to use the await keyword to retrieve the result.

RadioButton

For the RatioButton control of a radio button, methods for selecting and obtaining the selected state are provided according to the usage logic.

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

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

check(): Promise<void>

Check the Target radio button.

• Return value: an asynchronous method that does not return any value.

checked(): Promise<boolean>

Get the selected state of the target radio button, true means it is selected, false means it is not selected.

• Return value: Promise<boolean> type, representing whether the target checkbox is selected. You need to use the await keyword to retrieve the result.

CheckBox

For the CheckBox control of the check box control, the selected state can be directly set, and of course the state can also be obtained.

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): Promise<void>

Sets the checked state of the target checkbox.

• checkState: Boolean type, true means to select the check box, false means to uncheck the target check box, patial means to partially select, usually not used.
• Return value: an asynchronous method that does not return any value.

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

Get the selected state of the target radio button, true means it is selected, false means it is not selected.

• Return value: Promise<boolean | 'partial'> type, representing whether the target checkbox is selected. You need to use the await keyword to retrieve the result.

ComboBox

For the ComboBox control of a type of special input box with a drop-down box, an operation method for selecting the specified drop-down option is provided.

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(): Promise<void>

Expanding the drop-down box can be regarded as triggering the ▼ button on the right side of the target.

• Return value: an asynchronous method that does not return any value.

select(nameOrIndex): Promise<void>

• nameOrIndex: number or String type. If it is a number, the option at the corresponding index position in the drop-down box will be selected; if it is a string, the option with the corresponding name in the drop-down box will be selected.
• Return value: an asynchronous method that does not return any value.

selectedIndex(): Promise<number>

Get the position of the currently selected value in the drop-down box.

• Return value: Promise<number> type, representing the position of the current value in the drop-down box. You need to use the await keyword to retrieve the result.

selectedItem(): Promise<string>

Get the currently selected value.

• Return value: Promise<string> type, representing the currently selected value. You need to use the await keyword to retrieve the result.

itemsToSelect(): Promise<string[]>

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

• Return value: Promise<string[]> type, that is, an array of strings, to obtain the names of all selectable options in the target combo box. You need to use the await keyword to retrieve the result.

SpinBox

For the SpinBox control with up and down arrows in the application, it provides an operation API that triggers its value increase/decrease.

The SpinBox control inherits from the Edit control, which means it can use the methods of the Edit control in addition to the following methods. This can be seen from the type file.

The type definition of the control is as follows:

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

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

increment(): Promise<void>

Increments the value of the value box by one unit, and the size of the unit depends on the settings in the application. It can be understood as triggering the up arrow in the value box once.

• Return value: an asynchronous method that does not return any value.

decrement(): Promise<void>

Decreases the value of the value box by one unit, and the size of the unit depends on the settings in the application. It can be understood as triggering the down arrow in the value box once.

• Return value: an asynchronous method that does not return any value.

Application

A control for the application itself, usually exists as the topmost control, and provides methods for obtaining application properties and operating the application.

export interface IQApplication extends IQtControl {
    appInfo(): Promise<AppInfo>;
    pid(): Promise<number>;
    quit(): Promise<void>;
}
export interface AppInfo {
    appName: string,
    appPath: string,
    appVersion: string,
    pid: number,
}

class QApplication(QtContainer):
	def appInfo() -> "AppInfo"
	def exists(seconds: int) -> bool
	def pid() -> int
	def quit() -> None
	def topControls() -> List[QtControl]

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

appInfo(): Promise<AppInfo>

Obtain information about the application itself, such as application name, version, path, and so on.

• Return value: AppInfo type, an object containing the application name, path, version and process number.

pid(): Promise<number>

Get the process ID of the application.

• Return value: number type, the process number.

quit(): Promise<void>

Quit the app. will close the application and all child windows belonging to the application.

• Return value: an asynchronous method that does not return any value.

MenuBar & MenuBarItem

The MenuBar control for the toolbar operation in the application, and the button in the toolbar - the MenuBarItem control, is usually only used to click or open the menu button to expand the menu bar. If you need to directly operate menu items, it is recommended to read the invoke() method of the menu control [Menu&MenuItem].

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

open(itemName: String): Promise<void>

Opens the target menu bar option, passing in the name of the target menu bar option.

If it is the open() method on MenuBarItem, no parameters need to be passed in.

• itemName: string type, the name of the target menu bar option.
• Return value: an asynchronous method that does not return any value.

items(): Promise<IQMenuBarItem[]>

Gets the control objects for all options in the menu bar.

• Return value: IQMenuBarItem[] type, an array composed of all menu bar option control objects.

The following are the methods provided by MenuBarItem:

open(): Promise<void>

Open menu item.

• Return value: an asynchronous method that does not return any value.

text(): Promise<string>

Get the menu item text.

• Return value: string type, returns the text of the menu item.

Menu & MenuItem

Controls for menus and menu options in the application, Menu and MenuItem, operate the selection, expansion, and hiding of menus. The definition of the menu control is as follows, but the most commonly used and key is the invoke() operation method, which will be introduced later:

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

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): Promise<void>

Directly triggers a menu item in the target menu. In the Menu control, you need to pass in the name of the target menu item; in the MenuItem control, you don't need to pass in any parameters.

This method does not expand the menu, but directly triggers the function of the target menu item through communication, so the change of the menu will not be observed from the user's perspective.

• itemName: The name of the target menu item, which needs to be the first-level menu item of the target menu;
• Return value: an asynchronous method that does not return any value.

show(): Promise<void>

Expand the target menu.

hide(): Promise<void>

Hides the target menu.

itemNames(): Promise<string[]>

Get all menu item names in the target menu.

• Return value: string[] type, returns a string array composed of all menu item names.

items(): Promise<MenuItem[]>

Get all menu item objects in the target menu.

• Return value: MenuItem[] type, returns an object array composed of all menu item objects.

Following are the methods of MenuItem object.

invoke(): Promise<void>

Trigger the target menu item directly.

This method does not expand the menu, but directly triggers the function of the target menu item through communication, so the change of the menu will not be observed from the user's perspective.

• Return value: an asynchronous method that does not return any value.

checkable(): Promise<boolean>

Get whether the menu item can be checked. Some menu items are checked by clicking. This method is used to obtain the checkable status of the menu item.

• Return value: an asynchronous method that does not return any value.

toggleCheck(value: boolean): Promise<void>

Change the checked state of the menu item. Some menu items are clicked to toggle the checked state, this method is used to modify the checked state. Only menu items whose checkable() method returns true can use this method.

• value: boolean type, indicating the checked state.
• Return value: an asynchronous method that does not return any value.

checked(): Promise<boolean>

Get the checked state of the menu item.

• Return value: boolean type, indicating the checked state.

text(): Promise<string>

Get the text content of the menu item.

• Return value: string type, the text of the menu item.

itemIndex(): Promise<number>

Get the index of the menu item, which is the itemIndex value in the identification attribute.

• Return value: number type, menu item index.

hover(): Promise<void>

Hovering the mouse over the target menu item can be used to expand submenu items.

• Return value: an asynchronous method that does not return any value.

ProgressBar

For the controls supported by the progress bar in the application, the value of the progress bar can be obtained by calling the value() method.

Since the value of the progress bar is usually controlled by internal logic or other controls, it does not support directly modifying its value.

The shape is as follows:

The type file is as follows:

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

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

value(): Promise<number>

Get the value in the current progress bar and return it. Because the returned result is a number, the percent % sign will be omitted.

• Return value: Promise<number> type, you need to use the await keyword to retrieve the result.

Dial

For the knob control used to manually adjust the value, the function is similar to [slider control] (#slider-control), which is a control launched by Qt to adapt to touch screen applications. The shape is as follows:

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(): Promise<number>

Get the current knob value and return it.

• Return value: Promise<number> type, you need to use the await keyword to retrieve the result.

setValue(value): Promise<void>

To set the value of the knob, turn the knob to the specified value, but not exceed the maximum value.

• value: number type, turn the knob to the position of the specified value;
• Return value: an asynchronous method that does not return any value.

Slider

For a slider control that accepts a value set by the user.

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(): Promise<number>

Get the current slider value and return it.

• Return value: Promise<number> type, you need to use the await keyword to retrieve the result.

setValue(value): Promise<void>

Set the value of the slider, drag the slider to the position of the specified value, but not exceed the maximum value.

• value: number type, drag the slider to the position of the specified value;
• Return value: an asynchronous method that does not return any value.

ScrollArea

As a container, when there are many contents in the container, scrolling can be performed. Since sometimes the control is set to not display the scroll bar, it also supports a method for scrolling - the ensureVisible() method for scrolling.

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

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

ensureVisible(x, y): Promise<void>

Scroll to the target position (relative to the upper left corner of the scrolling area).

• x: number type, the number of horizontal pixels;
• y: number type, the number of vertical pixels;
• Return value: an asynchronous method that does not return any value.

TabBar & Tab & TabItem

For the control of the tab page in the application, Tab and TabItem, switch the tab page. At the same time, it provides the control bar where the tab page is located - the tab bar control TabBar. The definition of the tab bar control 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): IQTabItem

Get the automation object of the specified tab page, and pass in the index value or title of the tab page.

• itemNameOrIndex: number or string type, the index value of the target tab page or the title of the tab page.
• Return value: TabItem type, synchronously returns an operation object of TabItem type.

activate(itemNameOrIndex): Promise<void>

Activate the target tab page, passing in the index value or title of the tab page.

If it is the activate() method on TabItem, no parameters need to be passed in.

• itemNameOrIndex: number or string type, the index value of the target tab page or the title of the tab page.
• Return value: an asynchronous method that does not return any value.

closeTab(itemNameOrIndex): Promise<void>

Close the target tab page, pass in the index value or title of the tab page.

If it is the closeTab() method on TabItem, no parameters need to be passed in.

• itemNameOrIndex: number or string type, the index value of the target tab page or the title of the tab page.
• Return value: an asynchronous method that does not return any value.

activateIndex(): Promise<number>

Get the index value of the active tab in the current interface.

• Return value: number type, the index value of the tab page.

activateName(): Promise<string>

Get the name of the active label in the current interface.

• Return value: string type, the name of the tab page.

count(): Promise<number>

Get the number of tabs in the tab bar.

• Return value: number type, the number of tabs.

items(): Promise<string[]>

Get the name of the tab in the tab bar.

• Return value: string[] type, a string array consisting of all tab titles.

Following are the methods of the TabItem object.

activate(): Promise<void>

Activate tab.

• Return value: an asynchronous method that does not return any value.

closeTab(): Promise<void>

Close the tab.

• Return value: an asynchronous method that does not return any value.

text(): Promise<string>

Get the tab title.

• Return value: string type, returns the title of the tab page.

itemIndex(): Promise<number>

Get the order of the tabs in the entire tab bar.

• Return value: number type, returns the index value of the tab page.

GraphicsView & GraphicsItem

It belongs to a kind of graphics generated by drawing, the so-called primitive control, similar to the concept of SVG (Scalable Vector Graphics).CukeTest abstracts this type of primitive into a primitive control for identification and operation, and provides several identification properties for locating primitive controls:

1. position: The position of the target in the canvas;
2. bounding: The collision box of the target primitive, or it can be understood as contour information;
3. objectName: (Optional) The name of the target entity. Since entities do not necessarily contain objectName, it is an optional identification attribute.

export interface GraphicsView extends IQtControl {
}
export interface GraphicsItem extends IQtControl {
}