KeyPress/readme.md

# KeyPressRemark

一个功能强大的Windows按键模拟工具，支持向指定窗口发送按键和鼠标点击事件。本工具特别适用于游戏辅助、自动化测试、重复性操作等场景。

## 🚀 功能特性

- **精准窗口选择**：通过点击选择目标窗口，无需手动查找窗口句柄
- **多种发送模式**：
  - **PostMessage**：异步消息发送，适用于大多数应用
  - **SendMessage**：同步消息发送，确保按键顺序
  - **SendInput**：系统级输入模拟，兼容性最佳
- **自定义按键组合**：支持10个可自定义的按键配置
- **自动循环功能**：
  - 空格键自动发送（可调节间隔）
  - 鼠标左键自动点击（可调节间隔）
- **快捷键控制**：F1开始/停止，方便操作
- **智能设置保存**：自动保存用户配置，下次启动自动恢复

## 📋 环境要求

- **操作系统**：Windows 7/8/10/11
- **Python 版本**：3.11+
- **权限要求**：管理员权限（程序会自动请求）
- **硬件要求**：无特殊要求

## 🛠️ 安装与运行

### 方式一：使用 uv（推荐）

uv 是一个快速的 Python 包管理器，安装速度比 pip 更快。

1. **安装 uv**：
   ```bash
   pip install uv
   ```

2. **克隆项目**：
   ```bash
   git clone <repository-url>
   cd KeyPressRemark
   ```

3. **创建虚拟环境并安装依赖**：
   ```bash
   uv venv --python 3.11
   # Windows
   .venv\Scripts\activate
   # 或者直接使用 uv pip 安装
   uv pip install PyQt5==5.15.11 pyqt5-qt5==5.15.2 pywin32==311
   ```

4. **运行程序**：
   ```bash
   python src/main.py
   ```

### 方式二：传统 pip 方式

1. **克隆项目**：
   ```bash
   git clone <repository-url>
   cd KeyPressRemark
   ```

2. **创建虚拟环境**：
   ```bash
   python -m venv .venv
   .venv\Scripts\activate
   ```

3. **安装依赖**：
   ```bash
   pip install -r requirements.txt
   ```

4. **运行程序**：
   ```bash
   python src/main.py
   ```

### 方式三：使用打包版本

从 [Releases](releases) 下载预编译的 exe 文件，双击运行即可。

## 📖 使用指南

### 基本操作

1. **选择目标窗口**：
   - 点击"选择窗口"按钮
   - 鼠标变为十字形后，点击要控制的窗口
   - 成功选择后会显示窗口标题和进程信息

2. **配置按键**：
   - 在"自定义按键"区域，为每个按钮选择对应的按键
   - 支持字母、数字、功能键等

3. **选择发送模式**：
   - **PostMessage**：适用于大多数游戏和应用
   - **SendMessage**：适用于需要同步响应的应用
   - **SendInput**：适用于对按键检测严格的应用

4. **开始使用**：
   - 配置完成后，直接点击按键按钮发送
   - 或按 F1 开始自动循环功能

### 高级功能

#### 自动循环
- **空格键循环**：勾选后自动按设定间隔发送空格键
- **鼠标点击循环**：勾选后自动按设定间隔点击鼠标左键
- **间隔设置**：支持毫秒级精度，最小间隔10ms

#### 快捷键控制
- **F1**：开始/停止自动循环功能
- **ESC**：紧急停止所有自动功能

## 🏗️ 项目结构

```
KeyPressRemark/
├── src/                        # 源代码目录
│   ├── main.py                 # 程序入口点
│   ├── core/                   # 核心功能模块
│   │   ├── admin_check.py      # 管理员权限检查和申请
│   │   ├── constants.py        # 常量定义（按键码、消息常量等）
│   │   ├── key_sender.py       # 按键发送核心逻辑
│   │   └── window_selector.py  # 窗口选择功能实现
│   ├── gui/                    # 图形用户界面模块
│   │   ├── main_window.py      # 主窗口界面和逻辑
│   │   ├── about_dialog.py     # 关于对话框
│   │   └── components/         # 可复用UI组件
│   └── utils/                  # 工具和辅助模块
│       ├── settings.py         # 设置管理（保存/加载配置）
│       └── structures.py       # Windows API结构体定义
├── resources/                  # 资源文件目录
│   ├── icons/                  # 应用图标
│   ├── images/                 # 图片资源
│   └── qrc/                    # Qt资源文件
├── tests/                      # 单元测试文件
├── docs/                       # 项目文档
├── dist/                       # 打包输出目录
├── pyproject.toml             # 项目配置文件
├── requirements.txt           # 依赖列表
└── README.md                  # 项目说明文档
```

## 🔧 开发说明

### 核心模块详解

#### core/key_sender.py
负责实际的按键和鼠标事件发送，实现了三种不同的发送模式：

- **PostMessage模式**：异步发送，性能最佳
- **SendMessage模式**：同步发送，响应可靠
- **SendInput模式**：系统级模拟，兼容性最好

#### core/window_selector.py
实现窗口选择功能，通过鼠标点击获取目标窗口句柄。

#### gui/main_window.py
主界面实现，包含所有UI组件和事件处理逻辑。

#### utils/settings.py
配置管理模块，自动保存和恢复用户设置。

### 依赖说明

本项目主要依赖以下库：

- **PyQt5 (5.15.11)**：GUI框架
  - 用于创建图形用户界面
  - 提供丰富的UI组件和事件处理
  
- **pyqt5-qt5 (5.15.2)**：Qt5运行时库
  - 注意：Windows平台需要使用5.15.2版本
  - 新版本5.15.17不支持Windows平台
  
- **pywin32 (311)**：Windows API封装
  - 提供Python访问Windows API的能力
  - 用于窗口操作、消息发送等系统级功能

### 依赖版本说明

⚠️ **重要提示**：本项目在Windows平台上有特定的依赖版本要求：

- `pyqt5-qt5` 必须使用 **5.15.2** 版本
- 不能使用最新的 5.15.17 版本，因为该版本不提供Windows平台的wheel文件
- 如果遇到依赖安装问题，请使用 `uv pip install` 而不是 `uv add`

## 📦 打包部署

### 使用 PyInstaller 打包

1. **安装打包工具**：
   ```bash
   uv add --dev pyinstaller
   ```

2. **打包为单个exe文件**：
   ```bash
   pyinstaller --noconsole --onefile --icon=resources/icons/aaa.ico src/main.py --name=KeyPressRemark
   ```

3. **打包为目录形式**（推荐，启动更快）：
   ```bash
   pyinstaller --noconsole --icon=resources/icons/aaa.ico src/main.py --name=KeyPressRemark
   ```

### 打包选项说明

- `--noconsole`：不显示控制台窗口
- `--onefile`：打包为单个exe文件
- `--icon`：设置应用图标
- `--name`：设置输出文件名

## ⚠️ 注意事项

1. **管理员权限**：程序需要管理员权限才能向其他应用发送按键
2. **杀毒软件**：部分杀毒软件可能将按键模拟程序误报为恶意软件
3. **兼容性**：不同应用对按键模拟的支持程度不同，建议测试不同的发送模式
4. **性能**：高频率按键发送可能影响系统性能，建议合理设置间隔时间

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

1. Fork本项目
2. 创建feature分支：`git checkout -b feature/new-feature`
3. 提交更改：`git commit -am 'Add new feature'`
4. 推送分支：`git push origin feature/new-feature`
5. 提交Pull Request

## 📄 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

## 👨‍💻 作者

**xiao liu**

## 📝 更新日志

### v0.1.0 (当前版本)
- ✨ 基础功能实现
- ✨ 支持三种按键发送模式
- ✨ 窗口选择功能
- ✨ 自定义按键配置
- ✨ 自动循环功能
- ✨ 设置保存和恢复

## 🔮 计划功能

- [ ] 按键序列录制和回放
- [ ] 更多快捷键支持
- [ ] 多窗口同时控制
- [ ] 定时任务功能
- [ ] 界面主题切换

---

如有问题或建议，欢迎提交 [Issue](issues) 或联系作者。