fix: prevent dock from hiding when hovering over preview windows

[xionglinlin]

The issue was that when users hovered over application preview windows in the dock, the dock would automatically hide, causing the preview windows to appear floating without their parent dock. This happened because the preview windows were being incorrectly identified as tooltip windows and excluded from dock's event filtering logic.

The fix adds a custom property "isDockPreview" to the preview window container to distinguish dock preview windows from regular tooltip windows. The DockHelper event filter now checks for this property before skipping tooltip windows, ensuring that dock preview windows continue to be processed by the dock's event system.

Technical details:

1. Added property setting in X11WindowPreviewContainer::initUI() to mark the window as a dock preview
2. Modified DockHelper::eventFilter() to only skip tooltip windows that don't have the "isDockPreview" property set to true

Log: Fixed dock auto-hiding issue when hovering over application preview windows

Influence:

1. Test hovering over application preview windows in dock - dock should remain visible
2. Verify that regular tooltip windows still function normally and don't interfere with dock behavior
3. Test dock preview window display and interaction in different positions (top/bottom/left/right)
4. Verify that the fix works with multiple preview windows open simultaneously
5. Test with different application types and window states

fix: 修复鼠标悬停在应用预览窗口时任务栏自动隐藏的问题

问题在于当用户悬停在任务栏中的应用预览窗口时，任务栏会自动隐藏，导致预
览窗口悬空显示而没有父级任务栏。这是因为预览窗口被错误地识别为工具提示窗
口，从而被排除在任务栏的事件过滤逻辑之外。

修复方案为预览窗口容器添加自定义属性"isDockPreview"，以区分任务栏预览窗
口和常规工具提示窗口。DockHelper事件过滤器现在在跳过工具提示窗口之前会检
查此属性，确保任务栏预览窗口继续由任务栏的事件系统处理。

技术细节：

1. 在X11WindowPreviewContainer::initUI()中添加属性设置，将窗口标记为任务 栏预览窗口
2. 修改DockHelper::eventFilter()，仅跳过未设置"isDockPreview"属性为true 的工具提示窗口

Log: 修复鼠标悬停在应用预览窗口时任务栏自动隐藏的问题

Influence:

1. 测试悬停在任务栏中的应用预览窗口 - 任务栏应保持可见
2. 验证常规工具提示窗口仍能正常工作且不影响任务栏行为
3. 测试不同位置（顶部/底部/左侧/右侧）的任务栏预览窗口显示和交互
4. 验证修复在同时打开多个预览窗口时正常工作
5. 测试不同类型的应用程序和窗口状态

PMS: BUG-352855
Change-Id: I9e7dd425ce3dc887783bebfdf92acf61bca8c4ca

Summary by Sourcery

Ensure dock preview windows are correctly handled by the dock event system so the dock stays visible when hovering previews.

Bug Fixes:

• Prevent the dock from auto-hiding when hovering over application preview windows by distinguishing them from regular tooltip windows.

Enhancements:

• Tag dock preview window containers with a dedicated property to allow event filtering logic to treat them differently from tooltip windows.

Chores:

• Update dock helper source file copyright years to cover 2024–2026.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Marks dock preview windows with a custom property and updates the dock event filter so preview windows are not treated as regular tooltips, preventing the dock from auto-hiding when hovering over previews.

Sequence diagram for dock event filtering of preview vs tooltip windows

sequenceDiagram
    actor User
    participant DockPreviewWindow
    participant DockHelper
    participant Dock

    User->>DockPreviewWindow: Hover over preview
    DockPreviewWindow-->>DockHelper: QEvent(Hover/Enter)
    DockHelper->>DockHelper: eventFilter(watched, event)
    DockHelper->>DockPreviewWindow: window = qobject_cast<QWindow*>(watched)
    DockHelper->>DockHelper: check window->flags().testFlags(Qt::ToolTip)

    alt Tooltip window without isDockPreview
        DockHelper->>DockPreviewWindow: window->property(isDockPreview) == false
        DockHelper-->>DockPreviewWindow: return false (skip filtering)
        Dock-->>User: Dock may auto hide
    else Dock preview window
        DockHelper->>DockPreviewWindow: window->property(isDockPreview) == true
        DockHelper-->>DockPreviewWindow: continue processing event
        DockHelper->>Dock: Update visibility state (remain visible)
        Dock-->>User: Dock stays visible while hovering preview
    end

Loading

Class diagram for DockHelper and X11WindowPreviewContainer changes

classDiagram
    class DockHelper {
        +bool eventFilter(QObject *watched, QEvent *event)
    }

    class X11WindowPreviewContainer {
        +void initUI()
    }

    class QWindow {
        +Qt::WindowFlags flags()
        +QVariant property(const char *name)
        +void setProperty(const char *name, const QVariant &value)
    }

    class QEvent
    class QObject

    DockHelper ..|> QObject
    X11WindowPreviewContainer ..|> QObject

    X11WindowPreviewContainer --> QWindow : uses windowHandle()
    DockHelper --> QWindow : filters events for
    DockHelper --> QEvent

    note for X11WindowPreviewContainer "initUI sets windowHandle property isDockPreview = true on the preview window"
    note for DockHelper "eventFilter skips Qt::ToolTip windows only when isDockPreview is not true"

Loading

File-Level Changes

Change	Details	Files
Ensure dock preview windows are not treated as tooltip windows in the dock event filter so the dock stays visible when hovering previews.	Extend the tooltip window early-return condition in the dock event filter to only skip tooltip windows that do not have a specific dock-preview marker property set to true. Keep processing events for tooltip-typed windows that are explicitly marked as dock preview windows, allowing normal dock visibility behavior when hovering previews.	panels/dock/dockhelper.cpp
Mark X11 dock preview containers with a custom window property to distinguish them from regular tooltips.	In the preview container UI initialization, obtain the native window handle and set a boolean "isDockPreview" property on it. Retain existing preview container sizing and shadow configuration while adding the new property assignment step.	panels/dock/taskmanager/x11preview.cpp

---

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

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• Consider defining the "isDockPreview" property name as a shared constexpr/QStringLiteral (e.g., in a common header) instead of repeating the raw string in multiple places to avoid typos and ease future changes.
• In DockHelper::eventFilter, you could early-return when the window has the isDockPreview property set (before further transient/parent handling) to make the special-case behavior for previews more explicit and reduce unnecessary processing.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider defining the "isDockPreview" property name as a shared constexpr/QStringLiteral (e.g., in a common header) instead of repeating the raw string in multiple places to avoid typos and ease future changes.
- In DockHelper::eventFilter, you could early-return when the window has the isDockPreview property set (before further transient/parent handling) to make the special-case behavior for previews more explicit and reduce unnecessary processing.

---

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

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[deepin-ci-robot]

deepin pr auto review

这段代码主要涉及对Dock（任务栏）预览窗口的事件过滤处理和属性设置。以下是对这段diff的详细审查意见：

1. 代码逻辑审查

关于 DockHelper::eventFilter 的修改：

• 逻辑变更分析：

  • 原逻辑：当遇到带有 Qt::ToolTip 标志的窗口时，直接返回 false（不处理该事件，继续传递）。这意味着所有 Tooltip 类型的窗口都被忽略。
  • 新逻辑：当遇到带有 Qt::ToolTip 标志的窗口时，检查其是否设置了属性 "isDockPreview" 为 true。如果不是 Dock 预览窗口，才返回 false。
  • 意图推测：这表明 Dock 的预览窗口（X11WindowPreviewContainer）可能使用了 Qt::ToolTip 窗口类型来实现“无边框”、“置顶”或“不抢占焦点”等特性，但作者希望 DockHelper 能够捕获并处理这些预览窗口的事件，而忽略普通的 Tooltip。

• 潜在问题：

  • 代码可读性：修改后的逻辑稍微有些“绕”。原意是“如果是 Tooltip 则忽略”，现在是“如果是 Tooltip 但不是 Dock 预览则忽略”。建议可以重构判断条件使其更直观。
  • 逻辑完整性：如果 window 的 property("isDockPreview") 不存在或转换失败（例如返回的不是 bool），toBool() 默认返回 false。此时代码逻辑为 if (!false) -> return false，即忽略该窗口。这是安全的默认行为，符合防御性编程原则。

关于 X11WindowPreviewContainer::initUI 的修改：

• 逻辑变更分析：

  • 在初始化 UI 时，显式给窗口句柄设置了属性 "isDockPreview" 为 true。
  • 这与 DockHelper 中的修改相呼应，确保预览窗口能被识别并特殊处理。

• 潜在问题：

  • 时序问题：代码调用了 winId()，这会强制创建原生窗口句柄。紧接着调用 this->windowHandle()。虽然 winId() 确保了 windowHandle() 不会为空，但这种依赖隐式副作用的写法最好加上注释说明。
  • DPlatformHandle 初始化：DPlatformHandle handler(this->windowHandle()); 这一行紧跟在属性设置之后。DPlatformHandle 是 DTK 框架中的类，用于处理平台特定的窗口属性（如阴影）。这里看起来没有问题，但需确保 handler 对象的生命周期不会影响属性设置。

2. 代码质量与规范

• SPDX 版权年份更新：
  • SPDX-FileCopyrightText: 2024 - 2026：将版权年份更新到 2026 年是合规的做法，表示该文件在 2024 至 2026 年间持续维护。
• 命名规范：
  • isDockPreview：属性命名采用了驼峰命名法，且以 is 开头表示布尔值，符合 Qt 和 C++ 的常见命名习惯。
• 空指针检查：
  • if (auto handle = this->windowHandle())：使用了 C++17 的 if 初始化语句，并且进行了空指针检查，这是良好的编程习惯。

3. 代码性能

• 性能影响极小：
  • eventFilter 是高频调用的函数。增加了一次 property 查询和 toBool 转换。虽然 QVariant 的操作有一定的开销，但相比于事件分发和 UI 渲染，这个开销几乎可以忽略不计。
  • initUI 只在初始化时执行一次，对性能无影响。

4. 代码安全

• 类型安全：
  • window->property("isDockPreview").toBool()：如果属性未设置，toBool() 返回 false，这不会导致崩溃，逻辑上也是安全的（未标记的 Tooltip 会被忽略）。
• 空指针安全：
  • 在 X11WindowPreviewContainer::initUI 中，this->windowHandle() 前做了判空处理，避免了潜在的空指针解引用风险。

5. 改进建议

为了提高代码的可读性和健壮性，建议进行以下微调：

建议一：优化 DockHelper::eventFilter 的逻辑表达

原逻辑修改后略显晦涩，建议提取布尔变量或调整判断结构，使代码意图一目了然。

// panels/dock/dockhelper.cpp

bool DockHelper::eventFilter(QObject *watched, QEvent *event)
{
    // ... (前文代码保持不变)

    // skip tooltip windows, but handle dock preview windows specifically
    if (window->flags().testFlag(Qt::ToolTip)) {
        // 检查是否为 Dock 预览窗口
        bool isDockPreview = window->property("isDockPreview").toBool();
        if (!isDockPreview) {
            return false; // 如果不是 Dock 预览，则忽略（跳过）
        }
        // 如果是 Dock 预览，继续执行后续逻辑，不返回
    }

    // ... (后续代码保持不变)
}

注：testFlags 在 Qt 6 中已被弃用，建议使用单数形式的 testFlag，原代码中似乎混用了，建议统一检查 Qt 版本并使用正确的 API。diff 中显示原代码用的是 testFlags，此处建议顺便修正。

建议二：增强 X11WindowPreviewContainer::initUI 的注释

解释为什么需要调用 winId()，以及属性设置的目的。

// panels/dock/taskmanager/x11preview.cpp

void X11WindowPreviewContainer::initUI()
{
    // ... (前文代码保持不变)

    setSizePolicy(QSizePolicy::MinimumExpanding, QSizePolicy::MinimumExpanding);
    
    // 显式创建原生窗口 ID，确保 windowHandle() 可用
    winId(); 
    
    // 设置属性以便 DockHelper 能够识别并处理该预览窗口的事件
    // 即使该窗口使用了 Qt::ToolTip 标志
    if (auto handle = this->windowHandle()) {
        handle->setProperty("isDockPreview", true);
    }
    
    DPlatformHandle handler(this->windowHandle());
    // ... (后续代码保持不变)
}

建议三：使用常量定义字符串

避免硬编码字符串，防止拼写错误。

// 在合适的头文件中定义
static const char* const kIsDockPreviewProp = "isDockPreview";

// 使用处
handle->setProperty(kIsDockPreviewProp, true);
// ...
bool isDockPreview = window->property(kIsDockPreviewProp).toBool();

总结

这段 diff 主要是为了解决 Dock 预览窗口（使用 Tooltip 类型）被事件过滤器错误忽略的问题。通过引入自定义属性 "isDockPreview" 来区分普通 Tooltip 和 Dock 预览窗口。

总体评价：修改逻辑正确，能够解决特定场景下的事件处理问题，且具备基本的安全性。但在代码可读性（逻辑清晰度）和注释说明上还有提升空间。

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: wjyrich, xionglinlin

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

Details

Needs approval from an approver in each of these files:

• debian/deepin/OWNERS

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

[xionglinlin]

/forcemerge

[deepin-bot]

This pr force merged! (status: behind)