Actions Library API

Here are the basic built-in methods for controlling the mouse and keyboard safely.

macro_studio.actions

taskSleep

Python

taskSleep(duration: float = 0.01) -> Generator[float]

Pauses the task execution for a specified duration.

This is a non-blocking operation that yields control back to the worker for the given duration. It allows the application to remain responsive while the task is "sleeping".

Parameters:

Name	Type	Description	Default
`duration`	`float`	The time in seconds to pause the task. Defaults to 0.01 seconds.	`0.01`

Yields:

Type	Description
`Generator[float]`	The duration in seconds to sleep.

Raises:

Type	Description
`TaskInterruptedException`	If the task is hard-paused while sleeping.

taskWaitForResume

Python

taskWaitForResume() -> Iterator[None]

Yields control until the controller's hard-pause state is cleared.

This function is non-blocking and will cause the task to wait indefinitely until the main application signals that it should resume.

Yields:

Name	Type	Description
`None`	`None`	Indicates that the task should wait for an external resume signal.

holdKey

Python

holdKey(key_name: str) -> Iterator[None]

Context manager to hold down a keyboard key and ensure its release.

This context manager handles pressing a key down at the start of the with block and guarantees that the key is released when exiting the block, even if an exception occurs.

Parameters:

Name	Type	Description	Default
`key_name`	`str`	The name of the key to hold down (e.g., 'shift', 'a', 'enter').	required

Yields:

Name	Type	Description
`None`	`None`	The execution context within the `with` statement.

taskHoldKey

Python

taskHoldKey(key_name: str, duration: float) -> Iterator[float | None]

Holds a keyboard key for a specified duration within a task.

This function presses a key, holds it for the given duration using taskSleep, and then releases it. If the task is hard-paused during the hold, the key is released immediately, and the task waits for resume.

Parameters:

Name	Type	Description	Default
`key_name`	`str`	The name of the key to hold down.	required
`duration`	`float`	The duration in seconds to hold the key.	required

Yields:

Name	Type	Description
`float`	`float \| None`	The duration to sleep from `taskSleep`, or None from `taskWaitForResume`.

mouseClick

Python

mouseClick(coords: QPoint = None, button: str = MOUSE_PRIMARY) -> Iterator[None]

Context manager to perform a mouse click (press and release).

This context manager presses a mouse button at specified coordinates (or current position if coords is None) at the start of the with block. It guarantees the mouse button is released when exiting the block, even if an exception occurs. A small random offset is added to the release coordinates if coords are provided to simulate human-like mouse movement.

Parameters:

Name	Type	Description	Default
`coords`	`QPoint`	A QPoint object specifying the (x, y) coordinates for the click. If None, the current mouse position is used. Defaults to None.	`None`
`button`	`str`	The mouse button to press ('left', 'right', 'middle'). Defaults to MOUSE_PRIMARY ('left').	`MOUSE_PRIMARY`

Yields:

Name	Type	Description
`None`	`None`	The execution context within the `with` statement.

taskMouseClick

Python

taskMouseClick(coords: QPoint = None, button: str = MOUSE_PRIMARY) -> Iterator[float | None]

Performs a mouse click (press and release) within a task.

This function presses a mouse button at the given coordinates, yields for a short duration using taskSleep, and then releases the button. If the task is hard-paused during the click, the mouse button is released immediately, and the task waits for resume.

Parameters:

Name	Type	Description	Default
`coords`	`QPoint`	A QPoint object specifying the (x, y) coordinates for the click. If None, the current mouse position is used. Defaults to None.	`None`
`button`	`str`	The mouse button to use ('left', 'right', 'middle'). Defaults to MOUSE_PRIMARY ('left').	`MOUSE_PRIMARY`

Yields:

Name	Type	Description
`float`	`float \| None`	The duration to sleep from `taskSleep`, or None from `taskWaitForResume`.

taskPasteText

Python

taskPasteText(text_to_paste: str) -> Generator[float]

Pastes the given text using Ctrl+V after copying it to the clipboard.

This function temporarily stores the current clipboard content, copies the text_to_paste to the clipboard, simulates a Ctrl+V key combination, and then restores the original clipboard content.

Parameters:

Name	Type	Description	Default
`text_to_paste`	`str`	The string content to be pasted.	required

Yields:

Name	Type	Description
`float`	`Generator[float]`	The duration to sleep from `taskSleep`.