Screen Highlighter

按热键组合 + 拖动鼠标，在屏幕上绘制形状（矩形 / 椭圆 / 圆 / 自由线条），松开后按设定时长渐变消失。 适合演示、录屏、教学、临时圈重点等场景。

工具全程运行在系统消息泵层 (WH_MOUSE_LL)，不会把鼠标事件下发给下层应用： 在浏览器里拖动不会进入 drag-select、在文件管理器里拖动不会选中文件。 可在任意应用之上使用。

功能特性

• 四种绘制形状：矩形、椭圆、圆、自由线条（笔画）
• 可定制外观：颜色 / 线宽 / 线型 / 圆角
• 停留 + 渐隐动画：停留 N 毫秒开始渐隐 M 毫秒完全消失（QColor alpha 通道实现）
• 最小化浮窗：每个形状一个图标，纵向排列；折叠后只显示一个图标
• 多显示器：浮窗可吸附到任意一块屏幕的左右边缘
• 拖动支持：浮窗整个区域都能拖动（按钮间隙也能）
• 持久化配置：所有设置写入 ~/.screen_highlighter.json
• 拦截完整：使用 Rust 编译的 hookcore.dll（WH_MOUSE_LL）+ Python 共享内存 ring buffer 通信， Chromium、Electron 等使用 Raw Input 路径的应用也能被正确拦截
• 平滑回退：hook DLL 配合 pynput / keyboard 一起使用，启动稳定性有保障

截图

启动后默认布局（屏幕右侧靠右）：

   ▢  矩形
   ◯  椭圆
   ○  圆
   ✎  自由画
   ⚙  设置
   «  折叠

技术架构

┌─────────────────┐    共享内存 ring    ┌────────────────────┐
│ hookcore.dll    │◀───────────────────▶│ Python 主进程        │
│ (Rust, WH_      │   (LBUTTON{UP,      │                     │
│  MOUSE_LL hook) │    DOWN, MOVE})     │  MouseBridge        │
│                 │                     │  · 250 Hz poll      │
│  return 1 吞掉  │                     │  · 事件分发          │
│  Chromium       │                     │  · Python signal    │
│  drag-select    │                     │    转发             │
└─────────────────┘                     └────────────────────┘
                                                  │
                                                  ▼
                                        ┌────────────────────┐
                                        │ OverlayManager     │
                                        │ · _ActiveShape     │
                                        │ · QColor alpha 渐变│
                                        │ · 30 FPS 重绘       │
                                        └────────────────────┘

• hookcore/（Rust 库）—— WH_MOUSE_LL 系统级 hook，在 block=1 时吞掉 WM_LBUTTONDOWN/UP 并写入共享内存
• win_hook.py —— Python 端 ctypes 加载 hookcore.dll，封装共享内存 ring buffer 与启停 / block / unblock API
• modifier_bridge —— 50 ms 轮询 GetAsyncKeyState，识别当前是否按下了「画矩形所需的修饰键」
• mouse_bridge —— 主线程 QTimer 250 Hz poll_all() 共享内存，严格按 DOWN → MOVE → UP 顺序 emit 信号
• overlay.py —— 多屏全屏透明覆盖层，_ActiveShape 管理每个形状的生命周期（出生 / 停留 / 渐隐 / 死亡），QColor alpha 通道实现真正的渐变
• float_panel.py —— 浮窗 UI（纵向按钮列 + 自定义 eventFilter 拖动）
• settings_dialog.py —— 设置弹窗（11 个字段）
• main.py —— 入口，组装 hook + 覆盖层 + 浮窗 + 快捷键

安装

1. 安装依赖

pip install -r requirements.txt

依赖：

PyQt5>=5.15
pynput>=1.7.6
keyboard>=0.13.5

2. 编译 hookcore.dll

hookcore.dll 已经编译好放在项目根；如果要重新编译：

cd hookcore
cargo build --release
cd ..
./build_hookcore.bat   # 或手动 cp hookcore/target/x86_64-pc-windows-msvc/release/hookcore.dll ./

Rust 1.70+ toolchain 需要先安装：https://rustup.rs/

3. 运行

python main.py

启动后屏幕右侧出现浮窗。

使用方式

按住 Ctrl+Alt（默认配置）后，在任意位置拖动鼠标左键：

• 矩形 / 椭圆 / 圆：绘制到松手
• 自由线条：持续追踪，松开后按设定的停留 + 渐隐时长消失
• 下层应用：浏览器、IDE、文件管理器都不会收到左键事件，不会进入拖选状态

完全松开 Ctrl+Alt 后，hookcore.dll 解除拦截，下层应用立即恢复正常。

快捷键

快捷键	功能
Ctrl+Alt（默认）	进入 ARMED 遮盖期，开始绘制
Ctrl+Alt+H	全局开关工具（启用 / 停用）
Ctrl+Alt+C	清除所有形状

drag_modifier 字段可以改成其它组合： none（按下即画，无修饰键）、ctrl、alt、shift、ctrl+shift、alt+shift 等。

浮窗

• 单击任意形状图标 → 切换当前绘制形状
• 单击「设置」图标 → 打开设置弹窗
• 单击「折叠」图标（«）→ 折叠成单图标 »；再次单击 → 展开
• 拖动（含背景间隔） → 浮窗跟随移动，松手自动吸附到当前所在屏幕的左 / 右边缘

配置（~/.screen_highlighter.json）

{
  "color": "#FF3B30",
  "line_width": 3,
  "line_style": "solid",
  "shape": "rect",
  "corner_radius": 6,
  "fade_after_ms": 1500,
  "fade_out_ms": 400,
  "enabled": true,
  "drag_modifier": "ctrl+shift",
  "toggle_hotkey": "ctrl+alt+h",
  "clear_hotkey": "ctrl+alt+c",
  "float_panel_dock": "right",
  "float_panel_collapsed": false,
  "float_panel_offset": 0,
  "line_styles": ["solid", "dash", "dot"],
  "shapes": ["rect", "ellipse", "circle", "freehand"]
}

• 浮窗界面改任何字段 → 实时写入本文件
• 程序退出再启动 → 自动加载
• 配置被破坏 → 自动回退到默认值

打包为 EXE

一键打包

build.bat

脚本依次执行：

1. 检查 / 安装 pyinstaller、pywin32
2. build_hookcore.bat 编译 Rust hook DLL 并复制到项目根
3. pyinstaller build.spec --noconfirm --clean
4. 嵌入式自检（pynput / keyboard / win_hook / hookcore.dll）

产物

dist/
└── ScreenHighlighter/
    ├── ScreenHighlighter.exe
    └── _internal/
        ├── hookcore.dll       ← Rust hook 模块
        ├── _winhook.pyd       ← pynput 平台模块
        └── ...                ← PyQt5 插件与依赖

one-folder 模式（比 one-file 启动快，且 pynput / keyboard 模块加载更稳定）。

自定义打包

• 想换图标：在 build.spec 的 EXE(...) 块加 icon='app.ico'
• 想变 one-file：去掉 COLLECT(...) 块，把 exclude_binaries 设为 False

运行注意

• Windows 上 keyboard 库需要管理员权限运行 ScreenHighlighter.exe； 否则 Ctrl+Alt+H / Ctrl+Alt+C 全局快捷键失效，但浮窗上的开关按钮仍然可用
• 杀软偶尔误报 PyInstaller 产物；可以给 dist/ScreenHighlighter/ 目录加白名单

项目结构

screen_highlighter/
├── main.py                  # 入口：组装 hook、覆盖层、浮窗、快捷键
├── overlay.py               # 全屏透明覆盖层 + 形状生命周期
├── float_panel.py           # 浮窗 UI（纵向按钮列 + 拖动 + 折叠）
├── settings_dialog.py       # 设置弹窗（11 个字段）
├── config.py                # 配置数据类 + JSON 加载 / 保存
├── win_hook.py              # hookcore.dll 的 ctypes 封装
├── debug_log.py             # 诊断日志（JSON Lines to ~/.screen_highlighter.log）
├── requirements.txt
├── build.bat                # 一键打包脚本
├── build.spec               # PyInstaller 配置
├── build_hookcore.bat       # Rust hook DLL 编译 + 复制
├── hookcore.dll             # ← 由 build_hookcore.bat 生成
└── hookcore/                # Rust hook 源码
    ├── Cargo.toml
    └── src/lib.rs

诊断日志

启动时会自动写日志到 ~/.screen_highlighter.log（JSON Lines 格式）。 可设 SCREEN_HIGHLIGHTER_LOG=0 关闭。

排查问题时：

• hook_start / hook_stopped_on_quit —— hook DLL 是否成功装上
• modifier_state_changed —— ModifierBridge 状态变更
• hook_block_set / hook_unblock_set —— 是否进入 ARMED / 退出
• hook_poll_events —— 鼠标事件流（evt 1=DOWN / 2=MOVE / 3=UP）
• freehand_added_overlay / shape_opacity_sample —— 形状生命周期
• overlay_drop_dead_shape —— 形状被回收

已知限制

• 仅 Windows：依赖 WH_MOUSE_LL、Win32 修饰键 API、PyQt5 Windows 后端
• 鼠标事件之外的输入：未拦截键盘输入、右键菜单、中键等
• 杀软误报：PyInstaller 产物偶尔被报病毒，需用户加白名单

贡献

欢迎 PR、issue、建议。 开始之前请阅读 CONTRIBUTING.md。

许可证

MIT License —— 详见 LICENSE。