Touch Class

Touch is a low-level gesture API for when taps and straight swipes are not enough.

A touch from Touch.createTouch() stays held: after touch.down(x, y) + touch.dispatch() the finger stays down while your script continues, including during region.waitFor(...) or region.find(...). Release it with touch.up() + touch.dispatch(). See the second example below. The finger is released automatically if the macro stops or the code block ends.

`Touch.tap(x, y, duration?)`

Convenience tap (default 100ms).

let touch = Touch.createTouch();
let result = Touch.tap(500, 1200, 1000);
console.log(result);

`Touch.hold(x, y, duration?)`

Convenience long-press (default 600ms).

let touch = Touch.createTouch();
let result = Touch.hold(500, 1200, 1000);
console.log(result);

`Touch.swipe(x1, y1, x2, y2, duration?)`

Convenience straight swipe (default 300ms).

let touch = Touch.createTouch();
Touch.swipe(500, 1400, 500, 600, 1000);

`Touch.createTouch()`

Create a low-level touch object.

let touch = Touch.createTouch();
let result = Touch.createTouch();
console.log(result);

`touch.down(point, pointerId?)`

Press one finger down.

let touch = Touch.createTouch();
touch.down(new Point(300, 800), 0);

`down(x, y, ...)`

Press one finger down.

let touch = Touch.createTouch();
let result = touch.down(500, 1200, 'demo');
console.log(result);

`touch.move(point, pointerId?)`

Move one finger.

let touch = Touch.createTouch();
touch.move(new Point(300, 800), 0);

`move(x, y, ...)`

Move one finger.

let touch = Touch.createTouch();
let result = touch.move(500, 1200, 'demo');
console.log(result);

`touch.up(pointerId?)`

Lift one finger.

let touch = Touch.createTouch();
touch.up(0);

`touch.dispatch()`

Apply the staged down/move/up. After a down, this presses and holds the finger and returns immediately; after an up, it releases.

let touch = Touch.createTouch();
let result = touch.dispatch();
console.log(result);

`touch.commit()`

Apply the staged down/move/up. After a down, this presses and holds the finger and returns immediately; after an up, it releases.

let touch = Touch.createTouch();
touch.commit();

`touch.dispose()`

Release the finger (if still held) and free the touch handle.

let touch = Touch.createTouch();
let result = touch.dispose();
console.log(result);

`touch.release()`

Release the finger (if still held) and free the touch handle.

let touch = Touch.createTouch();
let result = touch.release();
console.log(result);

`Touch.multi()`

Create a multi-finger gesture object.

let touch = Touch.createTouch();
let result = Touch.multi();
console.log(result);

`multi.addFinger(point)`

Create and return a finger ID.

let touch = Touch.createTouch();
multi.addFinger(new Point(300, 800));

`multi.addFinger(x, y)`

Create and return a finger ID.

let touch = Touch.createTouch();
multi.addFinger(500, 1200);

`multi.moveFinger(fingerId, point)`

Move an existing finger.

let touch = Touch.createTouch();
multi.moveFinger(0, new Point(300, 800));

`moveFinger(...)`

Move an existing finger.

let touch = Touch.createTouch();
let result = touch.moveFinger('demo');
console.log(result);

`multi.removeFinger(fingerId)`

Remove one finger.

let touch = Touch.createTouch();
multi.removeFinger(0);

`multi.dispatch(duration)`

Run the built gesture.

let touch = Touch.createTouch();
let result = multi.dispatch(1000);
console.log(result);

Example:

// Let's create a virtual joystick movement using the Touch API
let joystickCenter = new Point(200, 800);
let t = Touch.createTouch();

// Press down exactly on the joystick
t.down(joystickCenter);

// Steer upwards, pushing the joystick slightly up
t.move(new Point(joystickCenter.x, joystickCenter.y - 50));
t.dispatch();

// Hold that position for 2 seconds (e.g., to walk forward)
wait(2000);

// Let go of the joystick
t.up();
t.dispatch();

Example, hold the screen while searching for an image:

let screen = new Region(0, 0, Screen.getWidth(), Screen.getHeight());

// Press and HOLD at (540, 1200). dispatch() returns immediately; the finger stays down.
let t = Touch.createTouch();
t.down(540, 1200);
t.dispatch();

// The finger is still held here. This blocking search runs WHILE holding.
// waitFor returns as soon as "target.png" appears, or null after 8s.
let found = screen.waitFor("target.png", 8000);

// Release the finger and free the handle.
t.up();
t.dispatch();
t.dispose();

if (found) {
  found.click();
}

Notes and limits

Only one finger per createTouch() object. For genuinely simultaneous multi-finger holds this API is still limited, use Touch.multi() or the built-in multi.click / pinchIn / pinchOut for one-shot multi-finger gestures.
While a finger is held you generally cannot dispatch a separate tap or swipe elsewhere. Android allows only one gesture in flight, so a competing gesture cancels the hold. Holding while searching is fine (a search is not a gesture); holding while tapping somewhere else is not.
A hold lives within the code block that started it; it is force-released when that block finishes.