Skip to content

feat: add dock spotlight cursor tracking - #1764

Open
wjyrich wants to merge 1 commit into
linuxdeepin:masterfrom
wjyrich:feat-spotlight
Open

wjyrich wants to merge 1 commit into
linuxdeepin:masterfrom
wjyrich:feat-spotlight

Conversation

@wjyrich

@wjyrich wjyrich commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor
  1. Add containsMouse and cursorPosition Q_PROPERTY bindings to DockPanel
  2. Implement eventFilter logic to track Enter, MouseMove, Leave and Hide events on the dock window without per-item handlers
  3. Cache spotlight tracking state via syncSpotlightTracking to avoid settings queries on the hot event path
  4. Create DockSpotlight.qml component rendering a two-layer radial gradient spotlight following the cursor
  5. Add SpotlightGradient.png texture asset shared by both layers
  6. Wire the spotlight into main.qml with a Loader gated on fashion mode and dock visibility
  7. Add mouse event derived includes (QEnterEvent, QMouseEvent) and position clamping to keep the spotlight inside the window bounds

Log: Added a cursor-following spotlight effect on the dock in fashion mode

Influence:

  1. Verify the spotlight appears when moving the cursor over the dock in fashion mode
  2. Verify the spotlight disappears when the dock is hidden or when the cursor leaves the dock area
  3. Test theme switching between light and dark mode to confirm spotlight opacity values change correctly
  4. Verify the spotlight does not appear in non-fashion (efficient) mode
  5. Test with dock resizing and different dock positions/screen edges
  6. Verify the spotlight tracks the cursor smoothly when a control keeps its mouse grab after the pointer leaves the window
  7. Confirm no regression in existing dock click, drag and context menu interactions

feat: 添加任务栏聚光灯光标跟踪

  1. 在 DockPanel 中新增 containsMouse 和 cursorPosition 属性绑定
  2. 在 eventFilter 中处理 Enter、MouseMove、Leave 和 Hide 事件, 无需逐项事件处理器即可跟踪光标
  3. 通过 syncSpotlightTracking 缓存聚光灯跟踪状态,避免在热路径上 查询设置
  4. 新建 DockSpotlight.qml 组件,渲染跟随光标的两层径向渐变聚光灯
  5. 添加 SpotlightGradient.png 贴图供两层图像共享
  6. 在 main.qml 中通过 Loader 接入聚光灯,并根据时尚模式和任务栏 可见性进行条件加载
  7. 添加 QEnterEvent、QMouseEvent 头文件,并对坐标进行边界钳制, 确保聚光灯始终位于窗口范围内

Log: 新增时尚模式下任务栏跟随光标的聚光灯效果

Influence:

  1. 验证在时尚模式下将光标移动到任务栏上时聚光灯正常显示
  2. 验证任务栏隐藏或光标移出任务栏区域时聚光灯消失
  3. 测试浅色与深色主题切换,确认聚光灯透明度随之变化
  4. 验证在非时尚(高效)模式下聚光灯不显示
  5. 测试任务栏尺寸调整及不同位置/屏幕边缘的情况
  6. 验证当控件在指针离开窗口后仍保持鼠标抓取时聚光灯仍能平滑跟踪
  7. 确认现有任务栏点击、拖拽和右键菜单交互无回归问题

PMS: task-396639

Summary by Sourcery

Add a fashion-mode dock spotlight that follows the cursor and automatically respects dock visibility and theme settings.

New Features:

  • Add a cursor-following radial spotlight effect to the dock in fashion mode.

Enhancements:

  • Expose dock cursor position and hover state for spotlight rendering while tracking events without per-control handlers.
  • Enable spotlight behavior to respond to dock visibility, theme, resizing, and cursor-grab scenarios.

Chores:

  • Add the shared spotlight gradient asset and integrate the spotlight component into the dock UI.

1. Add containsMouse and cursorPosition Q_PROPERTY bindings to DockPanel
2. Implement eventFilter logic to track Enter, MouseMove, Leave and Hide
   events on the dock window without per-item handlers
3. Cache spotlight tracking state via syncSpotlightTracking to avoid
   settings queries on the hot event path
4. Create DockSpotlight.qml component rendering a two-layer radial
   gradient spotlight following the cursor
5. Add SpotlightGradient.png texture asset shared by both layers
6. Wire the spotlight into main.qml with a Loader gated on fashion mode
   and dock visibility
7. Add mouse event derived includes (QEnterEvent, QMouseEvent) and
   position clamping to keep the spotlight inside the window bounds

Log: Added a cursor-following spotlight effect on the dock in fashion
mode

Influence:
1. Verify the spotlight appears when moving the cursor over the dock in
   fashion mode
2. Verify the spotlight disappears when the dock is hidden or when the
   cursor leaves the dock area
3. Test theme switching between light and dark mode to confirm spotlight
   opacity values change correctly
4. Verify the spotlight does not appear in non-fashion (efficient) mode
5. Test with dock resizing and different dock positions/screen edges
6. Verify the spotlight tracks the cursor smoothly when a control keeps
   its mouse grab after the pointer leaves the window
7. Confirm no regression in existing dock click, drag and context menu
   interactions

feat: 添加任务栏聚光灯光标跟踪

1. 在 DockPanel 中新增 containsMouse 和 cursorPosition 属性绑定
2. 在 eventFilter 中处理 Enter、MouseMove、Leave 和 Hide 事件,
   无需逐项事件处理器即可跟踪光标
3. 通过 syncSpotlightTracking 缓存聚光灯跟踪状态,避免在热路径上
   查询设置
4. 新建 DockSpotlight.qml 组件,渲染跟随光标的两层径向渐变聚光灯
5. 添加 SpotlightGradient.png 贴图供两层图像共享
6. 在 main.qml 中通过 Loader 接入聚光灯,并根据时尚模式和任务栏
   可见性进行条件加载
7. 添加 QEnterEvent、QMouseEvent 头文件,并对坐标进行边界钳制,
   确保聚光灯始终位于窗口范围内

Log: 新增时尚模式下任务栏跟随光标的聚光灯效果

Influence:
1. 验证在时尚模式下将光标移动到任务栏上时聚光灯正常显示
2. 验证任务栏隐藏或光标移出任务栏区域时聚光灯消失
3. 测试浅色与深色主题切换,确认聚光灯透明度随之变化
4. 验证在非时尚(高效)模式下聚光灯不显示
5. 测试任务栏尺寸调整及不同位置/屏幕边缘的情况
6. 验证当控件在指针离开窗口后仍保持鼠标抓取时聚光灯仍能平滑跟踪
7. 确认现有任务栏点击、拖拽和右键菜单交互无回归问题

PMS: task-396639
@deepin-ci-robot

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: wjyrich

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@sourcery-ai

sourcery-ai Bot commented Oct 15, 2026

Copy link
Copy Markdown

Reviewer's Guide

The PR implements a fashion-mode dock spotlight by caching cursor tracking in DockPanel’s window event filter, exposing the state to QML, rendering a shared-texture two-layer gradient, and conditionally loading it based on dock visibility and theme.

Sequence diagram for dock spotlight cursor tracking

sequenceDiagram
    participant Window as DockWindow
    participant Panel as DockPanel
    participant QML as DockSpotlight

    Note over Panel: syncSpotlightTracking caches fashionMode and hideState
    Window->>Panel: Enter(position)
    Panel->>Panel: setCursorPosition(position)
    Panel->>Panel: setContainsMouse(true)
    Panel-->>QML: cursorPositionChanged, containsMouseChanged
    QML->>QML: Move two gradient layers to cursor

    Window->>Panel: MouseMove(position)
    Panel->>Panel: setCursorPosition(position)
    Panel->>Panel: setContainsMouse(window bounds contains position)
    Panel-->>QML: cursorPositionChanged, containsMouseChanged

    Window->>Panel: Leave or Hide
    Panel->>Panel: setContainsMouse(false)
    Panel-->>QML: containsMouseChanged
    QML->>QML: Fade spotlight opacity
Loading

File-Level Changes

Change Details Files
Expose cached dock cursor state to QML through event-filter-driven properties.
  • Track enter, move, leave, and hide events at the dock window level.
  • Clamp mouse containment during mouse grabs and cache whether tracking is enabled.
  • Add containsMouse and cursorPosition properties with change notifications.
panels/dock/dockpanel.cpp
panels/dock/dockpanel.h
Add a reusable cursor-following spotlight visual with theme-dependent layered gradients.
  • Render outer and core spotlight layers from a shared texture.
  • Animate visibility and clamp the spotlight center to the component bounds.
  • Adjust layer opacity for light and dark themes.
panels/dock/package/DockSpotlight.qml
panels/dock/package/SpotlightGradient.png
Conditionally integrate the spotlight into the dock UI.
  • Load the effect only for fashion mode while the dock is shown.
  • Map the panel cursor position into the dock container coordinate space.
  • Pass dock item sizing and theme state into the spotlight component.
panels/dock/package/main.qml

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 2 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="panels/dock/package/DockSpotlight.qml" line_range="37" />
<code_context>
+            height: spotlight.baseRadius * 2.6
+            x: -width / 2
+            y: -height / 2
+            source: "SpotlightGradient.png"
+            fillMode: Image.Stretch
+            smooth: true
</code_context>
<issue_to_address>
**Spotlight effect is invisible**

When the installed dock package lacks `SpotlightGradient.png`, both `Image` elements in `DockSpotlight.qml` request the missing file, so Qt Quick cannot load the gradients and the spotlight renders without them. Users see no spotlight effect.

Include `SpotlightGradient.png` in the installed dock package or point both images to an available asset.

Also at `panels/dock/package/DockSpotlight.qml:49`.
</issue_to_address>

### Comment 2
<location path="panels/dock/dockpanel.cpp" line_range="591-592" />
<code_context>
+{
+    // Cache the mode so the hot event path never needs to query settings.
+    m_spotlightTracking = fashionMode() && hideState() == Show;
+    if (!m_spotlightTracking)
+        setContainsMouse(false);
+}
+
</code_context>
<issue_to_address>
**Spotlight stays hidden after activation**

When fashion mode becomes active while the pointer is already over the dock and remains stationary, `syncSpotlightTracking()` enables event tracking without sampling the pointer or updating `m_containsMouse`. With no subsequent mouse event, `containsMouse` stays false and the spotlight remains hidden until the pointer moves.

When enabling tracking, sample the current pointer and update `m_containsMouse`.
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread panels/dock/package/DockSpotlight.qml
Comment thread panels/dock/dockpanel.cpp
@deepin-ci-robot

Copy link
Copy Markdown

deepin pr auto review

★ 总体评分:97分 (大于70分通过)

■ 【总体评价】

代码审查通过
总体评分 97 分,大于 70 分通过阈值。本次提交为新增任务栏聚光灯光标跟踪功能,代码结构清晰,性能优化合理,无安全漏洞。

■ 【详细分析】

  • 1.语法逻辑(优秀)✓通过

具体分析内容,指出代码位置、函数名及问题原因
潜在问题:无
建议:代码语法正确,逻辑清晰,eventFilter 中早期返回逻辑合理,鼠标位置边界检查使用 QRectF::contains() 正确处理。QML 中使用 Math.max/Math.min 对坐标进行钳制,确保聚光灯始终位于窗口范围内。setContainsMouse 和 setCursorPosition 使用变更检测,仅在值变化时发射信号,避免冗余更新。

  • 2.代码质量(良好)✓通过

具体分析内容
潜在问题:1.panels/dock/dockpanel.cpp:50-52 syncSpotlightTracking() 仅通过信号连接调用,未在 init() 中显式调用进行初始化。虽然 rootObjectChanged 信号在 DPanel::init() 期间会触发,但显式调用更健壮(OCR 发现)
2.panels/dock/package/DockSpotlight.qml:31-53 两个 Image 元素结构相似,共享相同 source 和类似属性,可考虑合并优化
建议:建议在 init() 末尾(DPanel::init() 之后)显式调用 syncSpotlightTracking() 确保初始状态正确。DockSpotlight.qml 中两个 Image 可考虑使用 Repeater 或公共属性减少重复。

  • 3.代码性能(优秀)✓通过

具体分析内容
潜在问题:无
建议:syncSpotlightTracking() 缓存跟踪状态避免热路径查询设置。setContainsMouse/setCursorPosition 仅在值变化时发射信号。QML 使用单个 Item 变换代替分别计算两个 Image 坐标。两层 Image 共享同一纹理资源。Loader 通过 active 属性仅在需要时创建组件。enabled: false 防止聚光灯拦截事件。性能设计优秀。

  • 4.代码安全(优秀,存在 0 个安全漏洞)✓通过

漏洞对比统计:新增漏洞 0 个,减少漏洞 0 个,持平 0 个
总体风险描述,指出漏洞位置和攻击面
未发现安全漏洞

  • 建议:本次提交无安全漏洞。鼠标位置数据来自 Qt 事件系统,非外部输入。无命令执行、SQL 查询、文件路径操作等风险点。无硬编码密钥或敏感信息。QML 组件使用 enabled: false 禁用交互,防止潜在的输入注入。建议保持当前的防御性编程实践。

■ 【改进建议代码示例】

// 在 DockPanel::init() 末尾添加显式调用
bool DockPanel::init()
{
    // ... existing init code ...
    
    DPanel::init();
    
    // 确保聚光灯跟踪初始状态正确
    syncSpotlightTracking();
    
    // ... rest of init code ...
    return true;
}

@deepin-bot

deepin-bot Bot commented Oct 15, 2026

Copy link
Copy Markdown

TAG Bot

New tag: 2.0.58
DISTRIBUTION: unstable
Suggest: synchronizing this PR through rebase #1765

@deepin-bot

deepin-bot Bot commented Oct 16, 2026

Copy link
Copy Markdown

TAG Bot

New tag: 2.0.59
DISTRIBUTION: unstable
Suggest: synchronizing this PR through rebase #1766

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.

2 participants