feat: add privileged overlay surface support by gugullll · Pull Request #1272 · linuxdeepin/treeland

gugullll · 2026-08-13T03:28:31Z

Summary by Sourcery

Add privileged overlay surface support with dedicated stacking, lifecycle handling, and lock-screen integration.

New Features:

Support privileged XDG overlay surfaces identified by a dedicated toplevel tag, placing them above lock-screen and other overlays while exempting them from normal workspace and window-management behavior.

Bug Fixes:

Preserve privileged overlay behavior when surface tags change by revoking the special role and restoring normal workspace handling when the tag is removed.
Allow IM candidate panel detection to consistently handle both XDG and XWayland surfaces through a unified interface.

Enhancements:

Configure the global Qt Quick overlay above regular surfaces and add dedicated privileged overlay stacking and surface-role handling.
Replace the lock-screen power popup with an in-place overlay that closes when clicking outside the power list.
Extend the toplevel-tag test application with supported-tag selection and fullscreen/restore controls.

Build:

Add the Qt Quick Templates private dependency required by the overlay support.

sourcery-ai

Sorry @gugullll, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

sourcery-ai · 2026-08-13T03:28:58Z

Reviewer's Guide

Adds support for a new 'privileged overlay' toplevel tag and surface role, including its own container, focus/activation rules, and geometry handling, refactors IM candidate panel detection to be wrapper-centric, and adjusts the lockscreen power popup to behave like a privileged overlay demo while expanding the test_toplevel_tag example to cover both tags.

Sequence diagram for privileged overlay promotion on xdg_toplevel tag change

sequenceDiagram
    participant XdgSurface as WXdgToplevelSurface
    participant ShellHandler
    participant IMCandidatePanelManager
    participant Wrapper as SurfaceWrapper
    participant PrivContainer as SurfaceContainer

    XdgSurface->>ShellHandler: tagChanged
    ShellHandler->>IMCandidatePanelManager: checkAndApplyIMCandidatePanel(wrapperPtr)
    ShellHandler->>ShellHandler: checkAndApplyPrivilegedOverlay(wrapperPtr)
    ShellHandler->>Wrapper: applyPrivilegedOverlay(wrapper)
    Wrapper->>Wrapper: flushPendingGeometryAnimation()
    Wrapper->>PrivContainer: addSurface(wrapper)

File-Level Changes

Change	Details	Files
Introduce a privileged overlay surface role and container, and wire tag-based promotion of xdg-toplevels into ShellHandler and workspace/seat focus logic.	Define PRIVILEGED_OVERLAY_TAG and add m_privilegedOverlayContainer with dedicated Z-order and accessor Update updateWrapperContainer to keep privileged overlays in their container regardless of parent changes Connect WXdgToplevelSurface::tagChanged to a unified handler that checks both IM candidate panels and privileged overlays Implement checkAndApplyPrivilegedOverlay/applyPrivilegedOverlay to set the PrivilegedOverlay role, flush pending geometry animations, move the wrapper to the privileged overlay container, and adjust positioning/preview flags Allow privileged overlays to remain activated and exempt them from workspace active-surface stacking and inactivation removal	`src/core/shellhandler.cpp` `src/core/shellhandler.h` `src/core/rootsurfacecontainer.h` `src/workspace/workspace.cpp` `src/seat/helper.cpp`
Refactor IM candidate panel detection to work off SurfaceWrapper::shellSurface, supporting both xdg-toplevel tags and XWayland properties through a single entry point.	Replace separate WXdgToplevelSurface/WXWaylandSurface overloads of checkAndApplyIMCandidatePanel with a single wrapper-based version Use qobject_cast to branch on WXdgToplevelSurface vs WXWaylandSurface and check tag/property accordingly Update call sites in ShellHandler and IMCandidatePanelManager Xwayland handlers to use the new signature	`src/core/imcandidatepanelmanager.cpp` `src/core/imcandidatepanelmanager.h` `src/core/shellhandler.cpp`
Add flushing of pending geometry animations so surfaces can be safely reparented to the privileged overlay container without leaving incomplete animation state.	Introduce SurfaceWrapper::flushPendingGeometryAnimation that aborts any running geometry animation and immediately applies the pending state/geometry if valid	`src/surface/surfacewrapper.cpp` `src/surface/surfacewrapper.h`
Extend logging with a dedicated category for privileged surfaces to trace promotions and behavior.	Declare and define lcTlPrivilegedSurface QLoggingCategory for privileged overlays	`src/common/treelandlogging.cpp` `src/common/treelandlogging.h`
Adjust lockscreen power controls to use a custom full-screen overlay Item instead of a Popup, and ensure focus returns to the user input field when the power overlay closes.	Replace the Popup-based powerList with an Item containing a full-screen MouseArea and a positioned PowerList child Add a powerListClosed() signal on ControlAction and emit it when clicking outside the PowerList to close Hook LockView to powerListClosed to force focus back to userInput	`src/plugins/lockscreen/qml/ControlAction.qml` `src/plugins/lockscreen/qml/LockView.qml`
Update the test_toplevel_tag example to demonstrate both IM candidate panel and privileged overlay tags via a combo box.	Add a QComboBox listing supported tags and bind it to the existing tagEdit Wire currentIndexChanged to set the tagEdit text from the combo selection	`examples/test_toplevel_tag/main.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.

Copilot

Pull request overview

EN: This PR adds a “PrivilegedOverlay” surface role for xdg-toplevel surfaces tagged with org.deepin.treeland.privileged-overlay, placing them into a dedicated container rendered above the lock screen and excluding them from normal workspace activation/inactivation flows. It also refactors IM candidate panel detection to be wrapper-based for both XDG and XWayland, and updates the lockscreen power UI interaction.

**中文：**该 PR 为带有 org.deepin.treeland.privileged-overlay 的 xdg-toplevel 引入 “PrivilegedOverlay” 特权叠加层角色，将其放入独立容器并渲染在锁屏之上，同时从常规工作区激活/失活逻辑中排除；并将输入法候选窗检测改为基于 SurfaceWrapper 的统一逻辑（兼容 XDG 与 XWayland），以及调整锁屏电源菜单的交互行为。

Changes / 变更点：

EN: Introduce SurfaceRole::PrivilegedOverlay and a new privileged overlay container at a higher Z-order than the lock screen.
中文：新增 SurfaceRole::PrivilegedOverlay 及独立容器，并将其 Z 序设置为高于锁屏。
EN: Unify IM candidate panel detection into IMCandidatePanelManager::checkAndApplyIMCandidatePanel(SurfaceWrapper*) for XDG/XWayland.
中文：将输入法候选窗检测统一为 checkAndApplyIMCandidatePanel(SurfaceWrapper*)，同时支持 XDG/XWayland。
EN: Update lockscreen power list UI to close on outside click and restore focus, plus expand the test_toplevel_tag example UI.
中文：锁屏电源列表支持点击外部关闭并恢复焦点，同时增强 test_toplevel_tag 示例界面。

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`src/workspace/workspace.cpp`	Skip privileged overlays in workspace active-surface stack.
`src/surface/surfacewrapper.h`	Add `PrivilegedOverlay` role and `flushPendingGeometryAnimation()` API.
`src/surface/surfacewrapper.cpp`	Implement `flushPendingGeometryAnimation()` to apply pending state/geometry immediately.
`src/seat/helper.cpp`	Allow activation assertions for privileged overlays outside current workspace.
`src/plugins/lockscreen/qml/LockView.qml`	Restore focus when the power list closes.
`src/plugins/lockscreen/qml/ControlAction.qml`	Replace power popup with an overlay item + outside-click dismissal and a close signal.
`src/core/shellhandler.h`	Add privileged overlay container accessor + promotion helpers.
`src/core/shellhandler.cpp`	Create privileged overlay container, promote tagged surfaces, exclude from inactivation removal.
`src/core/rootsurfacecontainer.h`	Add `PrivilegedOverlayZOrder` above lock screen.
`src/core/imcandidatepanelmanager.h`	Change IM candidate panel application API to wrapper-only.
`src/core/imcandidatepanelmanager.cpp`	Implement wrapper-based XDG tag / XWayland property detection in one path.
`src/common/treelandlogging.h`	Add logging category for privileged surfaces.
`src/common/treelandlogging.cpp`	Define the new privileged surface logging category.
`examples/test_toplevel_tag/main.cpp`	Add a combo box for supported toplevel tags (incl. privileged overlay).

Suppressed comments (1)

src/core/shellhandler.cpp:540

EN: When promoting a surface to PrivilegedOverlay, the wrapper may still have a non-null parent surface (transient relationship). After moving to a different container, calls like stackToLast() can end up stacking relative to a parent in another parentItem, which is invalid and can break stacking/focus.
中文：将窗口提升为 PrivilegedOverlay 后，如果仍保留 transient 的父子关系（parentSurface 非空），在迁移到不同 container 后再调用 stackToLast() 等会尝试相对不同 parentItem 的父窗口进行堆叠，可能导致堆叠/焦点异常。

Detach from the parent surface before removing/adding to containers (and keep the wrapper independent in the privileged container).

    // Move from the original container to the privileged overlay container
    if (auto *oldContainer = wrapper->container())
        oldContainer->removeSurface(wrapper);
    m_privilegedOverlayContainer->addSurface(wrapper);

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

zccrs · 2026-08-13T05:19:01Z

 // Popup focus management
 Q_LOGGING_CATEGORY(lcTlPopupFocus, "treeland.popup.focus")
+// Privileged surface
+Q_LOGGING_CATEGORY(lcTlPrivilegedSurface, "treeland.privileged.surface", QtInfoMsg)


不用定义那么细碎的日志分类，定义一个 treeland.shell.xdg 好了，xdg shell相关的所有日志都用它。相对应的还可以有 treeland.shell.layer

zccrs · 2026-08-13T05:21:21Z

见上一条回复

zccrs · 2026-08-13T05:23:23Z

+    // If a geometry animation (e.g. fullscreen transition) is in progress, abort it
+    // and apply the pending state immediately. The animation is bound to the old
+    // container's scene graph and cannot complete after the container change below.
+    wrapper->flushPendingGeometryAnimation();


这类窗口应该是不是应该完全禁用动画？

这里实现flushPendingGeometryAnimation主要是为了解决在之前在锁屏情况下，特权窗口直接创建并全屏显示会全屏失败，后面发现这是客户端并非特权窗口本身的bug,该bug已经在https://github.com/linuxdeepin/treeland/pull/1281这笔提交中测试通过了，我这里就把flushPendingGeometryAnimation删除了。
此外：禁用动画也已经添加。

zccrs · 2026-08-13T05:26:45Z

+{
+    auto *xdgSurface = static_cast<WXdgToplevelSurface *>(wrapper->shellSurface());
+    if (xdgSurface->tag() != PRIVILEGED_OVERLAY_TAG)
+        return false;


这个窗口从拥有这个tag到remove这个tag要怎么处理？

这里之前没有考虑到这种情况，正在添加这部分逻辑

deepin-bot · 2026-08-14T07:55:31Z

TAG Bot

New tag: 0.8.18
DISTRIBUTION: unstable
Suggest: synchronizing this PR through rebase #1286

zccrs · 2026-08-14T10:10:30Z

+        QObject::connect(fullscreenBtn,
+                         &QPushButton::clicked,
+                         &window,
+                         [&window] {


这就没必要用lambda了

zccrs · 2026-08-14T10:10:38Z

+                             window.showFullScreen();
+                         });
+
+        QObject::connect(restoreBtn,


zccrs · 2026-08-14T10:11:18Z

+    QPointer<SurfaceWrapper> wrapperPtr(wrapper);
+    QObject::connect(surface, &WXdgToplevelSurface::tagChanged, this, [this, wrapperPtr]() {
+        if (wrapperPtr) {
+            if (checkAndApplyPrivilegedOverlay(wrapperPtr)) return;


不要写成单行

zccrs · 2026-08-14T10:11:24Z

+    QObject::connect(surface, &WXdgToplevelSurface::tagChanged, this, [this, wrapperPtr]() {
+        if (wrapperPtr) {
+            if (checkAndApplyPrivilegedOverlay(wrapperPtr)) return;
+            if (m_imCandidatePanelManager->checkAndApplyIMCandidatePanel(wrapperPtr)) return;


wineee · 2026-08-18T03:44:27Z

 {
-    if (m_type == Type::Layer || m_type == Type::XdgPopup || isInputPopupLike()) [[unlikely]]
+    if (m_type == Type::Layer || m_type == Type::XdgPopup || isInputPopupLike()
+        || surfaceRole() == SurfaceWrapper::SurfaceRole::PrivilegedOverlay) [[unlikely]]


这里还有必要加吗？

zccrs · 2026-08-18T05:15:14Z

        PopupZOrder = 5,
        CaptureLayerZOrder = 6,
        LockScreenZOrder = 7,
+        GlobalOverlayZOrder = 10,


用100, PrivilegedOverlayZOrder改成200，中间空出一些

zccrs · 2026-08-18T05:17:55Z

 #include <wxwaylandsurface.h>
 #include <wxwaylandsurfaceitem.h>

+#include <QtQuickTemplates2/private/qquickoverlay_p.h>


直接写 <private/qquickoverlay_p.h> 就行，放到QTimer后面

Add privileged overlay container and surface role for surfaces that should remain visible above the lock screen. Introduce logging category, z-order, tag-based detection, and geometry animation flush. Also reparent the entire QQuickOverlay from contentItem to rootSurfaceContainer with Z=10 (GlobalOverlayZOrder), so all QQuickPopup items (combo boxes, menus, tooltips, dimmers) render at the correct scene layer above lock screen and below privileged overlay. 新增特权叠加层容器和表面角色，使特定表面在锁屏状态下仍保持可见。添加日志分类、Z轴层级、基于tag的检测。将 QQuickOverlay 整体 reparent 到 rootSurfaceContainer，新增 GlobalOverlayZOrder 层级确保 popup 在正确 Z 序渲染。 Log: 添加特权叠加层表面支持；将 QQuickOverlay reparent 到 rootSurfaceContainer PMS: TASK-393961 Influence: 拥有 org.deepin.treeland.privileged-overlay tag 的 xdg-toplevel surface 将自动提升为特权叠加层，在锁屏时仍可见且不受 workspace 切换影响。

Add a QComboBox with supported treeland tags (im-candidate-panel and privileged-overlay) for quick tag selection. 在 toplevel-tag 测试 demo 中添加标签选择下拉框，支持快速选择 treeland 内置的两个 tag。 Log: 更新 test-toplevel-tag demo，添加下拉框选择标签 Influence: 仅在 examples 中新增 UI 控件，不影响其他功能。

deepin-ci-robot · 2026-08-18T08:13:10Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: gugullll, zccrs

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

sourcery-ai Bot reviewed Aug 13, 2026

View reviewed changes

gugullll changed the title ~~Feat/test toplevel tag combo~~ feat: add privileged overlay surface support Aug 13, 2026

zccrs requested a lite review from Copilot August 13, 2026 05:14

Copilot started reviewing on behalf of zccrs August 13, 2026 05:15 View session

Copilot AI reviewed Aug 13, 2026

View reviewed changes

Comment thread src/core/shellhandler.cpp Outdated

zccrs requested changes Aug 13, 2026

View reviewed changes

Groveer requested changes Aug 13, 2026

View reviewed changes

Comment thread src/core/shellhandler.cpp Outdated

Comment thread src/core/shellhandler.cpp Outdated

Comment thread src/core/shellhandler.h Outdated

gugullll force-pushed the feat/test-toplevel-tag-combo branch 2 times, most recently from a6621b0 to f86350b Compare August 14, 2026 07:37

gugullll force-pushed the feat/test-toplevel-tag-combo branch 3 times, most recently from be18f11 to 09406d0 Compare August 14, 2026 09:39

zccrs requested changes Aug 14, 2026

View reviewed changes

gugullll force-pushed the feat/test-toplevel-tag-combo branch 4 times, most recently from f9e366f to ed71a8e Compare August 18, 2026 03:30

wineee reviewed Aug 18, 2026

View reviewed changes

gugullll force-pushed the feat/test-toplevel-tag-combo branch 3 times, most recently from d5c6314 to e8a8ab7 Compare August 18, 2026 04:59

zccrs requested changes Aug 18, 2026

View reviewed changes

gugullll added 2 commits August 18, 2026 14:02

gugullll force-pushed the feat/test-toplevel-tag-combo branch from e8a8ab7 to 1d23dab Compare August 18, 2026 06:03

zccrs approved these changes Aug 18, 2026

View reviewed changes

zccrs merged commit 9ba10c8 into linuxdeepin:master Aug 18, 2026
9 checks passed

Uh oh!

Conversation

gugullll commented Aug 13, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by Sourcery

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourcery-ai Bot commented Aug 13, 2026

Reviewer's Guide

Sequence diagram for privileged overlay promotion on xdg_toplevel tag change

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

deepin-bot Bot commented Aug 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deepin-ci-robot commented Aug 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

gugullll commented Aug 13, 2026 •

edited by sourcery-ai Bot

Loading