Treeland DDE shell v2

DDE shell surface role for treeland

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.

factory for DDE shell surfaces

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 manager

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
idnew_id<treeland_dde_shell_surface_v2>
the new shell surface object
surfaceobject<wl_surface>
the surface to create a shell surface for
create a shell surface from a surface

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.

Argument
Value
Description
already_shell_surface0
the wl_surface already has a shell surface object
factory errors

Errors raised by the treeland_dde_shell_manager_v2 interface.


shell surface role

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()
destroy the shell surface object

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.

Argument
Type
Description
roleuint<treeland_dde_shell_surface_v2.role>
the rendering layer for this surface
assign a rendering layer to 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.

set_position_hint(output: object<wl_output>, x: int, y: int)
Argument
Type
Description
outputobject<wl_output>allow null
the output whose origin anchors the coordinates, or null for the primary output
xint
x coordinate relative to the output origin
yint
y coordinate relative to the output origin
suggest a fixed position relative to an output

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.

set_cursor_placement_hint(x_offset: int, y_offset: int)
Argument
Type
Description
x_offsetint
horizontal offset of the surface center from the cursor center, positive to the right
y_offsetint
distance from the bottom of the cursor to the top of the surface
suggest placing the surface relative to the cursor

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.

Argument
Type
Description
flagsuint<treeland_dde_shell_surface_v2.skip_flag>
bitfield of views that should not list this surface
set window-listing preferences

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
acceptuint
0 to refuse keyboard focus, 1 to accept it
control whether the surface accepts keyboard focus

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.

Argument
Type
Description
roleuint<treeland_dde_shell_surface_v2.role>
the effective stacking role
effective stacking role of this surface

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.

Argument
Value
Description
normal0
normal window layer, below the overlay layer and participating in regular toplevel stacking
overlay1
workspace overlay layer, above normal toplevels and below layer-shell surfaces
always_on_topsince 22
above normal windows and below workspace overlay surfaces
rendering layer for a shell surface

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.

Argument
Value
Description
switcher0x1
do not list the window in the task switcher
dock_preview0x2
do not show the window in dock window previews
multitask_view0x4
do not list the window in the multitask view
window-listing preferences

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

No compositor support found

SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT