Metadata-Version: 2.4
Name: mysphinx-snip
Version: 0.0.1
Summary: A cross-platform desktop screenshot tool (region capture, annotation, pin-to-screen).
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PySide6>=6.5
Requires-Dist: pynput>=1.7
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# mysphinx-snip

一个用 Python + PySide6 实现的跨平台桌面截图工具。

## 功能（v0.0.1）

- **区域截图**：拖拽框选屏幕区域，支持框选后移动 / 缩放（八个手柄）。
- **标注工具**：矩形、椭圆、箭头、画笔、文字、马赛克、高亮、序号，支持
撤销 / 重做（`Ctrl+Z` / `Ctrl+Y`），可调颜色与线宽。
- **输出**：复制到剪贴板、保存为 PNG/JPEG（自动按时间戳命名）。
- **贴图**：把截图钉在屏幕最上层的悬浮窗，可拖动、滚轮缩放、右键菜单
（复制 / 保存 / 不透明度 / 关闭）。
- **系统托盘 + 全局热键**：默认 `Ctrl+Shift+A`（macOS 为 `Cmd+Shift+A`）。
- **多显示器 / HiDPI**：每块屏幕一个覆盖层，按 device-pixel-ratio 输出物理像素。

> 暂未实现（后续迭代）：长截图、录屏（MP4/GIF）、带壳截图、OCR/AI、截图历史回溯。

## 安装

```bash
pip install -e .          # 或者：pip install -r requirements.txt
```

## 运行

```bash
mysphinx-snip             # 安装后提供的命令
# 或
python -m snip
```

启动后程序常驻系统托盘。点击托盘图标或按全局热键即可开始截图。

### 截图操作

1. 触发后屏幕变暗，拖拽框选要截取的区域。
2. 选区下方出现工具条：选择标注工具进行标注（未选工具时可移动/缩放选区）。
3. 点击 **复制 / 保存 / 贴图**，或按 `Enter` 复制、`Esc` 取消。

## 平台说明

- **macOS**：需要在 *系统设置 → 隐私与安全性* 授予两类权限：
  - **屏幕录制（必需）**：否则截到的图只有壁纸、没有窗口内容。首次运行会自动弹出授权请求。
  - **辅助功能（仅全局热键需要）**：否则会看到
  `This process is not trusted! ...` 且 `Cmd+Shift+A` 无效。
  权限要授给**运行本程序的那个应用**——从终端启动就是 Terminal/iTerm（打包成 .app 后则是该 App）。
  **授权后必须完全退出并重启该终端/App** 才会生效。
    > 提示：即使没开热键，也可以直接点**菜单栏图标 →「截图」** 使用；菜单里的
    > 「权限设置…」可一键打开对应的系统设置面板。
    > 已知限制：覆盖层无法盖住系统菜单栏区域（普通窗口层级限制），不影响其余区域截图。
- **Windows**：进程默认开启 Per-Monitor v2 DPI 感知，HiDPI 下输出清晰。
- **Linux**：X11 下可用；Wayland 对全屏覆盖层与全局热键支持有限（非主要目标平台）。

## 开发

```bash
pip install -e ".[dev]"
QT_QPA_PLATFORM=offscreen pytest      # 标注模型与逻辑层单测，无需真实显示
```

## 项目结构

```
snip/
  app.py          # 入口：系统托盘、全局热键、截图流程编排
  capture.py      # 屏幕抓取（QScreen.grabWindow → QPixmap，多屏 / HiDPI）
  overlay.py      # 全屏选区覆盖层 + 实时标注交互
  toolbar.py      # 选区浮动工具条
  annotations.py  # 标注数据模型 + 渲染 + 撤销/重做（纯逻辑，可单测）
  pin.py          # 贴图悬浮窗
  config.py       # 配置（QSettings）
```

