keypresser/README.md

# Jarvis Key Press Utility

A robust Python-based utility with a Tkinter GUI to automate single key press/release actions in a specific target window, leveraging AutoHotkey v2 for precise control. Designed with the Model-View-Controller (MVC) architectural pattern for enhanced modularity and maintainability.

## Table of Contents
- [Features](#features)
- [Project Structure](#project-structure)
- [Setup & Installation](#setup--installation)
  - [Prerequisites](#prerequisites)
  - [Cloning the Repository](#cloning-the-repository)
  - [Installing Python Dependencies](#installing-python-dependencies)
- [Usage](#usage)
  - [Running the Python Script](#running-the-python-script)
  - [Configuring Logging](#configuring-logging)
  - [Building the Executable](#building-the-executable)
- [Debugging Tips](#debugging-tips)
- [Contributing](#contributing)
- [License](#license)

## Features

* **Proactive Window Activation:** Automatically activates the specified target window before sending key presses, ensuring commands are directed correctly.
* **Precise Key Control:** Sends a single keydown event when the target window is active, and a single keyup event when it becomes inactive or the script/application exits.
* **Configurable Stop Key:** Uses a global hotkey (default: F6) to immediately stop the automated key presses and terminate the AutoHotkey script.
* **Graphical User Interface (GUI)::** Intuitive Tkinter interface for selecting the key to press and the target window.
* **Modular Architecture (MVC):** Clearly separates Model (application logic & state), View (GUI), and Controller (event handling) into distinct files.
* **Centralized Logging:** Detailed logging to console and a dynamically named file (`.log`), with configurable verbosity via `config.ini`.
* **External AutoHotkey Template:** The core AutoHotkey script logic is kept in a separate `template.ahk` file for easier AHK-specific debugging and modification.
* **Robust AutoHotkey.exe Discovery:** Automatically searches for the AutoHotkey executable in common installation paths or within the PyInstaller bundle.
* **Executable Compilation:** Includes a batch script for easy compilation into a standalone `.exe` with PyInstaller, bundling AutoHotkey.exe and necessary resources.

## Project Structure

The project is organized to separate concerns and facilitate development:

```
project_root/
├── main.py                     # Application entry point (initializes MVC, logging)
├── model/                      # Contains core application logic and data management
│   ├── key_press_model.py      # The main Model class (orchestrates sub-models)
│   ├── constants.py            # Global constants, mappings (e.g., STOP_KEY, AHK_KEY_MAP)
│   ├── app_logger.py           # Centralized logging setup and message queue management
│   ├── ahk_process_manager.py  # Handles AHK script generation, execution, monitoring, cleanup, pynput listener
│   └── window_manager.py       # Utility for retrieving active window titles
├── view/                       # Contains all Tkinter GUI elements and layout
│   └── view.py
├── controller/                 # Handles user input and orchestrates Model/View updates
│   ├── controller.py           # Main Controller class (high-level application logic)
│   └── ui_controller.py        # UI-specific interactions (e.g., button state, validation display)
├── resources/                  # Contains static assets
│   └── template.ahk            # AutoHotkey script template loaded by the Python script
├── scripts/                    # Contains utility scripts for development/deployment
│   └── exe_compile.cmd         # Batch script for building the standalone .exe
├── config.ini                  # Logging configuration file (generated on first run if not present)
└── bin/                        # Output directory for compiled executable and build artifacts
    ├── build/                  # PyInstaller's temporary build directory
    └── dist/                   # PyInstaller's output directory (contains JarvisKeyPressUtility.exe)
    └── JarvisKeyPressUtility.spec  # PyInstaller's spec file
```

## Setup & Installation

### Prerequisites

* **Python 3.8+**: Download from [python.org](https://www.python.org/downloads/). Ensure `pip` is included in your installation.
* **AutoHotkey v2**: Download and install from [autohotkey.com](https://www.autohotkey.com/v2/download/). The utility expects it to be in its default installation path (`C:\Program Files\AutoHotkey\v2\AutoHotkey.exe`), or detectable via system PATH.

### Cloning the Repository

```bash
git clone [https://wiccafe.de/kuro/KeyPresser.git](https://wiccafe.de/kuro/KeyPresser.git)
cd KeyPresser
```

### Installing Python Dependencies

Navigate to your project's root directory in your terminal or command prompt (where `main.py` is located) and run:

```bash
pip install -r requirements.txt
```

*(Note: You might need to create a `requirements.txt` file by running `pip freeze > requirements.txt` after installing `pynput`, `pyautogui`, `pygetwindow` manually, or simply install them directly if preferred)*:

```bash
pip install pynput pyautogui pygetwindow
```

## Usage

### Running the Python Script

To run the application directly from the source code:

```bash
python main.py
```

The GUI window will appear, and console output will show log messages. A `.log` file will also be created in the execution directory.

### Configuring Logging

On the first run, a `config.ini` file will be generated in the project root. You can modify this file to adjust logging verbosity:

```ini
[Logging]
file_log_level = DEBUG    ; e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL
console_log_level = INFO  ; e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL
```

* `file_log_level`: Controls the minimum level of messages written to the `.log` file.
* `console_log_level`: Controls the minimum level of messages displayed in the console.

### Building the Executable

To create a standalone executable (`.exe`), use the provided batch script:

1.  Navigate to the `scripts/` directory in your terminal:

    ```bash
    cd scripts/
    ```

2.  Run the compilation batch script:

    ```bash
    exe_compile.cmd
    ```

This script will:

* Clean up previous build artifacts in the `bin/` directory.
* Run PyInstaller to compile `main.py` into a single executable.
* Bundle `AutoHotkey.exe` and the `resources/` folder (containing `template.ahk`) inside the `.exe`.
* Place the compiled executable (`JarvisKeyPressUtility.exe`) in the `bin/dist/` folder.

## Debugging Tips

* **Python Console Output:** When running `main.py`, pay attention to the console output. This provides immediate feedback from the Python application.
* **Application Log File:** Check the `.log` file (e.g., `JarvisKeyPressUtility_YYYY-MM-DD_HH-MM-SS.log`) generated in the execution directory. This contains more detailed Python logging, especially if `file_log_level` in `config.ini` is set to `DEBUG`.
* **AutoHotkey Log File:** The AutoHotkey script itself generates a temporary log file (`jarvis_ahk_log_*.log`) in your user's temporary directory (e.g., `C:\Users\YourUser\AppData\Local\Temp`). This log provides direct insights into AutoHotkey's actions (window activation, key sends). The Python UI's log window also displays `[AHK]` messages from this file.
* **UI Feedback:** The GUI's log area will show `[AHK]` messages from the AutoHotkey script and Python warnings/errors (configured via `ui_log_level` in `config.ini`, default: WARNING). Validation labels will also guide correct input.
* **AHT Hotkey Issues:** If AutoHotkey errors persist, you can temporarily copy the generated `jarvis_ahk_*.ahk` file from your temp directory and run it directly with AutoHotkey to get more specific AHK error messages from its built-in debugger.

## Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests.

## License

This project is licensed under the MIT License - see the LICENSE.md file for details.