GTK4 Layer Shell

A library for using the Layer Shell and Session Lock Wayland protocols with GTK4. This Library is compatible with C, C++ and any language that supports GObject introspection files (Python, Vala, etc).

The Layer Shell protocol allows building desktop shell components such as panels, notifications and wallpapers. It can be used to anchor your windows to a corner or edge of the output, or stretch them across the entire output.

The Session Lock protocol allows building lock screens.

Documentation

GTK3 version

Reporting Bugs

• Try to include a minimum reproducer if possible (ideally in C)
• DO NOT REPORT GTK4 LAYER SHELL BUGS TO UPSTREAM GTK
• If you come across a genuine GTK bug while building a GTK Layer Shell program, reproduce it with this library completely absent (not included or linked in at all), and report to GTK using that reproducer

AI policy

AI agents are very useful, however I find their output annoying to read and frontier LLMs can not write code for this project that is consistently correct. Therefore:

• AI assistance in debugging and experimentation is encouraged
• All issue/PR comments must start with and should mostly consist of human writing
• If it's useful to include AI content for some reason, clearly mark it as such
• Production code must be human-written
• Test code may be AI-written if you've manually reviewed it
• Violations of this policy may result in the issue/PR being closed, or a sequence of bad-faith criticisms and tedious demands from my agent until yours give up

Supported Desktops

This library only works on Wayland, and only on Wayland compositors that support the Layer Shell protocol. Layer shell is supported on:

• wlroots based compositors (such as Sway)
• Smithay based compositors (such as COSMIC)
• Mir based compositors (some may not enable the protocol by default. It can be enabled with --add-wayland-extension zwlr_layer_shell_v1)
• KDE Plasma on wayland

Layer shell is not supported on:

• Gnome-on-Wayland
• Any X11 desktop

Using the Library

Demo

gtk4-layer-demo is built if examples are enabled. It's useful for testing layer shell support in compositors. Its code can be found in examples/demo/.

C/C++

The easiest way to build against GTK Layer Shell is to use the gtk-layer-shell-0 pkg-config package. Refer to your build system or the pkg-config docs for further instructions. examples/simple-example.c is a minimal complete app written in C. If you link against libwayland, you must link libwayland after gtk4-layer-shell. See linking.md for details.

Python

examples/simple-example.py contains sample Python code.

Vala

examples/simple-example.vala contains a minimal working Vala app.

Rust

@pentamassiv maintains safe Rust bindings and the crates.io crate. Rust examples can be found here.

Ruby

mswiger maintains Ruby bindings which are published to RubyGems.

Distro Packages

Building From Source

1. Clone this repo
2. Install build dependencies (see below)
3. $ meson setup -Dexamples=true -Ddocs=true -Dtests=true build (NOTE: --prefix=/usr may be needed on Arch Linux)
4. $ ninja -C build
5. $ sudo ninja -C build install
6. $ sudo ldconfig

Build Dependencies

• Meson (>=0.45.1)
• Ninja (>=1.8.2)
• libwayland (>=1.10.0)
• wayland-protocols (>=1.16.0)
• GTK4
• If introspection enabled: GObject introspection
• If docs enabled: GTK Doc
• If tests enabled: Python3
• If vapi enabled: Vala

To install these dependencies on Ubuntu 18.04 and later:

sudo apt install meson ninja-build libwayland-dev wayland-protocols libgtk-4-dev gobject-introspection libgirepository1.0-dev gtk-doc-tools python3 valac

To install on Arch Linux:

pacman -S --needed meson ninja gtk4 wayland wayland-protocols gobject-introspection libgirepository gtk-doc python vala

Meson Options

• -Dexamples (default false): If to build the example C apps; gtk4-layer-demo is installed if examples are built; The Vala example is never built with the rest of the project
• -Ddocs (default false): If to generate the docs
• -Dtests (default false): If to build the tests
• -Dsmoke-tests (default: true): If to test that all examples can run (disable if you don't want to install the various languages and dependencies required)
• -Dintrospection (default: true): If to build GObject Introspection data (used for bindings to languages other than C/C++)
• -Dvapi (default: true): If to build VAPI data and Vala example. The VAPI file allows this library to be used in Vala. Requires -Dintrospection=true

Running the Tests

• To run all tests: ninja -C build test
• To run specific test and print complete output: ninja -C build && meson test -C build --verbose <testname>
• To run tests under Valgrind (takes longer but catches memory issues) run with GTKLS_VALGRIND=1
• See test/README.md for more info and tips

Licensing

100% MIT (unlike the GTK3 version of this library which contained GPL code copied from GTK)