input

This module provides various input-related operations for simulating user actions on Android devices,
such as taps, swipes, scrolls, key presses, and directional movements. It enables automated UI interactions,
and supports both single and multi-device operations with absolute or relative coordinate systems.

All functions are dynamically attached to Device.prototype, allowing usage like device.click(...), device.scroll(...), etc.

Key Features

  • Touch Events: Precise taps using click and randomized area taps using click2.
  • Scroll Simulation: Scroll in any direction with pixel or ratio-based coordinates.
  • Key Event Sending: Simulate key codes for HOME, BACK, VOLUME, letters, numbers, etc.
  • Directional Movement: Use shift or move for predefined navigation gestures.
  • Multi-point Swipes: Create complex gestures with swipe, supporting finger indexing and delay.
  • Multi-device Support: Execute operations simultaneously on multiple connected devices.

Supported Input Modes

  • Absolute coordinates (e.g., device.click(100, 200))
  • Relative coordinates (e.g., device.click(0.5, 0.5) for center tap)
  • Predefined constants (e.g., tcConst.KEY_HOME, tcConst.movement.shiftPageDown)

Example

var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();

// Tap center of the screen
sigmaDevice.click(0.5, 0.5);

// Scroll up 1000 pixels
sigmaDevice.scroll(500, 800, 0, -1000);

// Send HOME key
sigmaDevice.send(tcConst.KEY_HOME);

(inner) click(x, y, stateopt) → {number}

Send a click event to click on the specified coordinates (x, y).

Example
// Example 1: Click at absolute pixel coordinates (123, 254) with touch state
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
if (sigmaDevice != null) {
    var ret = sigmaDevice.click(123, 254, tcConst.STATE_DOWN);
    if (ret == 0) {
        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");
}


// Example 2: Click at a relative position (12.5% width, 52.58% height)
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
if (sigmaDevice != null) {
    var ret = sigmaDevice.click(0.1250, 0.5258); // Relative click
    if (ret == 0) {
        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");
}

// Operation Result (if successful):
// Congratulations, this API executes successfully.
// Return value: 0
Parameters:
number x

x coordinate, (relative coordinate / absolute coordinate).
number y

y coordinate, (relative coordinate / absolute coordinate).
string state <optional>

(Optional) The touch event type constant:

  • tcConst.STATE_DOWN – press down only
  • tcConst.STATE_UP – release only
  • tcConst.STATE_PRESS – press and release (default tap behavior)
  • tcConst.STATE_MOVE
Returns:
number

result - This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) click2(x, y, offsetopt) → {number}

Click on the random coordinates in the specified area of the screen, that is, randomly click on a certain location within the specified area.

Example
// Randomly click on the specified area of the screen
// The offset range relative to the x coordinate is: 200 - 20/2 —— 200 + 20/2;
// The offset range relative to the y coordinate is: 200 - 10/2 —— 200 + 10/2;
// That is, the value range of the x coordinate is 195 —— 205, and the value range of the y coordinate is 195 —— 205
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
if (sigmaDevice != null) {
    sigmaDevice.click2(200, 200, {dx: 20, dy: 10});
} else {
    print("Failed to get the master device object");
}
Parameters:
number x

x coordinate, (relative coordinate / absolute coordinate).
number y

y coordinate, (relative coordinate / absolute coordinate).
Object offset <optional>

Optional parameters, consists of the keywords "dx" and "dy";
-"dx" : the horizontal offset relative to the x coordinate point, the offset interval relative to the x coordinate is: x-dx/2 - x+dx/2;
-"dy": The vertical offset from the y coordinate point, the offset interval relative to the y coordinate is: y-dy/2 y y + dy/2; For example: {dx:20,dy:10}

Properties
number dx

The left and right offset relative to the x coordinate.
number dy

The upper and lower offset relative to the y coordinate.
Returns:
number

result - If successful, it returns 0; if failed, it returns non-zero. In this case, you can use the lastError() function to get the specific error information.

(inner) move(code) → {number}

Move the page based on system setting swipe/scroll.

Example
// Example 1: Move the device screen up by one full page
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.move(tcConst.movement.pageUp);
if (ret == 0) print("Succeed to move");


// Example 2: Move the screen down slightly
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.move(tcConst.movement.down);


// Example 3: Multiple devices move down by one full page simultaneously
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevices = Device.searchObject(sigmaConst.DevAll);
var ret = sigmaDevices.move(tcConst.movement.pageDown);

// Operation Result:
If successful:
Move successfully
Parameters:
string code

Constant value, key code value. A predefined movement constant from tcConst.movement, including:

  • tcConst.movement.pageUp — Device screen page moves up one screen, equivalent to device.pgUp();
  • tcConst.movement.pageDown — Device screen page moves down one screen, equivalent to device.pgDown();
  • tcConst.movement.up — The device screen page moves up a little, equivalent to device.up();
  • tcConst.movement.down — The device screen page moves down a little, equivalent to device.down();
  • tcConst.movement.left — The device screen page moves down a little, equivalent to device.left();
  • tcConst.movement.right — The device screen page moves down a little, equivalent to device.right();
  • tcConst.movement.shiftUp — The device screen page moves up a little, "shiftUp" moves faster and larger than "up", equivalent to device.shiftUp();
  • tcConst.movement.shiftDown — The device screen page moves down a little, "shiftDown" moves faster and larger than "down", equivalent to device.shiftDown();
  • tcConst.movement.shiftPageUp — Device screen page moves up several screens, "shiftPgUp " moves faster and larger than "pgUp", equivalent to device.shiftPgUp();
  • tcConst.movement.shiftPageDown — Device screen page moves down several screens, "shiftPgDn " moves faster and larger than "pgDn", equivalent to device.shiftPgDn();
  • tcConst.movement.shiftLeft — The device screen page moves left a little, equivalent to device.shiftLeft();
  • tcConst.movement.shiftRight — The device screen page moves right a little, equivalent to device.shiftRight();
Returns:
number

If the execution is successful, it returns 0; if the execution fails, it returns null. You can get the error information through lastError().

(inner) scroll(xopt, yopt, dx, dy) → {number}

Scrolls the specified range from the specified scroll area position in the specified direction. Supports scrolling up one or more pages, scrolling down one or more pages, scrolling left one or more pages or scrolling right one or more pages, and supporting multiple devices to scroll simultaneously.
Simulates a scroll (swipe) gesture on the screen from a given coordinate by a specified offset.
Supports both absolute pixel coordinates and relative screen ratios, and can be used for single or multiple devices.
If x and y are omitted, the default scroll start point is used.
x and y are Optional, pointing to the area that the scrolling will take place, supporting absolute and relative coordinates. By default, By default, the mouse position is used. If the mouse position cannot be found, the screen center point is used (x = width / 2, y = height / 2). Different applications have different scroll areas, and there may be multiple scroll areas on the screen.

Example
// Example 1: Scroll up 1000 pixels from point (500, 700)
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.scroll(500, 700, 0, 1000);
if (ret == 0) print("Scroll successfully");


// Example 2: Scroll down 1000 pixels from point (500, 700)
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.scroll(500, 700, 0, -1000);


// Example 3: Scroll left 1000 pixels from point (500, 700) on multiple devices
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevices = Device.searchObject(sigmaConst.DevAll);
var ret = sigmaDevices.scroll(500, 700, -1000, 0);


// Example 4: Scroll right by 20% of the screen width from position (50%, 60%) on multiple devices
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevices = Device.searchObject(sigmaConst.DevAll);
var ret = sigmaDevices.scroll(0.5, 0.6, 0.2, 0);


// Example 5: Scroll right 1000 pixels from default starting point on multiple devices
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevices = Device.searchObject(sigmaConst.DevAll);
var ret = sigmaDevices.scroll(1000, 0); // x and y are omitted

// Operation Result:
// If successful, returns: Scroll successfully
Parameters:
number x <optional>

The starting x-coordinate (in pixels or ratio). Optional if using default position.
number y <optional>

The starting y-coordinate (in pixels or ratio). Optional if using default position.
number dx

Specifies the distance to scroll left or right. It supports relative and absolute coordinates.
When dx is positive, it means to scroll to the right, and when dx is negative, it means to scroll to the left. Usually, one of the dx or dy should be zero.
Some apps (e.g. picture too large to fit in device screen) can use to scroll both dx and dy.
number dy

Specifies the distance to scroll up or down, support relative and absolute coordinates.
when dy is positive it means to scroll up, and when dy is negative, it means to scroll down. Usually, one of the dx or dy should be zero.
Some apps (e.g. picture too large to fit in device screen) can use to scroll both dx and dy.
Returns:
number

result - If the execution is successful, it returns 0; if the execution fails, it returns null. You can get the error information through lastError().

(inner) send(code, stateopt) → {number}

Send a key event, such as home, menu, back, etc., to realize the key press and bounce event, or directly send a click event (press + bounce) to complete the click action. Total Control supports Android KEYCODE on keyboards and mobile phones.

key code value:

  1. Device keys:
    Back key: KEYCODE_BACK or tcConst.KEY_BACK;
    Home key: KEYCODE_HOME or tcConst.KEY_HOME;
    Power key: KEYCODE_POWER or tcConst.KEY_POWER;
    Menu key: KEYCODE_MENU or tcConst.KEY_MENU;
    Search key: KEYCODE_SEARCH or tcConst.KEY_SEARCH;
    RecentApp key: KEYCODE_RECENTAPP or tcConst.KEY_RECENTAPP.
  2. Keyboard keys:
    1). Function keyboard area
    F1-F12: The format is KEYCODE_x or tcConst.KEY_x, where x is A-Z, such as KEYCODE_F1 or tcConst.KEY_F1.
    Esc key: KEYCODE_ESCAPE or tcConst.KEY_ESCAPE.
    2). Main keyboard area
    A-Z letters: The format is KEYCODE_x or tcConst.KEY_x, where x is A-Z, such as KEYCODE_A or tcConst.KEY_A.
    0-9 numbers: The format is KEYCODE_x or tcConst.KEY_x, where x is 0-9, such as KEYCODE_0 or tcConst.KEY_0.
    Tab key: KEYCODE_TAB or tcConst.KEY_TAB.
    BackSpace key: KEYCODE_BACK_SPACE or tcConst.KEY_BACK_SPACE.
    CapsLock key: KEYCODE_CAPS_LOCK or tcConst.KEY_CAPS_LOCK.
    Enter key: KEYCODE_ENTER or tcConst.KEY_ENTER.
    Space key: KEYCODE_SPACE or tcConst.KEY_SPACE.
    '' key: KEYCODE_SLASH or tcConst.KEY_SLASH.
    '/' key: KEYCODE_BACKSLASH or tcConst.KEY_BACKSLASH.
    ',' key: KEYCODE_COMMA or tcConst.KEY_COMMA.
    '-' key: KEYCODE_MINUS or tcConst.KEY_MINUS.
    '=' key: KEYCODE_EQUALS or tcConst.KEY_EQUALS.
    ''' (apostrophe) key: KEYCODE_APOSTROPHE or tcConst.KEY_APOSTROPHE.
    ';' key: KEYCODE_SEMICOLON or tcConst.KEY_SEMICOLON.
    '.' key: KEYCODE_PERIOD or tcConst.KEY_PERIOD.
    '`' (backtick) key: KEYCODE_GRAVE or tcConst.KEY_GRAVE.
    '[' key: KEYCODE_LEFT_BRACKET or tcConst.KEY_LEFT_BRACKET.
    ']' key: KEYCODE_RIGHT_BRACKET or tcConst.KEY_RIGHT_BRACKET.
    Left Alt modifier key: KEYCODE_ALT_LEFT or tcConst.KEY_ALT_LEFT.
    Left Control modifier key: KEYCODE_CTRL_LEFT or tcConst.KEY_CTRL_LEFT.
    Left Shift modifier key: KEYCODE_SHIFT_LEFT or tcConst.KEY_SHIFT_LEFT.
    Left Win modifier key: KEYCODE_WIN_LEFT or tcConst.KEY_WIN_LEFT.
    Right Win modifier key: KEYCODE_WIN_RIGHT or tcConst.KEY_WIN_RIGHT.
    3). Edit control keyboard area
    PageUp key: KEYCODE_PAGE_UP or tcConst.KEY_PAGE_UP or tcConst.KEY_PGUP.
    PageDown key: KEYCODE_PAGE_DOWN or tcConst.KEY_PAGE_DOWN or tcConst.KEY_PGDN.
    End key: KEYCODE_END or tcConst.KEY_END. Delete key: KEYCODE_DEL or tcConst.KEY_DEL.
    Up key: KEYCODE_UP or tcConst.KEY_UP. Down key: KEYCODE_DOWN or tcConst.KEY_DOWN.
    Left key: KEYCODE_LEFT or tcConst.KEY_LEFT.
    Right key: KEYCODE_RIGHT or tcConst.KEY_RIGHT.
    4). Numeric keypad area
    0-9 numbers: the format is KEYCODE_NUMPAD_x or tcConst.KEY_NUMPAD_x, where x is 0-9, such as KEYCODE_NUMPAD_0 or tcConst.KEY_NUMPAD_0.
    Numeric keypad '+' key: KEYCODE_NUMPAD_ADD or tcConst.KEY_NUMPAD_ADD.
    Numeric keypad '-' key: KEYCODE_NUMPAD_SUBTRACT or tcConst.KEY_NUMPAD_SUBTRACT.
    Numeric keypad '*' key: KEYCODE_NUMPAD_MULTIPLY or tcConst.KEY_NUMPAD_MULTIPLY.
    Numeric keypad '/' key: KEYCODE_NUMPAD_DIVIDE or tcConst.KEY_NUMPAD_DIVIDE.
    Enter key: KEYCODE_NUMPAD_ENTER or tcConst.KEY_NUMPAD_ENTER.
    NumLock key: KEYCODE_NUM_LOCK or tcConst.KEY_NUM_LOCK.
    5). Key combination, only for API prototype send (code)
    tcConst.KEY_S_UP: Shift + ↑, the mobile screen page moves up a bit, "Shift + ↑" moves faster and larger than "↑".
    tcConst.KEY_S_DOWN: Shift + ↓, the mobile screen page moves down a bit, "Shift + ↓" moves faster and larger than "↓".
    tcConst.KEY_S_LEFT: Shift + ←, the mobile screen page moves a little to the left, "Shift + ←" moves faster and larger than "←".
    tcConst.KEY_S_RIGHT: Shift + →, the screen page of the mobile phone moves a little to the right, "Shift + →" moves faster and larger than "→".
    tcConst.KEY_S_PGUP: Shift + PgUp, mobile phone screen page moves up several screens, "Shift + PgUp" moves faster and larger than "pgUp".
    tcConst.KEY_S_PGDN: Shift + PgDn, the mobile screen page moves down a few screens, "Shift + PgDn" moves faster and larger than "pgDn".
Example
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();

// Send a HOME key press event
sigmaDevice.send(tcConst.KEY_HOME, tcConst.STATE_DOWN);

// Send a HOME key release event
sigmaDevice.send(tcConst.KEY_HOME, tcConst.STATE_UP);

// Send a HOME key full press (press & release)
sigmaDevice.send(tcConst.KEY_HOME, tcConst.STATE_PRESS);

// Equivalent to STATE_PRESS (default behavior if state is missing)
sigmaDevice.send(tcConst.KEY_HOME);

// Send POWER button press (hold down)
sigmaDevice.send(tcConst.KEY_POWER, tcConst.STATE_DOWN);
Parameters:
string code

The key code to send. Use predefined constants like tcConst.KEY_HOME, tcConst.KEY_POWER, tcConst.KEY_BACK, etc.
string state <optional>
 tcConst.STATE_PRESS

(Optional) The key event type:

  • tcConst.STATE_DOWN – Press down only
  • tcConst.STATE_UP – Release only
  • tcConst.STATE_PRESS – Press and release (default if omitted)
Returns:
number

result - This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) shift(direct) → {number}

Operate the device, slide the operation screen.

Example
// Example: Simulate a "LEFT" directional key input
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
if (sigmaDevice != null) {
    var ret = sigmaDevice.shift(tcConst.KEY_LEFT);
    if (ret == 0) {
        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");
}

// Operation Result (if successful):
Congratulations, this API executes successfully.
Return value: 0
Parameters:
string direct

The constant value of the direction.
Use predefined constants from tcConst, such as:

  • tcConst.KEY_LEFT — Swipe left
  • tcConst.KEY_RIGHT — Swipe right
  • tcConst.KEY_UP — Swipe up
  • tcConst.KEY_DOWN — Swipe down
Returns:
number

result - This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) swipe(…args) → {number}

Simulate user operation screens, touch events. Sliding events for single or multi-point operations can be implemented. A touch event that simulates a user's operation, enabling a single or multi-point sliding event. If the "coord" array consists of 2 points with no delay, you can use swape([x1, y1], [x2, y2], speed). Coordinate format: the first coordinate group in the array is the pressed coordinate; the last coordinate group in the array is the lifting coordinates; the middle array is the sliding coordinate

Supports:

  1. swipe(coord) - single or multiple sliding coordinates (single point or multiple points)
  2. swipe([x1, y1], [x2, y2], speed) - slide from the starting point to the end point, the default speed is 4

The coord object used in the script to store screen coordinates, whose member variables include:

  • x: int, The x coordinate of the pixel in the screen.
  • y: int, The y coordinate of the pixel in the screen.
Example
// Example 1: Single-point sliding (relative coordinates)
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.swipe([[0, 0, 30], [0.1, 0.2, 100], [0.5, 0.8, 1]]);
if (ret == 0) print("Sliding operation succeeded");


// Example 2: Multi-point sliding (absolute coordinates)
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.swipe([[124, 256, 255, 296, 30], [224, 296, 340, 432, 100], [324, 356, 435, 567, 1]]);
if (ret == 0) print("Sliding operation succeeded");


// Example 3: Two-point sliding with no delay
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.swipe([0, 0], [500, 800], 2); // finger index 2
if (ret == 0) print("Sliding operation succeeded");

// Operation Result:
If it executes successfully, it will return:
Sliding operation succeeded
Parameters:
any args <repeatable>

Mode 1: ([x1, y1], [x2, y2], speed) for simple swipe.

  • (x1, y1) and (x2, y2) are the starting and ending coordinates respectively. Supports both relative and absolute coordinate formats.
  • speed: This parameter is optional. Values range from 0 to 5, 0 - slowest, 5 - fastest. The intermediate coordinates will use the speed of the third tuple of the swipe operation. The default value is 4

Mode 2: (coord) where coord is an array of points with optional delay values

  • coord: Array coordinates.
  • Single point coordinate format definition: [x coordinate, y coordinate, delayed execution time].
  • Multi-point coordinate format definition: [x1 coordinate, y1 coordinate, x2 coordinate, y2 coordinate, delayed execution time].

For example:
1. Single point sliding: [124,256,123] or [[124,256,123],[356,156,111],[212,222,222],[256,456,333]]
2. Multi-slide: [[124,256,212,121,123],[256,456,323,423,333],[256,456,323,423,333]]
Returns:
number

result - This function returns 0 on success or -1 on failure. Specific error information can be obtained by the lastError() function.

(inner) swipe2(from, to, speedopt) → {number|null}

Simulates a smooth swipe gesture between two points with adjustable speed and coordinate type.
This function supports absolute and relative coordinates. If absolute coordinates are detected,
they are automatically converted to relative before performing the swipe.

Internally, the swipe path is built from high-granularity points based on the distance between two points,
and each step uses a predefined delay from the speed level.

Example
// Example 1: Absolute coordinates: swipe from (100, 200) to (500, 800) at speed 3
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.swipe2([100, 200], [500, 800], 3);
if (ret == 0) print("Swipe success");


// Example 2: Relative coordinates: swipe from 20% width, 30% height to 60% width, 80% height
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.swipe2([0.2, 0.3], [0.6, 0.8], 2);


// Example 3: Swipe with default speed (4)
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.swipe2([0.1, 0.1], [0.9, 0.9]);


// Example 4: Error case: invalid speed
var { Device } = require('sigma/device');
var input = require("sigma/input");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.swipe2([100, 200], [500, 800], 10);
if (ret == null) print("Error: " + lastError());
Parameters:
Array.<number> from

Starting point of the swipe. Format: [x, y].
Can be either absolute (e.g. [100, 200]) or relative (e.g. [0.2, 0.3]).
Array.<number> to

Ending point of the swipe. Format: [x, y].
Can be either absolute or relative, must match format of from.
number speed <optional>
 4

Optional swipe speed level from 0 (slowest) to 5 (fastest).
Returns:
number | null

This function returns 0 on success or non-zero on failure. Specific error information can be obtained by the lastError() function.