create desktop widgets and helpers

Traditional user interfaces can rely on this interface to define the foundations of typical desktops. Currently it's possible to set up background, panels and locking surfaces.

set_background(output: object<wl_output>, surface: object<wl_surface>)
Argument
Type
Description
outputobject<wl_output>
surfaceobject<wl_surface>
set_panel(output: object<wl_output>, surface: object<wl_surface>)
Argument
Type
Description
outputobject<wl_output>
surfaceobject<wl_surface>
set_lock_surface(surface: object<wl_surface>)
Argument
Type
Description
surfaceobject<wl_surface>
set_grab_surface(surface: object<wl_surface>)
Argument
Type
Description
surfaceobject<wl_surface>
set grab surface

The surface set by this request will receive a fake pointer.enter event during grabs at position 0, 0 and is expected to set an appropriate cursor image as described by the grab_cursor event sent just before the enter event.

desktop_ready()
desktop is ready to be shown

Tell the server, that enough desktop elements have been drawn to make the desktop look ready for use. During start-up, the server can wait for this request with a black screen before starting to fade in the desktop, for instance. If the client parts of a desktop take a long time to initialize, we avoid showing temporary garbage.

set_panel_position(position: uint)
Argument
Type
Description
positionuint
set panel position

Tell the shell which side of the screen the panel is located. This is so that new windows do not overlap the panel and maximized windows maximize properly.

configure(edges: uint, surface: object<wl_surface>, width: int, height: int)
Argument
Type
Description
edgesuint
surfaceobject<wl_surface>
widthint
heightint
prepare_lock_surface()
tell the client to create, set the lock surface

Tell the client we want it to create and set the lock surface, which is a GUI asking the user to unlock the screen. The lock surface is announced with 'set_lock_surface'. Whether or not the client actually implements locking, it MUST send 'unlock' request to let the normal desktop resume.

grab_cursor(cursor: uint)
Argument
Type
Description
cursoruint
tell client what cursor to show during a grab

This event will be sent immediately before a fake enter event on the grab surface.

panel_position { top, bottom, left, right } 
Argument
Value
Description
top0
bottom1
left2
right3
error { invalid_argument } 
Argument
Value
Description
invalid_argument0
an invalid argument was provided in a request

interface for implementing screensavers

Only one client can bind this interface at a time.

set_surface(surface: object<wl_surface>, output: object<wl_output>)
Argument
Type
Description
surfaceobject<wl_surface>
outputobject<wl_output>
set the surface type as a screensaver

A screensaver surface is normally hidden, and only visible after an idle timeout.


Compositor Support

Mutter
Mutter
46
KWin
KWin
6.2
Sway
Sway
1.9
COSMIC
COSMIC
1.0.0
Hyprland
Hyprland
0.42.0
niri
0.1.8
Weston
Weston
13
Mir
Mir
2.19
GameScope
GameScope
3.15.14
Jay
1.7.0
weston_desktop_shell
x
x
x
x
x
x
1
x
x
x