🖱️ SikuliX 2.0.5 – Detect Mouse Pointer Idle or Busy State (Solved)

If you’ve ever automated a desktop app with SikuliX, you know how useful it is for visual-based scripting. But sometimes, you need to go one level deeper — for instance, detecting whether the mouse pointer is currently busy (spinning wheel) or idle.

In SikuliX 2.0.5, this isn’t directly supported through the Python-like API, but it’s possible with a small trick involving Java Native Access (JNA).

⚙️ The Problem

When running scripts that interact with Windows UI, SikuliX can sometimes click while the system is still “busy” (like during a loading spinner).

I wanted to check the cursor’s state (idle or busy) before the next automation step — but the built-in Sikuli functions couldn’t detect that.

So I built a lightweight Java helper that works perfectly with SikuliX 2.0.5.

🧰 The Working Solution

The approach involves:

Using JNA (Java Native Access) to talk to the Windows API.
Packaging it properly into a JAR file.
Making sure the manifest file is valid (Sikuli is very sensitive to this!).

🪶 Step 1. Create a Manifest File

Your MANIFEST.MF file should look exactly like this — with an empty line at the end:

Manifest-Version: 1.0
Main-Class: newmain
Class-Path: lib/jna.jar lib/jna-platform.jar

If that last blank line is missing, Sikuli will refuse to load your dependencies.

⚙️ Step 2. Compile and Package

Use JDK 1.8 (older JDKs are best for SikuliX compatibility) to create your JAR file:

E:\jdk1_8_0_202\bin\jar cfm Jar.jar MANIFEST.MF *.class

This packages your compiled .class files and manifest into a single JAR.

🧩 Step 3. Load the JAR in SikuliX

Once compiled, you can import and use it inside Sikuli’s Jython environment:

sys.path.append("E:\\Downloads\\jarf\\withdependency\\newmain.jar")
import newmain

ct = newmain.cursor_type()
print(ct.getCode())           # Displays the cursor code
print(ct.getCode() == 32514)  # True if the pointer is "busy"

The cursor code represents the Windows system cursor type:

32512 → Normal arrow
32514 → Busy (spinning circle)

You can use this logic to pause your Sikuli automation until the mouse pointer returns to idle.

✅ Tips and Notes

Always end your MANIFEST.MF file with a newline.
Stick to JDK 1.8, since SikuliX 2.0.5’s Jython runtime can behave unpredictably with newer JDKs.
JNA JARs must be referenced with relative paths inside the manifest.

💡 Use Case Example

In a UI automation flow, you could write:

while newmain.cursor_type().getCode() == 32514:
    wait(0.5)

This ensures Sikuli waits until the mouse pointer becomes idle before continuing.

🧭 Final Thoughts

Detecting the mouse pointer’s busy state in SikuliX might not seem straightforward, but with a small helper class and proper JNA setup, it’s completely doable.

This approach gives you fine-grained control in automation scripts — perfect for handling slow-loading apps, modal popups, or background tasks.

Author: Algolassi
Published on: October 9, 2025
Category: Automation, Java, SikuliX
Tags: sikulix, jna, java, manifest, ui-automation, algolassi