Treeland DDE shell v2
Warning! This protocol is EXPERIMENTAL and under active development. It may change at any time, including in backward-incompatible ways, without incrementing the interface major version and without prior notice. No compatibility guarantees of any kind are provided. Clients and compositors must track the upstream definition in treeland-protocols and must not rely on the current interface names, requests, events, or semantics remaining stable across releases.
This protocol lets a privileged DDE client turn a wl_surface into a shell surface that renders below the wlr-layer-shell layer stack, at the overlay level of the workspace, and position it at coordinates relative to an output or auto-place it below the cursor.
The compositor must reject bind attempts from non-privileged clients.
The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.
treeland_dde_shell_manager_v2
A global that creates treeland_dde_shell_surface_v2 objects for privileged DDE clients implementing parts of the shell user interface.
The compositor must reject bind attempts from non-privileged clients.
destroy()
Destroy the treeland_dde_shell_manager_v2 object. Shell surfaces created through this manager are not affected.
get_shell_surface(id: new_id<treeland_dde_shell_surface_v2>, surface: object<wl_surface>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_dde_shell_surface_v2> | the new shell surface object |
| surface | object<wl_surface> | the surface to create a shell surface for |
Create a new treeland_dde_shell_surface_v2 object for the given surface, turning it into a shell surface. Only one shell surface object can be associated with a given wl_surface; the compositor raises already_shell_surface for a second attempt.
Recommended for use with xdg_surface.
error { already_shell_surface }
Argument | Value | Description |
|---|---|---|
| already_shell_surface | 0 | the wl_surface already has a shell surface object |
Errors raised by the treeland_dde_shell_manager_v2 interface.
treeland_dde_shell_surface_v2
A shell surface object assigns the DDE shell surface role to a wl_surface. The set_role request selects normal window stacking, always-on-top stacking, or workspace overlay stacking. Always-on-top surfaces render above normal windows and below workspace overlay surfaces. Workspace overlay surfaces render below layer-shell top and overlay surfaces. The default role is overlay.
The role carries no requests that map, commit, or configure buffer state; the client commits buffers with wl_surface semantics as usual.
On the server side the object is automatically destroyed when the related wl_surface is destroyed. On the client side, treeland_dde_shell_surface_v2.destroy() must be called before destroying the wl_surface object.
Positioning requests are mutually exclusive: set_position_hint suggests fixed coordinates relative to an output, while set_cursor_placement_hint asks the compositor to place the surface relative to the cursor. The most recently sent request determines the placement mode. Both requests are hints for the initial placement of the surface: the compositor decides the final position and may adjust it to keep the surface accessible, for example to keep its titlebar area within the output. Clients must not assume the requested position is honored exactly.
destroy()
The treeland_dde_shell_surface_v2 interface is removed from the wl_surface object that was turned into a shell surface with the treeland_dde_shell_manager_v2.get_shell_surface request.
The shell surface role is lost and the wl_surface is unmapped.
set_role(role: uint<treeland_dde_shell_surface_v2.role>)
Argument | Type | Description |
|---|---|---|
| role | uint<treeland_dde_shell_surface_v2.role> | the rendering layer for this surface |
Assign the role identified by the role enum to this shell surface, selecting the layer it renders in. The default role before this request is overlay.
Assigning the normal role returns the surface to the regular window layer, participating in normal toplevel stacking again.
The always_on_top role enables window always-on-top; selecting normal or overlay clears it. User changes to always-on-top switch between normal and always_on_top. Since version 2, effective role changes are reported through role.
Argument | Type | Description |
|---|---|---|
| output | object<wl_output>allow null | the output whose origin anchors the coordinates, or null for the primary output |
| x | int | x coordinate relative to the output origin |
| y | int | y coordinate relative to the output origin |
Suggest a position for the surface. The coordinates are relative to the origin of the given output; for example 50,50 suggests placing the surface 50 units right of and 50 units below the output's top-left corner, wherever that output currently sits in the global space spanning all outputs.
The output argument may be null, in which case the compositor uses the primary output as the anchor. Otherwise the output must be a valid, current wl_output. The position is resolved at request time; the compositor does not keep the output associated with this surface afterwards, and the client may release the wl_output proxy once the request has been sent. If the output is later destroyed, the already-applied position is not affected.
This request is a hint for the initial placement of the surface: the compositor decides the final position and may adjust it to keep the surface accessible. Clients must not assume the requested position is honored exactly.
Argument | Type | Description |
|---|---|---|
| x_offset | int | horizontal offset of the surface center from the cursor center, positive to the right |
| y_offset | int | distance from the bottom of the cursor to the top of the surface |
Suggest placing the surface relative to the current cursor position: horizontally offset by x_offset from the cursor center and vertically offset by y_offset from the bottom of the cursor.
This request is a hint for the initial placement of the surface: the compositor decides the final position and may adjust it to keep the surface accessible. Clients must not assume the requested position is honored exactly.
Sending this request switches the placement mode to cursor-relative; see the interface description for the interaction with set_position_hint.
set_skip_flags(flags: uint<treeland_dde_shell_surface_v2.skip_flag>)
Argument | Type | Description |
|---|---|---|
| flags | uint<treeland_dde_shell_surface_v2.skip_flag> | bitfield of views that should not list this surface |
Set the shell views that should not list this surface. The flags argument is a bitfield of skip_flag values; setting a flag asks the shell view not to include the surface, clearing it restores default listing. This request replaces any previously set flags.
set_accept_keyboard_focus(accept: uint)
Argument | Type | Description |
|---|---|---|
| accept | uint | 0 to refuse keyboard focus, 1 to accept it |
Set whether this surface can receive keyboard focus. When set to 0, the surface will not receive keyboard focus even when clicked or activated. When set to 1 (the default), the surface receives keyboard focus normally.
role(role: uint<treeland_dde_shell_surface_v2.role>)
Argument | Type | Description |
|---|---|---|
| role | uint<treeland_dde_shell_surface_v2.role> | the effective stacking role |
Sent after object creation to report the initial effective role, and subsequently after each effective role change caused by a client request, user action, or compositor policy. The compositor need not send this event if the effective role has not changed since the last notification.
role { normal, overlay, always_on_top }
Argument | Value | Description |
|---|---|---|
| normal | 0 | normal window layer, below the overlay layer and participating in regular toplevel stacking |
| overlay | 1 | workspace overlay layer, above normal toplevels and below layer-shell surfaces |
| always_on_topsince 2 | 2 | above normal windows and below workspace overlay surfaces |
The layer a shell surface renders in. Layers are ordered by z depth. Multiple surfaces can share a single role, and ordering within a single role is undefined.
skip_flag { switcher, dock_preview, multitask_view }
Argument | Value | Description |
|---|---|---|
| switcher | 0x1 | do not list the window in the task switcher |
| dock_preview | 0x2 | do not show the window in dock window previews |
| multitask_view | 0x4 | do not list the window in the multitask view |
Flags indicating that the surface prefers not to be listed in specific shell views. Used by the set_skip_flags request. Compositors should honor these preferences but may ignore them, for example for windows the user must always be able to reach.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT