Skip to content

Engine API

macro_studio.MacroStudio

Python
MacroStudio(macro_name: str = 'Default')

The central engine for managing and executing macros.

This class provides the main interface for registering tasks, managing variables, controlling the UI overlay, and handling the overall execution lifecycle of macros.

To use the engine, instantiate it and call launch():

Python
1
2
main_studio = MacroStudio()
main_studio.launch()

Initializes the MacroStudio engine.

Parameters:

Name Type Description Default
macro_name str

An optional name for the initial macro profile to load. If not provided, "Default" will be used.

 'Default'

Attributes

repeat_delay property writable

Python
repeat_delay: float

The delay (in seconds) applied between repetitions of tasks.

Returns:

Type Description
float

The current repeat delay in seconds.

Functions

addVar

Python
addVar(key: Hashable, data_type: CaptureMode | type, default_val: object = None, pick_hint: str = None)

Adds a user-definable variable to the current profile.

These variables can be configured by the user through the UI and their values can be retrieved during task execution.

Parameters:

Name Type Description Default
key Hashable

A unique, hashable identifier for the variable (e.g., a string).

 required
data_type CaptureMode | type

The expected data type or capture mode for the variable. Can be a Python type (e.g., int, str) or a CaptureMode enum member (e.g., CaptureMode.POINT, CaptureMode.REGION).

 required
default_val object

The initial default value for the variable.

 None
pick_hint str

A descriptive hint displayed to the user when they are prompted to "pick" a value for this variable (e.g., "Click a point on screen").

 None

getVar

Python
getVar(key: Hashable) -> Any | None

Retrieves the current value of a registered setup variable from the current profile.

Parameters:

Name Type Description Default
key Hashable

The hashable identifier of the variable to retrieve.

 required

Returns:

Type Description
Any | None

The current value of the variable if found, otherwise None.

addBasicTask

Python
addBasicTask(task_func: TaskFunc, *args: Any, enabled: bool = True, repeat: bool = False, display_name: str | None = None, **kwargs: Any) -> Controller

Registers a basic task function for execution within the macro studio.

Basic tasks run sequentially and are managed directly by the main execution thread.

Parameters:

Name Type Description Default
task_func TaskFunc

The Python function that defines the task's logic. It should be a generator function that yields control to the engine.

 required
*args Any

Positional arguments to pass to task_func when it is executed.

 ()
enabled bool

If True, the task will be included in the execution cycle when startExecution() is called. Defaults to True.

 True
repeat bool

If True, the task will automatically restart upon completion. Defaults to False.

 False
display_name str | None

An optional name to display for this task in the UI. If None, the function's __name__ will be used.

 None
**kwargs Any

Keyword arguments to pass to task_func when it is executed.

 {}

Returns:

Type Description
TaskContext

A TaskContext object, which is a handle to the registered task allowing for programmatic control (e.g., pausing, stopping).

addThreadTask

Python
addThreadTask(fun_in_thread: TaskFunc, *args: Any, enabled: bool = True, repeat: bool = False, display_name: str | None = None, **kwargs: Any) -> ThreadedController

Registers an advanced task function to run in a separate thread.

Threaded tasks execute concurrently with other tasks and the main UI thread, suitable for long-running or blocking operations that shouldn't halt the UI.

Parameters:

Name Type Description Default
fun_in_thread TaskFunc

The Python function that defines the task's logic. It should be a generator function that yields control to the engine.

 required
*args Any

Positional arguments to pass to fun_in_thread when it is executed.

 ()
enabled bool

If True, the task will be included in the execution cycle when startExecution() is called. Defaults to True.

 True
repeat bool

If True, the task will automatically restart upon completion. Defaults to False.

 False
display_name str | None

An optional name to display for this task in the UI. If None, the function's __name__ will be used.

 None
**kwargs Any

Keyword arguments to pass to fun_in_thread when it is executed.

 {}

Returns:

Type Description
ThreadContext

A ThreadedController object, which is a handle to the registered threaded task allowing for programmatic control.

getController

Python
getController(name_or_id: str | int) -> Union[Controller, ThreadedController, None]

Retrieves a task or thread controller handle by its name or internal ID.

Note: For coded tasks, the display_name provided during registration is used for lookup, not the function's __name__.

Parameters:

Name Type Description Default
name_or_id str | int

The display name (string) or internal ID (integer) of the task.

 required

Returns:

Type Description
Union[TaskContext, ThreadContext, None]

The TaskContext or ThreadedController instance if found, otherwise None.

isRunningTasks

Python
isRunningTasks() -> bool

Checks if any tasks are currently running or paused.

Returns:

Type Description
bool

True if the execution engine is active (running or paused), False otherwise.

startExecution

Python
startExecution()

Initiates or resumes the execution of registered tasks.

If the engine is currently paused, this method will resume its execution. If no tasks are running, it will start the execution worker and update the UI visuals.

cancelExecution

Python
cancelExecution(completed: bool = False)

Cancels all currently executing tasks and stops the execution engine.

This will stop any running tasks and reset the UI visuals.

Parameters:

Name Type Description Default
completed bool

If True, indicates that the cancellation is due to all tasks having completed successfully, rather than an explicit user cancellation. Defaults to False.

 False

pauseExecution

Python
pauseExecution(interrupt: bool = False) -> bool

Pauses the currently running tasks.

Parameters:

Name Type Description Default
interrupt bool

Controls the mechanism used to pause.

  • True: Interrupt & Cleanup. Raises a TaskInterruptedException inside the task. This breaks the current step immediately (e.g., cuts short a taskSleep), runs any try/finally cleanup blocks to release keys and reset state, and then suspends.
  • False: Freeze. Suspends the generator execution at the exact current line. No cleanup logic is triggered; held keys remain held and local variables are preserved exactly as-is.
 False

Raises:

Type Description
ValueError

If the provided delay is a negative value.

Returns:

Type Description
bool

True if the pause command was issued successfully; False if the engine could not be paused (e.g., worker was already stopped).

isPaused

Python
isPaused() -> bool

Checks if the execution engine is currently in a paused state.

Returns:

Type Description
bool

True if the engine is paused, False otherwise.

resumeExecution

Python
resumeExecution() -> Union[float, None]

Resumes macro execution if it was previously paused.

Returns:

Type Description
Union[float, None]

The duration in seconds for which the execution was paused, or None if the engine was not paused or could not be resumed.

launch

Python
launch()

Initializes the UI, loads the default profile, and starts the main application loop.

This method must be called after configuring your tasks and variables using addBasicTask, addThreadTask, and addVar. It blocks until the application exits.

Raises:

Type Description
SystemExit

When the Qt application event loop finishes.