Wayland layer-shell integration. The custom QPA plugin that mounts QWindows as zwlr_layer_shell_v1 surfaces, plus the LayerSurface Qt wrapper that exposes anchors, exclusive zone, margins, and keyboard interactivity as Q_PROPERTYs.
Qt's standard QPA plugins (wayland, xcb) create desktop-level windows. Overlays such as zone outlines, snap-assist previews, and shader wallpapers need to live on a layer-shell surface with per-surface anchor, margin, exclusive-zone, and keyboard-interactivity configuration that the regular Qt surface API doesn't expose.
phosphor-wayland is the lowest level of the stack:
`phosphor-layer` sits one level up and provides the policy layer (roles, per-screen surface registry, topology coordinator). Application code typically uses phosphor-layer or `phosphor-surfaces` and only touches this lib through registerLayerShellPlugin() at startup.
| Type | Purpose |
|---|---|
| PhosphorWayland::LayerSurface | QObject wrapper around a zwlr_layer_shell_v1 surface; Q_PROPERTY for layer / anchors / exclusive zone / keyboard / scope / screen / margins |
| PhosphorWayland::LayerSurface::Layer | Background / Bottom / Top / Overlay |
| PhosphorWayland::LayerSurface::Anchors | Q_FLAGS of AnchorTop / Bottom / Left / Right; AnchorAll constant for full-screen anchors |
| PhosphorWayland::LayerSurface::KeyboardInteractivity | None / Exclusive / OnDemand |
| PhosphorWayland::LayerSurfaceProps | Property-key constants used by LayerSurface ↔ QPA plugin |
| PhosphorWayland::registerLayerShellPlugin | Header-only env-var setup before QGuiApplication |
| PhosphorWayland::addCompositorLostCallback / removeCompositorLostCallback | Process-wide subscription to zwlr_layer_shell_v1 global-removal (one-shot, thread-safe) |
| PhosphorWayland::BackgroundEffect | Compositor blur behind a region of a window (ext-background-effect-v1); blurSupported says whether the compositor applies it, and the region is a no-op until it does |
Register the plugin before QGuiApplication, then build a layer surface in the usual Qt style:
#include <PhosphorWayland/LayerShellPluginLoader.h>
#include <PhosphorWayland/LayerSurface.h>
int main(int argc, char** argv) {
PhosphorWayland::registerLayerShellPlugin(); // safe no-op on non-Wayland sessions
QGuiApplication app(argc, argv);
using namespace PhosphorWayland;
// Attach a LayerSurface to a QWindow BEFORE the first show(). The
// surface drives the QPA plugin via dynamic properties on the window.
QWindow window;
auto* surface = LayerSurface::get(&window); // factory; never `new LayerSurface`
surface->setLayer(LayerSurface::LayerOverlay);
surface->setAnchors(LayerSurface::AnchorAll);
surface->setKeyboardInteractivity(LayerSurface::KeyboardInteractivityOnDemand);
surface->setScope(QStringLiteral("zone-overlay"));
surface->setScreen(QGuiApplication::primaryScreen());
surface->setMargins(QMargins(8, 8, 8, 8));
window.show();
return app.exec();
}