Treeland layer shell extension

layer surface interactive move and resize integration for treeland

This protocol lets a layer-shell client hand interactive move and resize over to the compositor: the client starts an operation with begin_resize or begin_move, the compositor drives the surface size or position through layer-surface configure events, and reports state, rejection reasons, and placement through this interface.

The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in RFC 2119.

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.

manager for layer surface interactive move and resize

This interface allows a layer-shell client (typically a dock surface) to opt in to compositor-driven interactive move and resize, so the compositor owns the drag state machine and the client follows the resulting layer-surface configure events instead of racing its own set_size requests.

This protocol applies to any layer-shell surface. The compositor drives the surface's size (begin_resize) or position (begin_move) over an interactive drag; whether a particular axis is freely resizable depends on the concrete anchor configuration.

destroy()
destroy the layer shell extension manager

Destroy the manager object. This does not destroy layer shell objects created with get_layer_shell_extension_object; those remain valid until their wl_surface is destroyed or the client destroys them.

get_layer_shell_extension_object(id: new_id<treeland_layer_shell_extension_object_v1>, surface: object<wl_surface>)
create a layer shell extension object for an existing wl_surface

Create a layer shell extension object for an existing wl_surface. The surface is expected to be a layer-shell surface; the compositor reports layer_shell_extension_exists if the same wl_surface already has a layer shell extension object bound.

The layer shell extension object is tied to the wl_surface: when the wl_surface is destroyed, the treeland_layer_shell_extension_object_v1 object is destroyed by the compositor as well, and the client must call get_layer_shell_extension_object again for a new wl_surface. A layer shell extension object must not outlive its wl_surface.

Argument
Value
Description
layer_shell_extension_exists0
the wl_surface already has a layer shell extension object bound
wl_surface_invalid1
the get_layer_shell_extension_object wl_surface argument is invalid

compositor-driven interactive resize and move for a layer surface

The client starts an interactive resize with begin_resize, passing a serial from a recent pointer event. The compositor validates the serial, takes over the drag (like xdg_toplevel.resize) and drives the surface size through the standard layer-surface configure events, reporting the resize state and any size restrictions through this interface.

The client may also start an interactive move with begin_move; the exact move semantics and state reporting are not yet finalized.

destroy()
destroy the layer shell extension object
Argument
Type
Description
seatobject<wl_seat>
seat the resize is initiated from
serialuint
serial of a recent pointer button press on seat
edgesuint<treeland_layer_shell_extension_object_v1.resize_edge>
edge(s) the client wants to drag, none of which may be anchored
min_widthint
minimum width for this resize, 0 for none
min_heightint
minimum height for this resize, 0 for none
max_widthint
maximum width for this resize, 0 for none
max_heightint
maximum height for this resize, 0 for none
start an interactive resize

Start a compositor-driven interactive resize of the associated surface. The seat and serial must come from a recent pointer button press on that seat; an invalid serial makes the compositor reject the request with resize_error.bad_serial. edges names which edge (or corner) of the surface the client wants to drag, using the xdg_toplevel.resize_edge values. The client owns which edge it drags; the compositor executes the drag on the reported edge.

The compositor rejects the request with resize_error.bad_edges when any of the requested edges is anchored: an anchored edge is already fixed in place by the layer-shell layout, so dragging it has no effect. A corner value (top_left etc.) requires both of its edges to be unanchored, otherwise the request is rejected. A dock anchored to a single screen edge, for example, may only be dragged on the edge opposite to its anchor.

Any other value is rejected with resize_error.bad_edges. The compositor emits resizing(1) once the drag actually starts, resizing(0) when it ends, and drives the surface size through the standard layer-surface configure events. On a rejected request it emits resize_rejected with a resize_error reason; in that case no resize starts and resizing is never emitted for this request. A request on a destroyed surface or with a destroyed seat is also rejected, with resize_error.bad_surface or resize_error.bad_seat respectively.

The min/max size arguments bound this resize only: they apply while this drag is active and are not a persistent property of the surface. A value of 0 means no limit in that direction (minimum 0 / maximum unbounded); negative values are treated as 0. The compositor clamps the target size to these limits and reflects the clamped size through the standard layer-surface configure event. Invalid limits (min > max with both non-zero) are ignored for that axis.

resizing(resizing: uint)
Argument
Type
Description
resizinguint
1 during interactive resize, 0 after it ends
interactive resize state changed

resizing=1 when the compositor starts the interactive drag, resizing=0 when it ends. The client may use this to run a settle / spring animation after the drag finishes. resizing(1) is only emitted after the compositor has actually taken over the drag; rejected begin_resize requests instead cause a resize_rejected event.

Argument
Type
Description
erroruint<treeland_layer_shell_extension_object_v1.resize_error>
reason the resize was rejected
a begin_resize request was rejected

Emitted when a begin_resize request is rejected: the reason names a resize_error value. No resize starts and resizing is never emitted for the rejected request. The client should use this instead of inferring acceptance from the absence of a resizing(1) event, and may fall back to its own drag logic.

edge values for resizing

Values indicate which edge (or corner) of the surface is being dragged in a resize operation, named from the surface's own perspective. Values are bit flags matching xdg_toplevel.resize_edge exactly: 1=top, 2=bottom, 4=left, 8=right; corner values are the OR of two adjacent edges (top_left=5=1|4, bottom_left=6=2|4, top_right=9=1|8, bottom_right=10=2|8).

The layer surface is anchored to one screen edge and changes height, vertical surfaces (left/right) change width. Whether an edge may be dragged at all depends on the surface's anchor; see begin_resize.

Argument
Value
Description
bad_serial1
serial does not match a recent pointer button press on the seat
bad_edges2
edges is not a valid resize_edge value
inactive3
the compositor cannot take over the resize right now (no container, surface not layer, animation running, or seat refused the takeover)
bad_surface4
the surface is invalid or has been destroyed
bad_seat5
the seat is invalid or has been destroyed
reason a begin_resize request was rejected

begin_resize is rejected (no resize starts) when the serial is stale (bad_serial), the edges value is not a valid resize_edge (bad_edges), or the compositor cannot take over the resize right now (inactive). It is also rejected when the associated surface is invalid or has been destroyed (bad_surface), or the seat is invalid or has been destroyed (bad_seat). The compositor then emits resize_rejected with the reason; an accepted request instead emits resizing(1).


Compositor Support

No compositor support found

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