State Lock Overlay

A lightweight always-on-top Windows overlay that displays the real-time state of Caps Lock, Num Lock, and Scroll Lock using a minimal, draggable UI built with PyQt6.

👀 Preview

🔒 Lock & Auto-hide

📐 Axis-constrained movement (Shift)

🖱️ Move & Cursor feedback

✨ Features

• 🔒 Displays Caps Lock, Num Lock, and Scroll Lock states in real time
• 🪟 Frameless, transparent, always-on-top floating overlay
• 🖱️ Drag & drop positioning
• 📐 Optional axis-constrained movement while dragging (Shift key)
• 📌 Position locking / unlocking (middle mouse click)
• 👻 Automatic auto-hide when locked and inactive
• 💾 Persistent configuration stored as JSON
• 📐 Relative screen positioning (resolution-independent)
• 🖥️ Automatically adapts to screen resolution changes
• 🎨 Automatic Windows light / dark theme detection
• 🎯 Windows accent color integration
• ⚡ Very low CPU usage (timer-based polling)

---

🧠 How It Works

The application:

1. Reads the state of keyboard lock keys using the Win32 API (GetKeyState)
2. Draws circular indicators using QPainter
3. Polls system state using lightweight timers:
   • Keyboard lock state: 150 ms
   • Windows theme & accent color: 5 seconds
   • Z-order enforcement (always on top): 50 ms
4. Automatically shows the overlay when a lock state changes
5. Hides the overlay after a configurable timeout when position locking is enabled
6. Stores its relative screen position so it adapts to resolution changes

---

🖥️ Requirements

Runtime (script execution)

• Windows 11
• Python 3.10+ (recommended)
• Python packages:
  • PyQt6

⚠️ Compatibility Notice

This application has only been tested on Windows 11.
It has not been tested on other Windows versions, nor on non-Windows operating systems.
While it may work on Windows 10, compatibility is not guaranteed.

Install dependencies:

pip install PyQt6

---

▶️ Running the Application (Script)

python state_lock_overlay.py

On first launch, the overlay will appear near the bottom-right of the primary screen.

---

🖱️ Mouse Controls

Action	Mouse Button / Key
Move overlay	Left click + drag
Lock / unlock movement	Middle click
Save configuration & exit	Right click
Axis-constrained move	Hold Shift while dragging

---

💾 Configuration File

The application stores its persistent state in:

~/Documents/.state_lock_settings.json

Stored values

{
  "rel_x": 0.759,
  "rel_y": 0.962,
  "locked": false,
  "hide_timer_in_ms": 3000
}

Fields description

• rel_x, rel_y
  Relative screen position (0.0 – 1.0), resolution-independent

• locked
  Prevents accidental movement and enables auto-hide behavior

• hide_timer_in_ms
  Time (in milliseconds) after which the overlay automatically hides when locked and no state changes occur

---

🎨 Theme Handling

The overlay automatically adapts to Windows system settings:

• Detects light / dark mode
• Reads and applies the system accent color
• Adjusts inactive indicator contrast accordingly

This is handled via the Windows Registry:

• HKCU\Software\Microsoft\Windows\DWM
• HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize

---

🏗️ Building the Executable (.exe)

The project includes a ready-to-use build system based on PyInstaller, with size optimizations and UPX compression.

Included build files

• build.bat – Automated build script
• StateLockOverlay.spec – Custom PyInstaller specification
• upx.exe – Executable compression (optional but recommended)

Build requirements

• Windows 11
• Python 3.10+
• PyInstaller (installed automatically by the script)
• upx.exe available in PATH or project directory

Build steps

build.bat

The script will:

1. Verify Python installation
2. Install PyInstaller if missing
3. Clean previous build/ and dist/ folders
4. Build the executable using StateLockOverlay.spec
5. Produce the final binary

Output

dist/StateLockOverlay.exe

The executable is built with:

• ❌ No console window (console=False)
• 🧹 Excluded unused PyQt6 modules
• 📦 UPX compression enabled
• ⚡ Optimized startup and reduced size

---

🔄 Start with Windows (Optional)

To have State Lock Overlay start automatically when Windows boots, you can place the executable in the user startup folder.

Recommended method (simple & safe)

1. Press Win + R
2. Type:

shell:startup

3. Press Enter
4. Copy StateLockOverlay.exe (or a shortcut to it) into the folder that opens

On the next Windows startup, the overlay will launch automatically.

💡 Tip
Using a shortcut instead of the executable allows you to easily replace the binary or change its location without modifying the startup folder again.

---

🚀 Future Improvements (Planned / Friendly)

The codebase is intentionally structured to allow future extensions such as:

• 🖥️ Proper multi-monitor support
• 🐧 Linux support (requires replacing Win32 API usage and add fallbacks)
• ⚙️ System tray integration for options

---

📜 License

This project is provided as-is for personal or educational use.

You are free to modify, extend, and redistribute it.