_{Official ZPE/YASS documentation}AutoGUI object

Introduction

The AutoGUI object provides a small set of native functions for automating basic user input such as moving the mouse and sending key / mouse presses.

Internally, AutoGUI uses Java's java.awt.Robot class to generate native input events. As a result, the object cannot be created in a headless (non-GUI supporting) environment. If ZPE is running headlessly, attempting to create an AutoGUI object will print an error and the object will not function.

All functions exposed by this object require a permission level of 4.

AutoGUI object functions

The following is a list of internal functions the AutoGUI object exposes. All functions are ZPEObjectNativeFunctions therefore run in native code.

position_mouse(number x, number y) ⇒ boolean

Moves the mouse pointer to the specified screen coordinate. Returns true if the operation was successful, otherwise false.

press_mouse(string button) ⇒ boolean

Presses (but does not release) the specified mouse button. The button parameter must be a numeric value (as a string) representing a mouse button mask compatible with Java's Robot API. Returns true if the operation was successful, otherwise false.

press_key(string key) ⇒ boolean

Presses (but does not release) the specified key. The key parameter must be a numeric value (as a string) representing a key code compatible with Java's Robot API (for example, values from java.awt.event.KeyEvent). Returns true if the operation was successful, otherwise false.

Examples

The following example moves the mouse to a position near the top-left of the screen and presses the left mouse button:

$gui = new AutoGUI()

# Move the mouse to x=50, y=50
$gui->position_mouse(50, 50)

# Press the left mouse button (button mask as a string)
$gui->press_mouse("16")

This example presses a key using a key code:

$gui = new AutoGUI()

# Press a key using its key code (as a string)
$gui->press_key("10")

Notes:

• Key and button codes: AutoGUI expects numeric codes provided as strings. These codes must match the constants used by Java's Robot API (for example key codes from java.awt.event.KeyEvent and mouse button masks from java.awt.event.InputEvent).
• Press vs release: The current AutoGUI API only provides press functions. If you need click behaviour (press + release) or key release, these would require additional functions.
• Security: All functions require permission level 4.