simple_program_launcher.txt

# Mouse Launcher

**Minimalist app launcher triggered by simultaneous Left+Right mouse click.**

Zero external dependencies - pure Python standard library (tkinter + ctypes).

![Windows](https://img.shields.io/badge/Windows-0078D6?style=flat&logo=windows)
![Python 3.8+](https://img.shields.io/badge/Python-3.8+-blue.svg)
![No Dependencies](https://img.shields.io/badge/Dependencies-None-green.svg)

---

## Features

- **L+R Click Trigger** - Press both mouse buttons simultaneously to show launcher
- **Instant Access** - Popup appears at cursor position
- **Hot Reload** - Edit `config.json` anytime, changes apply on next trigger
- **Keyboard Shortcuts** - Press 1-9 to launch items quickly
- **Click Outside to Close** - Or press Escape
- **Separators** - Organize items into groups
- **Auto Start** - Optional Windows startup integration

---

## Quick Start

```bash
# Run directly
pythonw launcher.pyw

# Or with visible console (for debugging)
python launcher.pyw
```

**Usage:** Press **Left + Right mouse buttons** together anywhere on screen.

---

## Configuration

Edit `config.json` to customize your launcher:

```json
{
  "items": [
    {"name": "My App", "path": "C:\\path\\to\\app.exe", "icon": "🚀"},
    {"name": "Project Folder", "path": "D:\\Projects", "icon": "📁"},
    {"name": "─────────────", "path": "", "icon": " ", "separator": true},
    {"name": "Notepad", "path": "notepad.exe", "icon": "📝"},
    {"name": "Calculator", "path": "calc.exe", "icon": "🔢"}
  ]
}
```

### Item Properties

| Property | Required | Description |
|----------|----------|-------------|
| `name` | Yes | Display name |
| `path` | Yes | Full path to exe/file/folder, or system command |
| `icon` | No | Emoji or character (default: ▶) |
| `separator` | No | Set `true` for non-clickable divider line |

---

## Auto Start (Windows)

### Method 1: VBS Script (Silent, No Console Flash)

1. Press `Win+R`, type `shell:startup`, press Enter
2. Create `MouseLauncher.vbs` with this content:

```vbs
' MouseLauncher.vbs - Silent startup script
' Launches pythonw without any visible window
Set WshShell = CreateObject("WScript.Shell")
WshShell.Run "pythonw ""D:\path\to\launcher.pyw""", 0, False
```

**How it works:**
- `WScript.Shell.Run` executes a command
- `pythonw` runs Python without console window
- Second parameter `0` = hidden window
- `False` = don't wait for completion

### Method 2: BAT File (Simple, Brief Console Flash)

Create `MouseLauncher.bat` in `shell:startup`:

```bat
@echo off
start "" pythonw "D:\path\to\launcher.pyw"
```

**Note:** BAT shows a brief black console flash on startup. VBS method is cleaner.

### Startup Folder Location

```
C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
```

Or access via: `Win+R` → `shell:startup`

---

## How It Works

### Architecture

```
┌─────────────────────────────────────────────────────┐
│  MouseLauncher (Main Controller)                    │
│  ├── Polls mouse state every 30ms via Windows API  │
│  ├── Detects L+R simultaneous press                │
│  └── Manages popup lifecycle                        │
├─────────────────────────────────────────────────────┤
│  LauncherPopup (UI)                                 │
│  ├── Borderless tkinter window                     │
│  ├── Loads config.json fresh on each show          │
│  └── Click-outside detection with debounce         │
└─────────────────────────────────────────────────────┘
```

### Key Technical Decisions

**1. Polling vs Hooks**
```python
# Using GetAsyncKeyState polling (simple, reliable)
left = user32.GetAsyncKeyState(VK_LBUTTON) & 0x8000
right = user32.GetAsyncKeyState(VK_RBUTTON) & 0x8000

# Why not SetWindowsHookEx?
# - Hooks require message pump in separate thread
# - 64-bit type issues with ctypes callbacks
# - Polling at 30ms is imperceptible and CPU-light
```

**2. Click-Outside Detection Challenge**
```python
# Problem: L+R triggers popup, but L is still held
# → Immediately detected as "click outside" → closes instantly

# Solution: Wait for BOTH buttons to release first
if not self._buttons_released:
    if not left and not right:
        self._buttons_released = True  # Now start listening
    return  # Keep waiting
```

**3. Hot Reload Config**
```python
def show(self, x, y):
    items = self._load_items()  # Fresh load every time!
    # No restart needed when editing config.json
```

**4. Launch Strategy**
```python
if os.path.exists(path):
    os.startfile(path)      # Files, folders, URLs
else:
    subprocess.Popen(path, shell=True)  # System commands
```

---

## Full Source Code

<details>
<summary>launcher.pyw (~230 lines)</summary>

```python
"""
Mouse Launcher - L+R Click to Launch
Minimalist launcher with zero external dependencies
"""
import ctypes
import json
import os
import subprocess
import time
import tkinter as tk
from pathlib import Path

# Windows API for mouse state detection
user32 = ctypes.windll.user32
VK_LBUTTON, VK_RBUTTON = 0x01, 0x02


class POINT(ctypes.Structure):
    """Windows POINT structure for cursor position"""
    _fields_ = [("x", ctypes.c_long), ("y", ctypes.c_long)]


CONFIG_FILE = Path(__file__).parent / "config.json"
POLL_MS = 30  # Mouse polling interval


class LauncherPopup:
    """Floating popup window with pinned items"""

    BG = "#1a1a2e"      # Dark background
    FG = "#ffffff"      # White text
    HOVER = "#2d2d44"   # Hover highlight
    ITEM_HEIGHT = 36
    WIDTH = 240

    def __init__(self, root, on_close):
        self.root = root
        self.on_close = on_close
        self.win = None
        self._closing = False

    def _load_items(self):
        """Load items fresh from config (hot reload support)"""
        if CONFIG_FILE.exists():
            try:
                with open(CONFIG_FILE, "r", encoding="utf-8") as f:
                    return json.load(f).get("items", [])
            except:
                pass
        # Fallback defaults
        return [
            {"name": "Notepad", "path": "notepad.exe", "icon": "📝"},
            {"name": "Explorer", "path": "explorer.exe", "icon": "📁"},
        ]

    def show(self, x, y):
        if self.win or self._closing:
            return

        items = self._load_items()

        # Create borderless, always-on-top window
        self.win = tk.Toplevel(self.root)
        self.win.overrideredirect(True)
        self.win.attributes("-topmost", True)
        self.win.attributes("-alpha", 0.95)
        self.win.configure(bg=self.BG)

        # Position at cursor, keep on screen
        height = len(items) * self.ITEM_HEIGHT + 16
        screen_w = self.root.winfo_screenwidth()
        screen_h = self.root.winfo_screenheight()
        x = min(x, screen_w - self.WIDTH - 10)
        y = min(y, screen_h - height - 40)
        self.win.geometry(f"{self.WIDTH}x{height}+{x}+{y}")

        # Build item list
        frame = tk.Frame(self.win, bg=self.BG)
        frame.pack(fill="both", expand=True, padx=8, pady=8)

        for i, item in enumerate(items):
            self._create_item(frame, item, i)

        self.win.bind("<Escape>", lambda e: self.hide())
        self.win.focus_force()

        # Start click-outside detection after buttons released
        self._buttons_released = False
        self.win.after(50, self._check_click_outside)

    def _create_item(self, parent, item, index):
        icon = item.get("icon", "▶")
        name = item.get("name", "Unknown")
        path = item.get("path", "")
        is_sep = item.get("separator", False)

        if is_sep:
            # Non-clickable separator line
            lbl = tk.Label(parent, text=f"  {name}", font=("Segoe UI", 9),
                          bg=self.BG, fg="#555555", anchor="center", pady=2)
            lbl.pack(fill="x", pady=0)
            return

        # Clickable item
        lbl = tk.Label(parent, text=f" {icon}  {name}", font=("Segoe UI", 11),
                      bg=self.BG, fg=self.FG, anchor="w", padx=8, pady=4,
                      cursor="hand2")
        lbl.pack(fill="x", pady=2)

        # Hover effects
        lbl.bind("<Enter>", lambda e: lbl.configure(bg=self.HOVER))
        lbl.bind("<Leave>", lambda e: lbl.configure(bg=self.BG))
        lbl.bind("<Button-1>", lambda e: self._launch(path))

        # Keyboard shortcut (1-9)
        if index < 9:
            self.win.bind(str(index + 1), lambda e, p=path: self._launch(p))

    def _launch(self, path):
        self.hide()
        if path:
            try:
                if os.path.exists(path):
                    os.startfile(path)
                else:
                    subprocess.Popen(path, shell=True)
            except Exception as e:
                print(f"Launch error: {e}")

    def _check_click_outside(self):
        if not self.win or self._closing:
            return

        left = user32.GetAsyncKeyState(VK_LBUTTON) & 0x8000
        right = user32.GetAsyncKeyState(VK_RBUTTON) & 0x8000

        # Wait for trigger buttons to release first
        if not self._buttons_released:
            if not left and not right:
                self._buttons_released = True
            self.win.after(50, self._check_click_outside)
            return

        # Detect fresh left click outside window
        if left and not right:
            pt = POINT()
            user32.GetCursorPos(ctypes.byref(pt))
            try:
                wx, wy = self.win.winfo_rootx(), self.win.winfo_rooty()
                ww, wh = self.win.winfo_width(), self.win.winfo_height()
                if not (wx <= pt.x <= wx + ww and wy <= pt.y <= wy + wh):
                    self.hide()
                    return
            except tk.TclError:
                pass

        if self.win:
            self.win.after(50, self._check_click_outside)

    def hide(self):
        if self._closing:
            return
        self._closing = True

        if self.win:
            try:
                self.win.destroy()
            except:
                pass
            self.win = None

        # Debounce before allowing next popup
        self.root.after(300, self._finish_close)

    def _finish_close(self):
        self._closing = False
        self.on_close()


class MouseLauncher:
    """Main controller - polls mouse and manages popup"""

    def __init__(self):
        self.root = tk.Tk()
        self.root.withdraw()  # Hide root window

        self.popup = LauncherPopup(self.root, self._on_popup_close)
        self._popup_shown = False
        self._both_were_up = True
        self._last_trigger = 0

    def _poll_mouse(self):
        """Check for L+R simultaneous press"""
        left = user32.GetAsyncKeyState(VK_LBUTTON) & 0x8000
        right = user32.GetAsyncKeyState(VK_RBUTTON) & 0x8000

        if left and right:
            now = time.time()
            if self._both_were_up and not self._popup_shown:
                if now - self._last_trigger > 0.5:  # Debounce 500ms
                    self._both_were_up = False
                    self._last_trigger = now
                    pt = POINT()
                    user32.GetCursorPos(ctypes.byref(pt))
                    self._show_popup(pt.x, pt.y)
        elif not left and not right:
            self._both_were_up = True

        self.root.after(POLL_MS, self._poll_mouse)

    def _show_popup(self, x, y):
        self._popup_shown = True
        self.popup.show(x, y)

    def _on_popup_close(self):
        self._popup_shown = False

    def run(self):
        self.root.after(100, self._poll_mouse)
        self.root.mainloop()


if __name__ == "__main__":
    MouseLauncher().run()
```

</details>

---

## License

MIT License - Use freely, modify as needed.

---

*Built with Python, zero dependencies, maximum simplicity.*