IOS13 SimulateTouch

https://github.com/xuan32546/ios13-simulatetouch
Admin
IOS13 SimulateTouch (ZXTouch) is a system-wide touch event simulation library for jailbroken iOS...
Tokens:16,038
Snippets:208
Trust Score:6.7
License:GPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install coverage package

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Command to install the coverage package for test coverage analysis.

```bash
> python3 -m pip install coverage
```

--------------------------------

### Switch Application Example

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Demonstrates connecting to a device and returning to the home screen using the bundle identifier.

```python
from zxtouch.client import zxtouch

device = zxtouch("127.0.0.1") # create instance
device.switch_to_app("com.apple.springboard") # return to home screen

device.disconnect()
```

--------------------------------

### Show Alert Box Example

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Demonstrates triggering a system-wide alert box that persists for 3 seconds.

```python
from zxtouch.client import zxtouch

device = zxtouch("127.0.0.1") # create instance
device.show_alert_box("Alert", "This is a system-wide alert box that lasts for 3 seconds", 3)

device.disconnect()
```

--------------------------------

### Retrieve screen color

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Example usage of the pick_color method to get and print RGB values from a specific point.

```python
from zxtouch.client import zxtouch
import time

device = zxtouch("127.0.0.1")
print("Picking color from 100, 100 after 1.5 seconds...")
time.sleep(1.5)
result_tuple = device.pick_color(100, 100)
if not result_tuple[0]:
    print("Error while getting color. Error info: " + result_tuple[1])
else:
    result_dict = result_tuple[1]
    print("Red: " + result_dict["red"] + ". Green: " + result_dict["green"] + ". Blue: " + result_dict["blue"])
		
device.disconnect()
```

--------------------------------

### Execute touch and multi-touch operations

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Complete example demonstrating device connection, single touch movement, and simultaneous multi-touch execution.

```python
# code example
from zxtouch.client import zxtouch
from zxtouch.touchtypes import *
import time

device = zxtouch("127.0.0.1") # create instance

# finger "5" touch (400, 400)
device.touch(TOUCH_DOWN, 5, 400, 400) # TOUCH_DOWN is imported from zxtouch.touchtypes
time.sleep(1)
# move to (400, 600)
device.touch(TOUCH_MOVE, 5, 400, 600) # TOUCH_MOVE is imported from zxtouch.touchtypes
time.sleep(1)
# touch up
device.touch(TOUCH_UP, 5, 400, 600) # TOUCH_UP is imported from zxtouch.touchtypes
time.sleep(1)

# multitouch point (300, 300) and (500, 500) at the same time
device.touch_with_list([{"type": TOUCH_DOWN, "finger_index": 1, "x": 300, "y": 300}, {"type": TOUCH_DOWN, "finger_index": 2, "x": 500, "y": 500}])
time.sleep(1)
device.touch_with_list([{"type": TOUCH_UP, "finger_index": 1, "x": 300, "y": 300}, {"type": TOUCH_UP, "finger_index": 2, "x": 500, "y": 500}])

device.disconnect()
```

--------------------------------

### Install DEB package via SSH

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Command to install the ZXTouch tweak package manually on an iOS device using dpkg.

```bash
dpkg -i /PATH/TO/om.zjx.pccontrol_0.0.2_iphoneos-arm.deb
```

--------------------------------

### Setup and teardown for GUI tests

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Standard class methods for initializing and cleaning up tkinter objects in GUI tests.

```python
@classmethod
def setUpClass(cls):
    requires('gui')
    cls.root = tk.Tk()
    cls.text = tk.Text(root)

@classmethod
def tearDownClass(cls):
    del cls.text
    cls.root.update_idletasks()
    cls.root.destroy()
    del cls.root
```

--------------------------------

### Execute image matching

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Example usage of the image_match method, including error handling and result verification.

```python
from zxtouch.client import zxtouch

device = zxtouch("127.0.0.1") # create instance
result_tuple = device.image_match("/var/mobile/Library/ZXTouch/scripts/examples/Image Matching.bdl/examples_folder.jpg", 0.8, 5, 0.85) # try 5 times with acceptable value 0.8. Each time  make template image size*1.5 AND size/1.5 then match again.

if not result_tuple[0]:
	print("Error happens while matching template image. Error info: " + result_tuple[1])
else:
	result_dict = result_tuple[1]
	if float(result_dict["width"]) != 0 and float(result_dict["height"]) != 0:
		print("Match success! X: " + result_dict["x"] + ". Y: " + result_dict["y"] + ". Width: " + result_dict["width"] + ". Height: " + result_dict["height"])
	else:
		print("Match failed. Cannot find template image on screen.")
		
device.disconnect()
```

--------------------------------

### Initialize Tkinspect Object Browser

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/TODO.txt

Example usage of the Tkinspect module to visually navigate an object's attributes and hierarchy.

```python
>>> from inspector import Tkinspect
>>> Tkinspect(None, myObject)
```

--------------------------------

### Get Device Information

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves a dictionary containing device metadata such as name, system version, and model.

```python
def get_device_info():
    """Get information of the device
		
	Args:
		None
				    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise a dictionary containing name, system_name, system_version, model, identifier_for_vendor.
							format of the dicionary: {"name": ?, "system_name": ?, "system_version": ?, "model": ?, "identifier_for_vendor": ?}
    """
```

--------------------------------

### Display toast messages

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Example usage of the show_toast method with various toast types and positions.

```python
from zxtouch.client import zxtouch
from zxtouch.toasttypes import *
import time

device = zxtouch("127.0.0.1") # create instance
device.show_toast(TOAST_SUCCESS, "This is an success message toast", 1.5)
time.sleep(1.5)

device.show_toast(TOAST_ERROR, "This is an error message toast", 1.5)
time.sleep(1.5)

device.show_toast(TOAST_WARNING, "This is an warning message toast", 1.5)
time.sleep(1.5)

device.show_toast(TOAST_MESSAGE, "This is an normal message toast", 1.5)
time.sleep(1.5)

device.show_toast(TOAST_ERROR, "Toast can also be shown at bottom", 3, TOAST_BUTTOM)


device.disconnect()
```

--------------------------------

### Manage Touch Recording

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Functions to start and stop the recording of touch events on the device.

```python
def start_touch_recording():
    """Start recording touch events. If success, there will be a red indicator at the top of your screen.
		
	Args:
    	None
        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

```python
def stop_touch_recording():
    """Stop recording touch events. You can also double click volumn down button to stop recording
		
	Args:
    	None
        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

--------------------------------

### Get Screen Size

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves the screen dimensions in pixels, returning a dictionary with width and height.

```python
def get_screen_size():
    """Get screen size in pixels
		
	Args:
		None
				    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise a dictionary containing width and height of the screen.
							format of the dicionary: {"width": ?, "height": ?}
    """
```

--------------------------------

### Get Screen Orientation

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves the current screen orientation as an integer string.

```python
def get_screen_orientation():
    """Get orientation of the screen
		
	Args:
		None
				    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise the orientation of the screen. An int value in str format indicating the orientation.
    """
```

--------------------------------

### Get Screen Scale

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves the screen scale factor as an integer string.

```python
def get_screen_scale():
    """Get scale of the screen
		
	Args:
		None
				    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise the scale of the screen. An int value in str format indicating the scale.
    """
```

--------------------------------

### Initialize a ZXTouch Instance

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Create a connection to the device using its IP address. Use '127.0.0.1' for scripts running directly on the iOS device.

```python
from zxtouch.client import zxtouch # import module
device = zxtouch("127.0.0.1") # create instance
```

--------------------------------

### start_touch_recording()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Initiates the recording of touch events on the device screen.

```APIDOC
## start_touch_recording()

### Description
Starts recording touch events. A red indicator appears at the top of the screen upon success.

### Returns
- **Result tuple** (tuple) - A tuple where the first element is a boolean indicating success, and the second element is an error message if failed.
```

--------------------------------

### IDLE Command Line Syntax

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/help.html

The command line interface for launching IDLE with various options for execution, debugging, and file handling.

```text
idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ...

-c command  run command in the shell window
-d          enable debugger and open shell window
-e          open editor window
-h          print help message with legal combinations and exit
-i          open shell window
-r file     run file in shell window
-s          run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window
-t title    set title of shell window
-           run stdin in shell (- must be last option before args)
```

--------------------------------

### switch_to_app(bundle_identifier)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Brings a specific application to the foreground on the connected iOS device.

```APIDOC
## switch_to_app(bundle_identifier)

### Description
Brings an application to the foreground using its bundle identifier.

### Parameters
- **bundle_identifier** (string) - Required - The bundle identifier of the application to bring to the foreground.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is an error string if index 0 is False.
```

--------------------------------

### Run all IDLE tests via command line

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Commands to execute the full IDLE test suite using unittest or regrtest.

```bash
python -m unittest -v idlelib.idle_test
python -m test -v -ugui test_idle
python -m test.test_idle
```

--------------------------------

### Bring Application to Foreground

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Defines the function signature for switching to a specific application by its bundle identifier.

```python
def switch_to_app(bundle_identifier):
	"""Bring an application to foreground
	
	Args:
		bundle_identifier: the bundle identifier of the application
	
	Returns: 
		Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
	"""
```

--------------------------------

### zxtouch(ip)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Initializes a connection to the ZXTouch service on the target iOS device.

```APIDOC
## zxtouch(ip)

### Description
Creates a new instance of the ZXTouch client to communicate with the device at the specified IP address.

### Parameters
- **ip** (string) - Required - The IP address of the iOS device. Use "127.0.0.1" for local execution.

### Usage Example
```python
from zxtouch.client import zxtouch
device = zxtouch("127.0.0.1")
```
```

--------------------------------

### Run individual test cases

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Commands to execute specific test methods within the IDLE test suite.

```bash
python -m unittest -v idlelib.idle_test.test_xyz.Test_case.test_meth
python -m test -m idlelib.idle_test.text_xyz.Test_case.test_meth test_idle
```

--------------------------------

### Run Coverage Analysis on Windows

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

A batch script to run coverage tests for a specific module and generate an HTML report.

```batch
@echo off
rem Usage: cover filename [test_ suffix] # proper case required by coverage
rem filename without .py, 2nd parameter if test is not test_filename
setlocal
set py=f:\dev\3x\pcbuild\win32\python_d.exe
set src=idlelib.%1
if "%2" EQU "" set tst=f:/dev/3x/Lib/idlelib/idle_test/test_%1.py
if "%2" NEQ "" set tst=f:/dev/ex/Lib/idlelib/idle_test/test_%2.py

%py% -m coverage run --pylib --source=%src% %tst%
%py% -m coverage report --show-missing
%py% -m coverage html
start htmlcov\3x_Lib_idlelib_%1_py.html
rem Above opens new report; htmlcov\index.html displays report index
```

--------------------------------

### show_keyboard()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Shows the on-screen keyboard if it is currently hidden.

```APIDOC
## show_keyboard()

### Description
Shows the keyboard if it is currently hiding.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is an error string if index 0 is False.
```

--------------------------------

### run_shell_command(command)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Executes a shell command on the device with root privileges.

```APIDOC
## run_shell_command(command)

### Description
Runs a shell command on the device as root.

### Parameters
- **command** (string) - Required - The shell command to execute.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is an error string if index 0 is False.
```

--------------------------------

### Define show_toast function

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Function signature and documentation for displaying toast notifications on the device.

```python
def show_toast(toast_type, content, duration, position=0, fontSize=0):
	"""show a toast
	
	Args:
        type: type of the toast. Please import zxtouch.toasttypes for the constant.
        content: content of the toast
        duration: how long the toast will appear before disappearing
        position: position of the toast. Please import zxtouch.toasttypes for the constant.
        
        For more information about the constants, please see code example below
	
	Returns: 
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""	"""
```

--------------------------------

### Guard GUI tests

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Use these snippets to ensure GUI tests are skipped in environments without graphical support.

```python
from test.support import requires
requires('gui')
```

--------------------------------

### Launch IDLE from Console

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/help.html

Command to launch IDLE from a console to view error messages if the application quits silently.

```bash
python -m idlelib
```

--------------------------------

### Run human-mediated tests

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Execute widget tests that require manual verification.

```bash
python -m idlelib.idle_test.htest
```

--------------------------------

### Run IDLE tests via command line

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Commands to execute automated unit tests or human-mediated tests from the terminal.

```bash
python -m test.test_idle
```

```bash
python -m idlelib.idle_test.htest
```

--------------------------------

### Displaying and inspecting strings with control characters in IDLE

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/help.html

Demonstrates how IDLE's Shell handles control characters and how the repr() function displays them compared to standard print output.

```python
>>> s = 'a\tb\a<\x02><\r>\bc\nd'
>>> len(s)
14
>>> s  # Display repr(s)
'a\tb\x07<\x02><\r>\x08c\nd'
>>> print(s, end='')  # Display s as is.
# Result varies by OS and font.  Try it.
```

--------------------------------

### touch_with_list(touch_list)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Performs multiple touch events simultaneously using a list of event dictionaries.

```APIDOC
## touch_with_list(touch_list)

### Description
Performs multiple touch events at the same time based on a provided list of event objects.

### Parameters
- **touch_list** (list) - Required - A list of dictionaries, where each dictionary contains: {"type": int, "finger_index": int, "x": int, "y": int}.

### Returns
- **None**
```

--------------------------------

### Define an IDLE Extension Class

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/extend.txt

A template for an IDLE extension class, demonstrating the structure for menu definitions and event handling.

```python
class ZoomHeight:

    menudefs = [
        ('edit', [
            None, # Separator
            ('_Zoom Height', '<<zoom-height>>'),
         ])
    ]

    def __init__(self, editwin):
        self.editwin = editwin

    def zoom_height_event(self, event):
        "...Do what you want here..."
```

--------------------------------

### Configure .coveragerc for IDLE

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Settings for coverage.py to enable branch coverage and exclude IDLE-specific test code from reports.

```ini
[run]
branch = True

[report]
# Regexes for lines to exclude from consideration
exclude_lines =
    # Don't complain if non-runnable code isn't run:
    if 0:
    if __name__ == .__main__.:

    .*# htest #
    if not _utest:
    if _htest:
```

--------------------------------

### get_device_info()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves comprehensive information about the connected device.

```APIDOC
## get_device_info()

### Description
Returns a dictionary containing device metadata including name, system name, version, model, and vendor identifier.

### Returns
- **result_tuple[0]** (bool) - True if the command executed successfully, False otherwise.
- **result_tuple[1]** (dict/str) - Error information if the first element is False; otherwise, a dictionary containing: {"name": str, "system_name": str, "system_version": str, "model": str, "identifier_for_vendor": str}.
```

--------------------------------

### show_alert_box(title, content, duration)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Displays a system-wide alert box on the device for a specified duration.

```APIDOC
## show_alert_box(title, content, duration)

### Description
Displays an alert box on the device screen.

### Parameters
- **title** (string) - Required - The title of the alert box.
- **content** (string) - Required - The content message of the alert box.
- **duration** (int) - Required - The time in seconds the alert box remains visible.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is an error string if index 0 is False.
```

--------------------------------

### play_script(script_absolute_path)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Executes a zxtouch script on the iOS device.

```APIDOC
## play_script(script_absolute_path)

### Description
Play a zxtouch script on the iOS device using its absolute file path.

### Parameters
- **script_absolute_path** (string) - Required - The absolute path of the script file.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is error information or an empty string.
```

--------------------------------

### Run Shell Command as Root

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Defines the function signature for executing shell commands on the device with root privileges.

```python
def run_shell_command(command):
    """Run shell command on device as root
		
	Args:
    	command: command to run
        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

--------------------------------

### Play Zxtouch Script

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Executes a zxtouch script file on the connected iOS device using its absolute path.

```python
def play_script(script_absolute_path):
    """Play a zxtouch script on iOS device.
		
	Args:
    	script_absolute_path: absolute path of the script
    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

--------------------------------

### Show Alert Box

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Defines the function signature for displaying a system-wide alert box with a specified duration.

```python
def show_alert_box(title, content, duration):
    """Show alert box on device

    Args:
        title: title of the alert box
        content: content of the alert box
        duration: the time the alert box shows before disappear

    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

--------------------------------

### get_screen_size()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves the screen dimensions of the device.

```APIDOC
## get_screen_size()

### Description
Get the screen size of the device in pixels.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success. If successful, index 1 contains a dictionary with 'width' and 'height' keys.
```

--------------------------------

### image_match(template_path, acceptable_value, max_try_times, scaleRation)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Matches a template image against the current screen content on the iOS device.

```APIDOC
## image_match(template_path, acceptable_value, max_try_times, scaleRation)

### Description
Matches the screen with a template image. Returns a tuple containing execution status and coordinate information if successful.

### Parameters
- **template_path** (string) - Required - Absolute path of the template image on the iOS device.
- **acceptable_value** (float) - Optional - Similarity threshold for a successful match (default 0.8).
- **max_try_times** (int) - Optional - Number of attempts to perform the match (default 4).
- **scaleRation** (float) - Optional - Scaling factor for the template image if matching fails due to size differences (default 0.8).

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating execution success, and index 1 is either an error string or a dictionary containing 'x', 'y', 'width', and 'height' of the matched area. If width and height are 0, the match was unsuccessful.
```

--------------------------------

### touch(type, finger_index, x, y)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Performs a single touch event on the screen at specified coordinates.

```APIDOC
## touch(type, finger_index, x, y)

### Description
Performs a single touch event at the specified screen coordinates.

### Parameters
- **type** (int) - Required - The touch event type (e.g., TOUCH_DOWN, TOUCH_MOVE, TOUCH_UP).
- **finger_index** (int) - Required - The finger index of the touch event (range 1-19).
- **x** (int) - Required - The x coordinate of the screen.
- **y** (int) - Required - The y coordinate of the screen.

### Returns
- **None**
```

--------------------------------

### Run IDLE tests from Shell

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Execute tests within an IDLE user process from the Shell.

```python
>>> import test.autotest
```

--------------------------------

### Run tests via Python interpreter

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Commands to run specific test modules or the entire test suite interactively.

```python
python -m idlelib.xyz
python -m idlelib.idle_test.test_xyz
```

```python
>>> import unittest
>>> unittest.main('idlelib.idle_test', verbosity=2)
```

--------------------------------

### Retrieve Battery Information

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Fetches current battery state and level from the device.

```python
def get_battery_info():
    """Get information of the battery
		
	Args:
		None
				    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise a dictionary containing battery_state, battery_level, battery_state_string.
						format of the dicionary: {"battery_state": ?, "battery_level": ?, "battery_state_string": ?}
    """
```

--------------------------------

### Define pick_color function

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Function signature and documentation for retrieving RGB color values from a screen coordinate.

```python
def pick_color(x, y):
    """Get the rgb value from the screen.
		
	Args:
   		x: x coordinate of the point on the screen
   		y: y coordinate of the point on the screen

    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise a dictionary containing red, green, blue of the point on screen.  
    """
```

--------------------------------

### Define image_match function

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

The function signature and docstring for matching a template image against the device screen.

```python
def image_match(template_path, acceptable_value=0.8, max_try_times=4, scaleRation=0.8):
    """Match screen with a template image
		
	Args:
    	template_path: absolute path of the template image on your iOS device.
    	acceptable_value: for a success match, what is the similarity of the template and parts you want to match on the screen.
    	scaleRation: if match failed due to the size difference between template image and image on screen, what should the size of the template image be for the next try.
    	max_try_times: how many times to try.
        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise a dictionary containing x, y, width, height of the template on screen. (see code example below)
		
		NOTICE: result_tuple[0] == True does not mean a success match, it only means no error happens while matching. To check whether it is a success match, check the width and height of the returned dictionary. If both width and height == 0, then it means match failed.
    """
```

--------------------------------

### Perform OCR and Language Support

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Functions for extracting text from screen regions and querying supported OCR languages.

```python
def ocr(self, region, custom_words=[], minimum_height="", recognition_level=0, languages=[], auto_correct=0, debug_image_path=""):
    """Get text from a region

    Args:
        region: a tuple containing start_x, start_y, width, height of the region to ocr. Format: (x, y, width, height)
        custom_words: an array of strings to supplement the recognized languages at the word recognition stage.
        minimum_height: the minimum height of the text expected to be recognized, relative to the image height. The default value is 1/32
        recognition_level: a value that determines whether the request prioritizes accuracy or speed in text recognition. 0 means accurate. 1 means faster.
        languages: an array of languages to detect, in priority order.  Default: english. Use get_supported_ocr_languages() to get the language list.
        auto_correct: whether ocr engine applies language correction during the recognition process. 0 means no, 1 means yes
        debug_image_path: debug image path. If you DONT want the ocr engine to output the debug image, leave it blank

    Returns:
        Result tuple: (success?, error_message/return value)

        if the operation successes, the return value will be an array of texts in the region.
    """
```

```python
def get_supported_ocr_languages(self, recognition_level):
    """Get languages that can be recognized by ocr

    Args:
        recognition_level: a value that determines whether the request prioritizes accuracy or speed in text recognition. 0 means accurate. 1 means faster.

    Returns:
        Result tuple: (success?, error_message/return value)

        if the operation successes, the return value will be an array of available languages .
    """
```

--------------------------------

### device.show_toast(toast_type, content, duration, position=0, fontSize=0)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Displays a toast notification on the connected device screen.

```APIDOC
## device.show_toast(toast_type, content, duration, position=0, fontSize=0)

### Description
Displays a toast notification on the device. Use constants from `zxtouch.toasttypes` for type and position parameters.

### Parameters
- **toast_type** (int) - Required - The type of toast (e.g., TOAST_SUCCESS, TOAST_ERROR).
- **content** (str) - Required - The text content to display.
- **duration** (float) - Required - How long the toast remains visible.
- **position** (int) - Optional - The screen position of the toast.
- **fontSize** (int) - Optional - The font size of the toast text.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is an error message string if index 0 is False.
```

--------------------------------

### Perform accurate sleep in zxtouch

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Use this method instead of standard Python sleep to ensure precise timing intervals.

```python
def accurate_usleep(microseconds):
    """Sleep for an accurate time
		
	Args:
    	microseconds: microseconds to sleep
        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

--------------------------------

### Add test execution block to module

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/layout/usr/lib/python3.7/idlelib/idle_test/README.txt

Boilerplate code to include at the end of a module to enable running tests directly.

```python
if __name__ == "__main__":
    from unittest import main
    main('idlelib.idle_test.test_abc', verbosity=2, exit=False)
```

--------------------------------

### Show the iOS keyboard

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Call this function to display the keyboard if it is currently hidden.

```python
def show_keyboard():
    """Show the keyboard
    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

--------------------------------

### Define single touch event function

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Function signature for performing a single touch event. Requires importing touch types from zxtouch.touchtypes.

```python
def touch(type, finger_index, x, y):
	"""Perform a touch event
	
	Args:
		type: touch event type. For touch event types, please insert "from zxtouch.touchtypes import *" at top of your script.
		finger_index: the finger index of the touch event. The range should be 1-19
		x: x coordinate of the screen
		y: y coordinate of the screen
	
	Returns: 
		None
	"""
```

--------------------------------

### accurate_usleep(microseconds)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Provides a method to sleep for an accurate duration in microseconds, bypassing standard Python sleep inaccuracies.

```APIDOC
## accurate_usleep(microseconds)

### Description
Sleeps for an accurate time duration in microseconds.

### Parameters
- **microseconds** (int) - Required - The number of microseconds to sleep.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is an error string if index 0 is False.
```

--------------------------------

### Force Stop Script

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Immediately terminates the execution of the currently running script on the device.

```python
def force_stop_script_play():
    """Force stop playing a script
		
	Args:
		None
				    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

--------------------------------

### get_battery_info()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves the current battery status and level from the device.

```APIDOC
## get_battery_info()

### Description
Retrieves information about the device battery, including state and level.

### Returns
- **Result tuple** (tuple) - A tuple where the first element is a boolean indicating success, and the second element is an error message or a dictionary containing 'battery_state', 'battery_level', and 'battery_state_string'.
```

--------------------------------

### Define multi-touch event function

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Function signature for performing multiple simultaneous touch events using a list of dictionaries.

```python
def touch_with_list(self, touch_list: list):
    """Perform touch events with a list of events
    touch list should be type of list. Inside the list, there must be dictionaries with the following format

    Args:
    	touch_list: format example: [{"type": ?, "finger_index": ?, "x": ?, "y": ?}]
    	
    Returns: 
    	None
    """
```

--------------------------------

### device.pick_color(x, y)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves the RGB color value from a specific coordinate on the device screen.

```APIDOC
## device.pick_color(x, y)

### Description
Captures the RGB color values from the specified (x, y) coordinate on the screen.

### Parameters
- **x** (int) - Required - The x coordinate on the screen.
- **y** (int) - Required - The y coordinate on the screen.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success. If successful, index 1 is a dictionary containing 'red', 'green', and 'blue' keys. If unsuccessful, index 1 contains the error message.
```

--------------------------------

### get_supported_ocr_languages()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves a list of languages supported by the OCR engine.

```APIDOC
## get_supported_ocr_languages(recognition_level)

### Description
Returns the list of languages available for OCR recognition based on the specified level.

### Parameters
- **recognition_level** (int) - Required - 0 for accurate, 1 for faster.

### Returns
- **Result tuple** (tuple) - A tuple where the first element is a boolean indicating success, and the second element is an array of available languages.
```

--------------------------------

### Insert text into fields

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Inserts text into the active field; use the backspace character '\b' to simulate deletions.

```python
def insert_text(text):
    """Insert text to the textfield
    
    Args:
    	text: text to insert (\b for deleting characters)
    	        
    Returns:
       Result tuple
		
		The format of the result tuple:
		result_tuple[0]: True if no error happens when executing the command on your device. False otherwise
		result_tuple[1]: error info if result_tuple[0] == False. Otherwise ""
    """
```

--------------------------------

### get_screen_orientation()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves the current orientation of the device screen.

```APIDOC
## get_screen_orientation()

### Description
Returns the current orientation of the screen as an integer value in string format.

### Returns
- **result_tuple[0]** (bool) - True if the command executed successfully, False otherwise.
- **result_tuple[1]** (str) - Error information if the first element is False; otherwise, the screen orientation.
```

--------------------------------

### hide_keyboard()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Hides the on-screen keyboard if it is currently visible.

```APIDOC
## hide_keyboard()

### Description
Hides the keyboard if it is currently showing.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is an error string if index 0 is False.
```

--------------------------------

### get_screen_scale()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Retrieves the scale factor of the device screen.

```APIDOC
## get_screen_scale()

### Description
Returns the scale of the screen as an integer value in string format.

### Returns
- **result_tuple[0]** (bool) - True if the command executed successfully, False otherwise.
- **result_tuple[1]** (str) - Error information if the first element is False; otherwise, the screen scale.
```

--------------------------------

### ocr()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Performs Optical Character Recognition on a specified region of the screen.

```APIDOC
## ocr(region, custom_words=[], minimum_height="", recognition_level=0, languages=[], auto_correct=0, debug_image_path="")

### Description
Extracts text from a defined region on the screen.

### Parameters
- **region** (tuple) - Required - (start_x, start_y, width, height) of the region.
- **custom_words** (array) - Optional - Strings to supplement recognized languages.
- **minimum_height** (string) - Optional - Minimum text height relative to image height.
- **recognition_level** (int) - Optional - 0 for accuracy, 1 for speed.
- **languages** (array) - Optional - Languages to detect in priority order.
- **auto_correct** (int) - Optional - 0 for no, 1 for yes.
- **debug_image_path** (string) - Optional - Path to save debug image.

### Returns
- **Result tuple** (tuple) - A tuple where the first element is a boolean indicating success, and the second element is an array of recognized texts.
```

--------------------------------

### force_stop_script_play()

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Stops the currently running script on the device.

```APIDOC
## force_stop_script_play()

### Description
Force the device to stop playing the current script.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is error information or an empty string.
```

--------------------------------

### move_cursor(offset)

Source: https://github.com/xuan32546/ios13-simulatetouch/blob/master/README.md

Moves the text cursor on a text field by a specified offset.

```APIDOC
## move_cursor(offset)

### Description
Move the text cursor on a text field. Use a negative offset to move left and a positive offset to move right.

### Parameters
- **offset** (int) - Required - The relative position to move the cursor.

### Returns
- **result_tuple** (tuple) - A tuple where index 0 is a boolean indicating success, and index 1 is error information or an empty string.
```
Tokens:
Raw