Gui Text

What if the position of the specified text in the control needs to be manipulated, but the text cannot be recognized as a control? Maybe GuiText can help you solve this problem.

As the name suggests, Gui Text is a way of operating text as a control object. Its implementation starts from the underlying mechanism of graphics rendering, and realizes further and more precise positioning by positioning the text position on the existing control tree.

Add GuiText

Like other test objects, Gui Text objects are also detected, identified and managed in the model manager. After opening the model file or the model manager, you can click "Spy Gui Text" (located in the drop-down list of the "Spy Windows Object" button in the model manager toolbar) to enter the detection of the text object.

edit properties

At present, Gui Text has one and only one identification attribute—text, but this attribute supports regular expression matching. For details, please refer to Object Detail Page Operations.

edit parent node

Gui Text has requirements for direct container controls, so editing of the parent control of Gui Text needs to be carefully modified. If the nearest container control of Gui Text (such as Pane, Window, Tree, Menu, etc.) is deleted, Gui Text will not be recognized correctly.

API for Gui Text

Type definition for Gui Text

export interface IGuiTextControl {
    click(x?: number, y?: number, mousekey?: number): Promise<void>;
    dblClick(x?: number, y?: number, mousekey?: number): Promise<void>;
    exists(seconds?: number): Promise<boolean>;
    highlight(duration?: number);
    moveMouse(x?: number, y?: number, seconds?: number): Promise<void>;
    rect(): Promise<Rect>;
    text(): Promise<string>;
    takeScreenshot(filePath?: string): Promise<string>;
    modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string | Buffer>;  //base64 is the default
    modelProperties(all?: boolean): {[x: string]: any};
}

operation method

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

The mouse clicks the control, and the relative position (offset) of the click and the mouse button used can be modified by passing in parameters.

• x: number, the click position is relative to the horizontal pixel point of the upper left corner of the control, 0 represents the horizontal midpoint position of the control, and the default value is 0;
• y: number, the click position is relative to the vertical pixel point of the upper left corner of the control, 0 represents the vertical midpoint position of the control, and the default value is 0;
• mouseKey: MouseKey type, the mouse key to operate, the default is 1, which is the left mouse button.

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

Double click on the control, called in the same way as the click() method, modifies the relative position (offset) of the click and the mouse button used by passing in parameters.

• x: number, the click position is relative to the horizontal pixel point of the upper left corner of the control, 0 represents the horizontal midpoint position of the control, and the default value is 0;
• y: number, the click position is relative to the vertical pixel point of the upper left corner of the control, 0 represents the vertical midpoint position of the control, and the default value is 0;
• mouseKey: MouseKey type, the mouse key to operate, the default is 1, which is the left mouse button.

moveMouse(x, y): Promise<void>

Move the mouse cursor to the relative position of the control, and move to the center of the control by default.

• x: number, the click position is relative to the horizontal pixel point of the upper left corner of the control, 0 represents the horizontal midpoint position of the control, and the default value is 0;
• y: number, the click position is relative to the vertical pixel point of the upper left corner of the control, 0 represents the vertical midpoint position of the control, and the default value is 0;

exists(time): Promise<boolean>

Check whether the control exists, and the input parameter is the maximum waiting time (timeout) for checking. The default call will only check once without retrying or waiting.

• time: number, the timeout time, the unit is seconds, when it is 0, it will not retry and wait, and the default parameter is 0.
• returns: Asynchronously returns whether the control exists, true means it exists, false means it does not exist.

pressKeys(keys, options?): Promise<void>

Enter a key or character string, and focus on the target control before inputting. When a string is passed in, some special characters (^+~%{}()) in the string will be executed as control keys (Shift key, CTRL key, etc.) For the corresponding symbols, please refer to Appendix: Key Codes for details. If you want to enter plain text, ignoring these control key symbols, you can use the {textOnly: true} option and call it like this: pressKeys(str, {textOnly: true}).

• keys: string type, the key, key combination or string to be input, up to 1024 characters are supported.
• options: (Optional) Some optional parameters that control the input mode.
  • textOnly: Enter only character strings, and also enter control characters as text. The effect is equivalent to calling Keyboard.typeString().
• cpm: the number of input characters per minute, used to control the speed of text input. It is recommended to set the cpm value above 200 for automatic operation. Due to the internal implementation of the method and the different processing of text input by various systems and applications, the actual input speed may not reach the set cpm. When options is a number, it is equivalent to the cpm parameter.
• returns: An asynchronous method that returns no value. For more instructions or examples, please refer to Simulating Keyboard Operations.

takeScreenshot(filePath): Promise<string>

The screenshot of the control, you can pass in the path to save the screenshot to the path location.

• filePath: (optional) string, the save path and file name of the screenshot, such as "./images/screenshot1.png".
• returns: Asynchronously returns the base64 string of the screenshot.

modelProperties(): Promise<object>

Get the model properties of the target control, that is, the properties of the corresponding model object (recognition properties and other properties).

• returns: Asynchronously returns an object object consisting of properties of the target model object.

modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string>

Get a cached screenshot of the control in the model manager.

If you call the modelImage() method on an object returned by Descriptive Mode, an error will be reported.

• returns: Asynchronously return the Buffer object or base64 string of the screenshot of the target control.

property method definition

It should be noted that the property methods of the control are asynchronous. After calling, CukeTest will communicate with the target control to obtain the current property of the control, that is, the real-time property, rather than the identification property in the model object. The properties listed below are supported by all controls, but not all have values. You can try similar property methods to obtain the target properties according to the suggestions.

text(): Promise<string>

Text information of Gui Text.

When using regular expressions to match Gui Text, you can also get the full text.

• returns: string type, asynchronously returns the text of the target Gui Text.

rect(): Promise<Rect>

The control's description rectangle.

• returns: Shared Object API, asynchronously returns an object containing x, y, height and width information of the control.