texts

This module provides device text control functions, including clipboard text retrieval and automated input capabilities on Android devices.
It allows developers to programmatically simulate text input, including support for multi-field forms using simulated tab and enter keys.

Key Features:

  • Clipboard Access: Get the current content of the device's clipboard.
  • Text Input: Simulate input into the currently focused or specified screen coordinates.
  • Form Input Support: Use \t (tab) and \n (enter) to fill multiple fields, ideal for login or registration forms.

Typical Usage:

  • Fill input boxes in apps using inputText(x, y, content) or inputText(content) if already focused.
  • Simulate structured form filling with inputForm("user\tphone\tpassword\t").
  • Read and utilize clipboard data using getClipboardText().

All methods are automatically attached to the Device.prototype via internal utilities,
making them available on any device instance returned by Device.getMain().

(inner) getClipboardText() → {string|null}

Get the text content in the device clipboard.

Example
// Example: Retrieve the clipboard text from the main device
var { Device } = require("sigma/device");
var sigmaDevice = Device.getMain();

if (sigmaDevice != null) {
    var tests = require("sigma/tests")
    var ret = sigmaDevice.getClipboardText();
    if (ret != null) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}

//If it executes successfully, it will return:
Congratulations, this API executes successfully.
Return value: my clipboard
Returns:
string | null

The clipboard text if available, or null if retrieval fails.

(inner) inputForm(content) → {number}

Inputs structured text content into multiple input fields on the connected Android device.
The fields are filled sequentially using tab characters (\t) to simulate "Tab" key presses between input boxes.
This is commonly used for login forms or multi-field entries.
This function has the same function as device.inputText(), and the addition is:
If "\t" appears in the parameter, a Tab key event will be sent. For each occurrence of "\t", a Tab will be sent. If "\t" appears at the end of the content, an Enter event will be sent.

Example
// Example 1: Input login name and password into a multi-field form
// when the focus is on the first input box,
// this code will input the username, phone number, and password by simulating Tab navigation.
var { Device } = require("sigma/device");
var sigmaDevice = Device.getMain();
var tests = require("sigma/tests");
var ret = sigmaDevice.inputForm("John\t\t15612658951\t\t123456\t\t");
if (ret == 0) {
    print("Input content successfully!");
} else {
    print(lastError());
}

// Operation Result:
If it executes successfully, it will return:
Input content successfully!
Parameters:
string content

Enter the character content (Chinese, English, numbers, etc.).
The tab-delimited string to input, where each \t moves focus to the next input field.
Returns:
number

0 if the input is successful, otherwise an error code.

(inner) inputText(xopt, yopt, content) → {number}

Inputs a string into the currently focused input field on the connected Android device.
Optionally, you can specify screen coordinates (x, y) to first tap the location before entering the text.

Example
// Example 1: Input text into the currently focused field
// As shown in the figure (inputText.png), when the focus is already on the message content field,
// this code inputs the text directly.
var { Device } = require("sigma/device");
var sigmaDevice = Device.getMain();
var tests = require("sigma/tests");
var ret = sigmaDevice.inputText("Hello word!\n");
if (ret == 0) {
    print("Character input successfully！");
} else {
    print(lastError());
}


// Example 2: Input text at a specific screen position
var { Device } = require("sigma/device");
var sigmaDevice = Device.getMain();
var tests = require("sigma/tests");
var ret = sigmaDevice.inputText(221, 381, "Hello word!");
if (ret == 0) {
    print("Character input successfully！");
} else {
    print(lastError());
}

// Operation Result:
If it executes successfully, it will return:
Character input successfully！
Parameters:
number x <optional>

(Optional) The x-coordinate where the device should tap before inputting text.
number y <optional>

(Optional) The y-coordinate where the device should tap before inputting text.
string content

The text to input. enter the character content (Chinese, English, numbers, etc.).
Returns:
number

Returns 0 if successful, non-zero if it fails, and gets the error message via the lastError() function when it fails.