Protocol Support

Sweets implements a range of Wayland protocols for activation, cross-client window relationships, pointer control, and input methods. This page summarizes each one and how Sweets handles it.

XDG Activation

Sweets implements xdg-activation-v1. Launchers, portals, notifications, and applications can request activation for a mapped XDG toplevel.

Current policy: if the requested surface belongs to a managed window and the session is unlocked, Sweets switches to that window's workspace and focuses it. Requests for unmapped, unmanaged, or non-XDG surfaces are ignored.

XDG Foreign

Sweets implements xdg-foreign v1 and v2. Applications and portals can export an XDG toplevel from one client and import it from another, which lets helper windows, dialogs, and embedded flows establish parent/child relationships even when they are split across processes.

# smoke test
wayland-info | rg 'zxdg_(exporter|importer)_v[12]'

Relative Pointer and Pointer Constraints

Sweets implements relative-pointer-v1 and pointer-constraints-v1. Applications such as games, virtual machines, remote desktop clients, and 3D tools can request relative pointer events and lock or confine the pointer while their surface has pointer focus.

Current policy: Sweets activates constraints for the pointer-focused root surface on seat0. Locked pointers keep the compositor cursor stationary while relative motion continues to the client. Confined pointers clamp cursor motion to the client's constraint region. Compositor-owned move/resize grabs do not send relative pointer motion to clients.

Text Input and Input Methods

Sweets implements text-input-v3 and input-method-v2, the protocol pair used by input method frameworks such as Fcitx5 and IBus for compose/preedit text, candidate windows, and surrounding-text updates.

Current behavior: normal XDG windows and keyboard-interactive layer-shell surfaces can receive text-input focus, one input method can bind to seat0, IME keyboard grabs work after compositor keybindings, and input-method popup surfaces are placed near the client's cursor rectangle. Session lock clears IME focus so lock surfaces receive raw keyboard input.

# smoke test
fcitx5 -d
WAYLAND_DISPLAY=$WAYLAND_DISPLAY foot

Then focus a text field in a Wayland app and switch to an input method that shows preedit/candidate UI.

Virtual Keyboards

Sweets implements virtual-keyboard-v1, so on-screen keyboards, accessibility tools, remote-control tools, and some input-method setups can inject keyboard events into seat0.

Virtual keyboards go through the same routing as physical keyboards: compositor keybindings first, then shortcut inhibition and IME policy, then focused-client delivery. Session lock still takes priority.

# smoke test
wayland-info | rg zwp_virtual_keyboard_manager_v1

For an interactive test, use an on-screen keyboard client such as wvkbd if it is installed, then focus a text field and type from the on-screen keyboard.

Virtual Pointers

Sweets implements virtual-pointer-v1, so remote-control, accessibility, and automation tools can inject pointer motion, buttons, and scroll events into seat0.

Virtual pointers go through the normal cursor path: output activation, focus-follows-mouse, pointer constraints, interactive move/resize, click focus, and focused-client delivery all behave the same as with physical pointers.

# smoke test
wayland-info | rg zwlr_virtual_pointer_manager_v1

Presentation Time

Sweets implements wp_presentation_time. Clients receive accurate presentation feedback — the exact time a frame hit the screen, the refresh cycle, and whether it was shown with zero copy or hardware clocks. Media players and games use this for smooth frame pacing and audio/video sync.

There is nothing to configure. The scene graph emits feedback automatically for every surface it presents, so the data tracks each output's real refresh.

# smoke test
wayland-info | rg wp_presentation

Foreign Toplevel Listing

Sweets publishes the list of open windows so taskbars, docks, and window switchers can show and act on them. It implements both the older zwlr_foreign_toplevel_management_v1 and the modern ext-foreign-toplevel-list, side by side, so clients can use whichever they support.

Each XDG toplevel appears as a handle on both managers, created when the window maps and removed when it unmaps, with title and app-id kept in sync. The zwlr manager also carries state (focused, fullscreen, maximized, per-output) and accepts activate/close/fullscreen/maximize requests; ext-foreign-toplevel-list is listing-only by design, so it just mirrors title and app-id.

# smoke test
wayland-info | rg 'foreign_toplevel'

Toplevel Icon

Sweets implements xdg-toplevel-icon-v1. A client can give an individual window its own icon — either a themed icon name or pixel buffers — overriding the default icon derived from its app-id (useful when one app shows several windows that each want a distinct icon).

Sweets draws no title bars, so it does not paint the icon itself. Instead it records the per-window icon name and exposes it through the IPC views query as icon="<name>", so an IPC-driven bar or dock can render it. Buffer-only icons (no name) are accepted but not surfaced, since the text IPC cannot carry raw pixels. The compositor advertises a conventional set of preferred icon sizes (16–64 px).

# smoke test
wayland-info | rg xdg_toplevel_icon_manager_v1

Server-Side Decorations

Sweets draws window borders itself, so it asks clients not to draw their own title bars. It implements both xdg-decoration (the modern protocol) and KDE's obsolete org_kde_kwin_server_decoration (for clients, including some GTK builds, that only speak the old one).

Current policy: both default to server-side. For xdg-decoration Sweets forces server-side mode on every toplevel and re-asserts it if a client renegotiates. For KDE server-decoration it advertises a server-side default mode, which is the signal those clients read to drop their client-side decorations.

# smoke test
wayland-info | rg 'decoration'

Single-Pixel Buffer

Sweets implements single-pixel-buffer-v1. Clients can create a 1×1 buffer of a single solid color without allocating shared memory, which compositors, portals, and some toolkits use for cheap solid fills and placeholder surfaces. There is nothing to configure; the scene graph renders these buffers like any other.

# smoke test
wayland-info | rg wp_single_pixel_buffer_manager_v1

Alpha Modifier

Sweets implements alpha-modifier-v1. A client can ask the compositor to apply a constant opacity to one of its surfaces, instead of pre-multiplying alpha into every frame it submits. The scene graph applies the per-surface factor automatically, so there is nothing to configure.

# smoke test
wayland-info | rg wp_alpha_modifier_v1

Pointer Gestures

Sweets implements pointer-gestures-v1. Multi-finger touchpad gestures — swipe, pinch, and hold — are forwarded to the application under the pointer, so native clients get browser swipe-back, GTK pinch-zoom, and similar interactions.

Current policy: Sweets relays every swipe/pinch/hold begin, update, and end from the seat cursor straight to the pointer-focused client; wlroots delivers each gesture only to that client. Sweets does not bind gestures to compositor actions, so nothing is intercepted. The gesture events themselves only originate from a physical multi-finger touchpad via libinput, though the global is always advertised.

# smoke test
wayland-info | rg zwp_pointer_gestures_v1

Explicit Synchronization

Sweets implements linux-drm-syncobj-v1. Instead of implicit, driver-guessed buffer fences, clients hand the compositor explicit acquire/release timeline points, so the GPU is told exactly when a buffer is ready and when it is free to reuse. This removes a class of flicker and stutter and improves performance, most visibly on NVIDIA.

The protocol is advertised only when both the renderer and the backend support DRM synchronization timelines and a DRM device is available — in practice the DRM/KMS backend on a capable GPU. When that support is missing (for example a software renderer or a nested session whose parent lacks it), the global is simply not exposed and clients fall back to implicit sync. The scene graph handles the per-surface acquire and release fences.

It can be turned off with the explicit_sync general setting (default on). Keep it on for NVIDIA.

# smoke test (DRM/KMS session)
wayland-info | rg wp_linux_drm_syncobj_manager_v1

Tearing Control

Sweets implements tearing-control-v1. A client — typically a game — can hint that a surface should be presented immediately (async) rather than waiting for vsync, trading a possible tearing seam for lower latency.

Current policy: the hint is honored only when the global allow_tearing switch is on, the requesting window is fullscreen and driving the output, and the backend accepts a tearing page-flip for that frame. A fullscreen surface tagged a game through content-type-v1 (see below) counts as requesting tearing too, so games that set a content type but never speak tearing-control-v1 still get the low-latency path. Any frame that does not meet these conditions falls back to a normal vsynced flip. Tearing requires the DRM/KMS backend.

# smoke test
wayland-info | rg wp_tearing_control_manager_v1

Content Type

Sweets implements content-type-v1. A client can tag a surface with the kind of content it shows — photo, video, or game — so the compositor can make presentation decisions that fit. A fullscreen surface tagged game is treated as wanting low-latency presentation: when allow_tearing is on it triggers a tearing page-flip even without an explicit tearing-control-v1 hint. Other content types are advertised for clients but do not currently change presentation.

# smoke test
wayland-info | rg wp_content_type_manager_v1

Keyboard Shortcut Inhibition

Sweets implements keyboard-shortcuts-inhibit-v1. Apps such as virtual machines, remote desktop clients, and some games can ask Sweets to pass keyboard shortcuts through while their surface has focus.

Current policy is simple: Sweets honors inhibitors for the focused surface on seat0. While active, Sweets skips compositor keybindings and forwards key events to the client. Session lock still takes priority.