From 6ff336710021537c44f11cbcf61b1338a327ce21 Mon Sep 17 00:00:00 2001 From: kuro Date: Thu, 19 Jun 2025 19:13:29 +0000 Subject: [PATCH] README.md added readme --- README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..487d5b6 --- /dev/null +++ b/README.md @@ -0,0 +1,151 @@ +# 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.