Qt Object API

Object manipulation API methods are divided into two categories, operations and attributes. The operation does the actual action on the control, and the property is to obtain the run-time properties of the control. Because the control access is asynchronous, the properties are also obtained in the form of methods, that is, you need to add parentheses "()" when calling, and the Promise object that returns the target value-Promise<T>, needs to be added before the call await keyword to get the result in Promise.

Before reading the API documentation...

API syntax description

Qt's API documentation is based on the type file of leanpro.qt (for example, you can enter the type definition file of leanpro.qt.d.ts to view the calling method of the API), so it uses the TypeScript syntax. A brief introduction is made based on the knowledge required to read the document. If you want to learn more, you can go to TypeScript Chinese Introduction to learn more about related syntax.

The first is the name of the current class, here is IQtControl, the full name can be understood as Interface of Qt Control, representing the generalized Qt control interface definition.

The second is the base class, which represents the base class from which the current class extends, and the extension represents the inheritance of the properties and methods in the base class. This is extended from the container class IQtContainer. The container contains various object acquisition APIs. Such an extension can achieve chained object acquisition.

For example, to get the complete call of the "Family" cell in the "sheet1" table in the "Table OverView" window can be written as:

model.getWindow("Table Overview").getTable("sheet1").getTableItem("Family");

CukeTest will optimize when actually generating the control call code, so we don't usually see such a long call.

The last is the operation method and attribute method of the current class. There is a blank line between the operation method and the attribute method to indicate the distinction. () represents the number of parameters passed in, the format of the parameter is [argName]:[argType], if there is a ? before :, it means that the parameter has a default value, even if it is empty Does not affect operation. The tail of the method (after the last :) represents the return value of the method, Promise<T> indicates that the method is an asynchronous method, and only T represents a synchronous method.

The T here represents the type name, such as void, string, number, etc.

The relationship of each class

In CukeTest, the expansion relationship between several classes is roughly as follows:

  1. The lowest base class, the container class IQtContainer, contains methods for obtaining automation objects;
  2. The second base class, the basic control class IQtControl, contains the common operation and attribute methods of each control;
  3. Specific control classes, such as IQWindow, IQLabel... etc. A series of specific Qt controls, in addition to the extended methods, most controls contain their own unique operations and attribute methods to achieve different Automation of controls.

Common API

Different types of object operations have different operations and attributes. They all have some common operations and properties, which can be called no matter which control they are, as follows:

export interface IQtControl extends IQtContainer {
    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>
}

click(x, y, mousekey): Promise<void>

Send a click signal, the default is to left click the center of the target control.

  • x: number type, the horizontal pixel of the relative coordinate, the default is the horizontal center;
  • y: number type, the vertical pixel of the relative coordinate, the default is the vertical center;
  • mouseKey: Left and right mouse buttons, 1 is the left button, 2 is the right button; the default value is 1;
  • Return value: Asynchronous method that does not return any value.

dblClick(x, y, mousekey): Promise<void>

Send a double-click signal, the default is to double-click the center of the target control.

  • x: number type, the horizontal pixel of the relative coordinate; the default is the horizontal center;
  • y: number type, the vertical pixel relative to the coordinate; the default is the vertical center;
  • mouseKey: number type, left and right mouse buttons, 1 is the left button, 2 is the right button; the default value is 1;
  • Return value: Asynchronous method that does not return any value.

wheel(value): Promise<void>

Send the mouse wheel signal.

  • value: number type, positive value scrolls forward, negative value scrolls backward. For example, 1 scroll forward one space, -1 scroll backward one space
  • Return value: Asynchronous method that does not return any value.

moveMouse(x, y): Promise<void>

Move the mouse position to the specified position, x and y are the horizontal and vertical pixels relative to the position of the control.

  • x: number type, the horizontal pixel of the relative coordinate;
  • y: number type, the vertical pixel relative to the coordinate;
  • Return value: Asynchronous method that does not return any value.

rect(): Promise<Rect>

Obtain the shape and position information of the target control.

  • Return value: Return a Rect object, which contains the coordinate information x and y of the control, and the width and height information width and height.

Rect type

An object used to describe the shape and position of the control. In CukeTest, all controls can use a rectangle (Bounding Rectangle) to describe position and shape information. The Rect object contains the following properties:

  • x: number type, the horizontal pixel of the relative coordinate;
  • y: number type, the vertical pixel relative to the coordinate;
  • width: number type, horizontal width, in pixels;
  • height: number type, vertical height, in pixels;

This article only introduces the basic concepts of object operations and the methods of the two base classes. For more documentation about API introduction, you can continue to read the next article: API of Basic Type Objects.

In addition, the specific definitions of each operation and attribute can be found in the model manager, or you can open the type file of the Qt automation API library that comes with CukeTest-the type file of leanpro.qt to search, the specific method can be See the introduction in the More API Introduction section.

API call skills

Distinguishing skills between synchronous and asynchronous methods

The API for obtaining objects is defined in the IQContainer interface class, as follows:

export interface IQtContainer {
    parent: IQtContainer;
    getGeneric(...conditions: ConditionFilter[]): IQtControl;
    getWindow(...conditions: ConditionFilter[]): IQWindow;
    getButton(...conditions: ConditionFilter[]): IQButton;
    ......
    getTable(...conditions: ConditionFilter[]): IQTable;
    getTableItem(...conditions: ConditionFilter[]): IQTableItem;
    getTree(...conditions: ConditionFilter[]): IQTree;
    getTreeItem(...conditions: ConditionFilter[]): IQTreeItem;
    getVirtual(...conditions: ConditionFilter[]): IVirtual;
}

If you compare with the return value of the object operation API in the previous section, you can immediately notice that the return value of the Get Object API is a direct data type, not Promise<T>, which means that these are all synchronous methods, that is, no You need to add the await keyword to get the returned result. There is also a special synchronization method in the object manipulation API, which is the getItem method belonging to the Table, List, and Tree controls. It is also the only synchronization method in the object manipulation API.

You may be aware of this. Yes, there is a difference in naming between synchronous methods and asynchronous methods in CukeTest. The methods with the prefix of get- are synchronous methods, without the keyword of await; and those without this prefix It is an asynchronous method. If await is not added, only a Promise object will be returned, and await is the correct return value.

The difference between value(), text() and data() methods

You may notice that almost every control has a method to get control information, such as the text() method of the label control Label, the value() method of the text box control Edit, and the table control Table Thedata()` method is a method to get the content of the control. So what is the difference between them? It is mainly determined according to the different nature of the target data:

  • text(): The data in the target control is immutable, such as labels, buttons, menu items, etc., which belong to persistent data that will not change easily during operation;
  • value(): The data in the target control is editable, such as input boxes, cells, etc., which are non-persistent data that can be modified at any time during operation;
  • data(): The data in the target control is more complex, such as tables, lists, etc. As a view component, it contains many sub-controls, and the data of the corresponding structure will be returned according to the control structure. For example, the data() method of the Table control returns a string of two-dimensional arrays, while the data() method of the List control returns a string of one-dimensional arrays.

According to the above rules, when you need to get the content of a control, you can first judge the nature of the content of the control, and then you can roughly guess the corresponding method.

More API introduction

More control operations and attribute help can be found in the model manager, or in the script generated by dragging and dropping the model file, hold down the Ctrl key and click the leanpro.qt reference in the script head to jump to the type Definition file.

Chinese version click here.

results matching ""

    No results matching ""