Repository navigation
feat: add normal role to dde-shell surface role enum - #119
Merged
Merged
Conversation
1. Add normal (0) to the treeland_dde_shell_surface_v2 role enum and keep overlay at 1 so a shell surface can be restored from the overlay layer back to the normal window layer. 2. Document that set_role(normal) returns the surface to regular toplevel stacking while overlay remains the default. 3. Sync the protocol purpose and v1-to-v2 migration notes in the dde/ and public/ READMEs (EN + zh_CN). Log: DDE shell surfaces can now restore to normal window layer. Influence: 1. Run ./check-protocol-xml.sh dde/treeland-dde-shell-unstable-v2.xml and confirm wayland-scanner exits clean. 2. Verify the generated header exposes ROLE_NORMAL=0 and ROLE_OVERLAY=1. 3. In a client, call set_role(overlay) then set_role(normal) and check the surface returns to regular toplevel stacking. feat: 为 dde-shell surface role 枚举新增 normal 角色 1. 在 treeland_dde_shell_surface_v2 的 role 枚举中新增 normal（0）， overlay 保持为 1，使 shell surface 可从 overlay 层还原回普通窗口层。 2. 补充说明 set_role(normal) 会恢复常规 toplevel 叠放，overlay 仍为默认值。 3. 同步 dde/ 与 public/ 下中英文 README 的协议用途及 v1→v2 迁移说明。 Log: DDE shell surface 现可还原至普通窗口层。 Influence: 1. 运行 ./check-protocol-xml.sh dde/treeland-dde-shell-unstable-v2.xml 并确认 wayland-scanner 退出码为 0。 2. 检查生成的头文件中 ROLE_NORMAL=0、ROLE_OVERLAY=1。 3. 客户端依次调用 set_role(overlay) 与 set_role(normal)，确认 surface 恢复到常规 toplevel 叠放。
Reviewer's guide (collapsed on small PRs)Reviewer's GuideThe protocol now supports switching DDE shell surfaces between the default workspace overlay layer and the normal window layer, with XML semantics and English/Chinese migration documentation synchronized to the new Sequence diagram for restoring a DDE shell surface to the normal window layersequenceDiagram
participant Client
participant Surface as treeland_dde_shell_surface_v2
participant Compositor
Client->>Surface: set_role(overlay)
Surface->>Compositor: Render at workspace overlay layer
Client->>Surface: set_role(normal)
Surface->>Compositor: Render at normal window layer
Compositor-->>Surface: Participate in regular toplevel stacking
Flow diagram for DDE shell surface role layersflowchart LR
Default["Default role: overlay = 1"] --> Overlay["Workspace overlay layer\nAbove normal toplevels\nBelow layer-shell surfaces"]
Overlay -->|"set_role(normal)"| Normal["normal = 0\nRegular window layer\nNormal toplevel stacking"]
Normal -->|"set_role(overlay)"| Overlay
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="dde/treeland-dde-shell-unstable-v2.xml" line_range="106-107" />
<code_context>
ordering within a single role is undefined.
</description>
- <entry name="overlay" value="0" summary="workspace overlay layer, above normal toplevels and below layer-shell surfaces" />
+ <entry name="normal" value="0" summary="normal window layer, below the overlay layer and participating in regular toplevel stacking" />
+ <entry name="overlay" value="1" summary="workspace overlay layer, above normal toplevels and below layer-shell surfaces" />
</enum>
</code_context>
<issue_to_address>
**issue (broader_impact):** The v2 wire value for `overlay` changes from 0 to 1 while both interfaces remain version 1, so existing v2 clients compiled against the previous XML and explicitly calling `set_role(overlay)` send 0 and are interpreted as requesting `normal`, silently moving the surface into regular toplevel stacking.
**Triggers:** When an already-deployed v2 client explicitly sets the overlay role using the previous generated header or a literal value of 0.
**Suggested fix:** Preserve the existing v2 `overlay=0` value and assign the new `normal` role to 1, or introduce a versioned protocol/interface that allows clients to distinguish the changed enum mapping.
```suggestion
<entry name="normal" value="1" summary="normal window layer, below the overlay layer and participating in regular toplevel stacking" />
<entry name="overlay" value="0" summary="workspace overlay layer, above normal toplevels and below layer-shell surfaces" />
```
</issue_to_address>
### Comment 2
<location path="dde/treeland-dde-shell-unstable-v2.xml" line_range="74-77" />
<code_context>
- wl_surface. A shell surface renders below the wlr-layer-shell
- layer stack, at the overlay level of the workspace: above
- normal toplevel windows but below layer-shell surfaces.
+ wl_surface. A shell surface renders either at the overlay level
+ of the workspace (above normal toplevel windows but below
+ layer-shell surfaces) or at the normal window layer, as
+ selected by the set_role request. The default role is overlay.
The role carries no requests that map, commit, or configure
</code_context>
<issue_to_address>
**issue:** The protocol-level description at the top of the XML still says every shell surface renders below the layer-shell stack at the workspace overlay level, so the generated protocol documentation contradicts the changed interface description that permits the `normal` window layer and does not document the new behavior in the protocol purpose.
**Triggers:** When consumers or maintainers rely on the protocol-level description rather than the interface-specific description.
**Suggested fix:** Update the top-level protocol description to state that a shell surface can render either at the overlay level or at the normal window layer, with overlay as the default.
</issue_to_address>
Comment on lines
+106
to
+107
| <entry name="normal" value="0" summary="normal window layer, below the overlay layer and participating in regular toplevel stacking" /> | ||
| <entry name="overlay" value="1" summary="workspace overlay layer, above normal toplevels and below layer-shell surfaces" /> |
There was a problem hiding this comment.
issue (broader_impact): The v2 wire value for overlay changes from 0 to 1 while both interfaces remain version 1, so existing v2 clients compiled against the previous XML and explicitly calling set_role(overlay) send 0 and are interpreted as requesting normal, silently moving the surface into regular toplevel stacking.
Triggers: When an already-deployed v2 client explicitly sets the overlay role using the previous generated header or a literal value of 0.
Suggested fix: Preserve the existing v2 overlay=0 value and assign the new normal role to 1, or introduce a versioned protocol/interface that allows clients to distinguish the changed enum mapping.
Suggested change
| <entry name="normal" value="0" summary="normal window layer, below the overlay layer and participating in regular toplevel stacking" /> | |
| <entry name="overlay" value="1" summary="workspace overlay layer, above normal toplevels and below layer-shell surfaces" /> | |
| <entry name="normal" value="1" summary="normal window layer, below the overlay layer and participating in regular toplevel stacking" /> | |
| <entry name="overlay" value="0" summary="workspace overlay layer, above normal toplevels and below layer-shell surfaces" /> |
Comment on lines
+74
to
+77
| wl_surface. A shell surface renders either at the overlay level | ||
| of the workspace (above normal toplevel windows but below | ||
| layer-shell surfaces) or at the normal window layer, as | ||
| selected by the set_role request. The default role is overlay. |
There was a problem hiding this comment.
issue: The protocol-level description at the top of the XML still says every shell surface renders below the layer-shell stack at the workspace overlay level, so the generated protocol documentation contradicts the changed interface description that permits the normal window layer and does not document the new behavior in the protocol purpose.
Triggers: When consumers or maintainers rely on the protocol-level description rather than the interface-specific description.
Suggested fix: Update the top-level protocol description to state that a shell surface can render either at the overlay level or at the normal window layer, with overlay as the default.
Groveer
approved these changes
Sep 30, 2026
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: Groveer, wineee The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Log: DDE shell surfaces can now restore to normal window layer.
Influence:
feat: 为 dde-shell surface role 枚举新增 normal 角色
Log: DDE shell surface 现可还原至普通窗口层。
Influence:
Summary by Sourcery
Allow DDE shell surfaces to switch between the workspace overlay layer and the regular window layer.
New Features:
Enhancements:
Documentation: