Skip to content

[0152] PDF 阅读器小手拖动使用 QScroller 实现#3435

Merged
da-liii merged 9 commits into
mainfrom
da/0152/pdf_hand
May 20, 2026
Merged

[0152] PDF 阅读器小手拖动使用 QScroller 实现#3435
da-liii merged 9 commits into
mainfrom
da/0152/pdf_hand

Conversation

@da-liii

@da-liii da-liii commented May 20, 2026

Copy link
Copy Markdown
Contributor

摘要

将 PDF 阅读器小手(Browse Tool)拖动滚动的手动实现替换为 Qt QScroller,使行为与 Okular 完全一致。

改动内容

  • 使用 QScroller::handleInput() 处理 InputPress/InputMove/InputRelease,替代直接操作滚动条
  • 配置 Okular 同款滚动参数:
    • DecelerationFactor = 0.3
    • MaximumVelocity = 1.0
    • DragStartDistance = 0.0(零延迟响应)
    • HorizontalOvershootPolicy / VerticalOvershootPolicy = OvershootAlwaysOff
  • 移除手动惯性滚动定时器及相关状态变量(inertialTimer_inertialVelocityY_ 等),惯性滚动由 QScroller 内置处理
  • 保留光标状态机(OpenHandCursorClosedHandCursor)和点击保护逻辑

测试计划

  • 加载 PDF 后悬停页面,光标显示为张开小手
  • 按下左键立即变为握紧小手,零延迟开始拖动
  • 拖动时页面跟随鼠标移动(grab-and-pull)
  • 快速拖动后释放,有惯性滚动效果
  • 滚动到边界时无 overshoot 回弹
  • 短距离按下释放(< 4px)不触发滚动,视为点击
  • 切换矩形选择模式后光标变为十字,小手逻辑不干扰

🤖 Generated with Claude Code

da-liii and others added 9 commits May 20, 2026 18:37
将 Okular 的默认浏览工具(小手拖动)的产品细节、光标状态机、
QScroller 驱动、屏幕边缘光标环绕、缩略图交互等调研结果写入
 devel/0152.md。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- 默认显示 OpenHandCursor,左键按下拖动时变为 ClosedHandCursor
- 使用曼哈顿距离阈值区分拖动与点击
- 拖动时直接操作垂直滚动条,实现平滑滚动
- 在关键位置添加 LIII_DEBUG 日志(press/drag/release)
- 更新现有矩形选择模式的光标回退逻辑(恢复为 OpenHandCursor)
- 添加 6 个单元测试覆盖小手功能的各个场景
- 更新 devel/0152.md How 部分,补充实现方案

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
将拖动公式从 +dy 改为 -dy,使得鼠标向下拖动时页面向下移动
(滚动条值减小),符合"抓住纸往下拉"的直觉。

- 更新 test_dragScrollsDown:先在中间位置开始,验证向下拖动后
  滚动条值减小
- 更新 devel/0152.md How 部分的方向描述

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- 在 mouseMove 中实时采集拖动速度(px/ms)
- 释放时若速度超过 0.5 px/ms,启动惯性滚动定时器(60fps)
- 每帧按速度更新滚动条位置,并乘以 0.85 减速因子
- 速度低于 0.3 px/ms 时自动停止
- 添加 2 个单元测试覆盖惯性滚动启动和停止
- 更新 devel/0152.md 补充惯性滚动实现细节

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- mousePress 时立即显示 ClosedHandCursor,无需等待拖动阈值
- mouseMove 时无论移动多少距离都直接更新滚动位置
- browseDragActive_ 仅用于区分单击 vs 拖动,不再阻止滚动更新
- 同步更新 devel/0152.md 和单元测试

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
替换手动滚动条操作和自定义惯性滚动,改用 Qt QScroller
驱动,配置与 Okular 相同的滚动参数:
- DecelerationFactor = 0.3
- MaximumVelocity = 1.0
- DragStartDistance = 0.0(零延迟响应)
- OvershootAlwaysOff(边界无回弹)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- 使用事件原生时间戳 mouseEvent->timestamp() 替代 wall clock
- 添加 scrollBar singleStep(20) 与 Okular 保持一致
- 添加滚动条与 QScroller 的 actionTriggered 同步

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@da-liii da-liii merged commit e388531 into main May 20, 2026
3 of 4 checks passed
@da-liii da-liii deleted the da/0152/pdf_hand branch May 20, 2026 11:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant