GTK4 Layer Shell

https://github.com/wmww/gtk4-layer-shell
Admin
A GTK4 library for building desktop shell components like panels, notifications, and lock screens...
Tokens:42,456
Snippets:316
Trust Score:9.3
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Build and install GTK Layer Shell from source

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/README.md

Build and install GTK Layer Shell from source. The meson setup command enables examples, docs, and tests; on Arch Linux, --prefix=/usr may be needed. Then compile, install, and refresh the dynamic linker cache.

```bash
meson setup -Dexamples=true -Ddocs=true -Dtests=true build
```

```bash
ninja -C build
```

```bash
sudo ninja -C build install
```

```bash
sudo ldconfig
```

--------------------------------

### Preload example: run weston-terminal with LAYER_* env vars

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/configuration.md

Command line example from layer_shell_preload.md that launches weston-terminal with the layer-shell preload library and several LAYER_* environment variables. Sets anchoring to left, right, and bottom (LAYER_ANCHOR='lrb'), height to 50, exclusive zone enabled (LAYER_EXCLUSIVE=1), and keyboard mode on-demand (LAYER_KEYBOARD=on-demand). The LD_PRELOAD path assumes the preload .so is installed at /usr/lib/liblayer-shell-preload.so.

```shell
$ LD_PRELOAD=/usr/lib/liblayer-shell-preload.so LAYER_ANCHOR='lrb' LAYER_HEIGHT=50 \
    LAYER_EXCLUSIVE=1 LAYER_KEYBOARD=on-demand weston-terminal
```

--------------------------------

### gtk_layer_init_for_window with anchors and exclusive zone

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Shows a complete setup with anchor, margin, and exclusive zone before presenting. Initializing an already-realized window is a programming error; the setup will not take effect properly.

```c
gtk_layer_init_for_window(window);            // 1: initialize
gtk_layer_set_anchor(window, GTK_LAYER_SHELL_EDGE_BOTTOM, TRUE);
gtk_layer_set_margin(window, GTK_LAYER_SHELL_EDGE_BOTTOM, 20);
gtk_layer_auto_exclusive_zone_enable(window); // push maximized windows away
gtk_window_present(window);                   // 2: realize — init must be first
```

--------------------------------

### Install build dependencies on Ubuntu

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/README.md

Install all build dependencies for GTK Layer Shell on Ubuntu 18.04 and later. This command installs Meson, Ninja, Wayland, GTK4, GObject introspection, GTK Doc, Python3, and Vala packages.

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

--------------------------------

### Install build dependencies on Arch Linux

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/README.md

Install all build dependencies for GTK Layer Shell on Arch Linux. This command installs Meson, Ninja, GTK4, Wayland, GObject introspection, GTK Doc, Python, and Vala packages.

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

--------------------------------

### Basic gtk_layer_init_for_window usage

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Shows the minimal setup for a layer surface: create a window, initialize it with gtk_layer_init_for_window(), then present it. The init call must precede gtk_window_present().

```c
GtkWindow* window = GTK_WINDOW(gtk_application_window_new(app));
gtk_layer_init_for_window(window);  // must precede present()
gtk_window_present(window);
```

--------------------------------

### Getting zwlr_layer_surface_v1 for raw interop

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Shows how to obtain the raw zwlr_layer_surface_v1 object for direct protocol interop. The pointer is nullable; check it before use.

```c
struct zwlr_layer_surface_v1* wl_obj = gtk_layer_get_zwlr_layer_surface_v1(window);
if (wl_obj) { /* raw protocol interop, e.g. zwlr_layer_surface_v1_set_size(wl_obj, w, h) */ }
```

--------------------------------

### Set keyboard mode to ON_DEMAND

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Example of setting the keyboard mode to GTK_LAYER_SHELL_KEYBOARD_MODE_ON_DEMAND. On protocol version < 4, the library warns and falls back to NONE.

```c
gtk_layer_set_keyboard_mode(window, GTK_LAYER_SHELL_KEYBOARD_MODE_ON_DEMAND);
```

--------------------------------

### Run weston-terminal with Layer Shell Preload

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/layer_shell_preload.md

Example command that preloads liblayer-shell-preload.so and sets LAYER_ environment variables to configure a layer surface. Use this to run any Wayland app with layer shell properties.

```bash
$ LD_PRELOAD=/usr/lib/liblayer-shell-preload.so LAYER_ANCHOR='lrb' LAYER_HEIGHT=50 LAYER_EXCLUSIVE=1 LAYER_KEYBOARD=on-demand weston-terminal
```

--------------------------------

### Enable respect-close if not already enabled

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Example usage of gtk_layer_get_respect_close. It checks if respect-close is disabled and enables it if so.

```c
if (!gtk_layer_get_respect_close(window)) gtk_layer_set_respect_close(window, TRUE);
```

--------------------------------

### Get and print layer namespace

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Retrieves the current namespace and prints it. The returned string is owned by the library and must not be freed.

```c
const char* ns = gtk_layer_get_namespace(window);
g_print("layer namespace: %s\n", ns);
```

--------------------------------

### Check exclusive edge enabled

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Example usage of gtk_layer_get_exclusive_edge_enabled. Retrieves whether exclusivity is enabled for the bottom edge.

```c
gboolean bottom_exclusive = gtk_layer_get_exclusive_edge_enabled(window, GTK_LAYER_SHELL_EDGE_BOTTOM);
```

--------------------------------

### Set keyboard mode to EXCLUSIVE

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Example of setting the keyboard mode to GTK_LAYER_SHELL_KEYBOARD_MODE_EXCLUSIVE, which grabs exclusive focus if the surface is on the top or overlay layer.

```c
/* Lockscreen-style overlay that grabs the keyboard */
gtk_layer_set_keyboard_mode(window, GTK_LAYER_SHELL_KEYBOARD_MODE_EXCLUSIVE);
```

--------------------------------

### Get protocol version

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Retrieves the protocol version supported by the compositor. Returns 0 when unsupported and may block for a Wayland roundtrip on first call.

```c
// 0 when unsupported; also blocks for a roundtrip on first call
guint protocol_version = gtk_layer_get_protocol_version();
```

--------------------------------

### Assign window to monitor with gtk_session_lock_instance_assign_window_to_monitor

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Assigns a GTK window to a specific monitor for the lock surface. This must be called with an unrealized window immediately after the lock starts, typically within a monitor signal handler. Do not call gtk_window_present() manually as the library handles this internally.

```c
void gtk_session_lock_instance_assign_window_to_monitor(
    GtkSessionLockInstance* self,
    GtkWindow *window,
    GdkMonitor *monitor
);
```

```c
static void on_monitor_present(GtkSessionLockInstance* lock, GdkMonitor* monitor, void* data) {
    // Called once per monitor when the lock starts, and for each new monitor while locked
    GtkWindow* window = GTK_WINDOW(gtk_application_window_new(app));
    GtkWidget* box = gtk_box_new(GTK_ORIENTATION_VERTICAL, 0);
    gtk_box_append(GTK_BOX(box), gtk_label_new("Locked"));
    gtk_window_set_child(window, box);
    gtk_session_lock_instance_assign_window_to_monitor(lock, window, monitor);
}
```

```c
static void on_monitor_present(GtkSessionLockInstance* lock, GdkMonitor* monitor, void* data) {
    GtkWindow* window = GTK_WINDOW(gtk_application_window_new(app));
    gtk_session_lock_instance_assign_window_to_monitor(lock, window, monitor);
    // No present() call needed; assign_window_to_monitor() presents for us
}
```

--------------------------------

### Enable respect-close and veto close

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Example usage of gtk_layer_set_respect_close. It enables respect-close and connects a close-request handler that returns TRUE to veto the close. This is needed to handle the .closed event without destroying the window.

```c
gtk_layer_set_respect_close(window, TRUE);
g_signal_connect(window, "close-request", G_CALLBACK(on_close_request), NULL);
/* on_close_request returns TRUE to veto the close */
```

--------------------------------

### Set exclusive edge preference

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Example usage of gtk_layer_set_exclusive_edge_enabled. Enables exclusivity on the bottom edge and disables it on the left edge, preferring the bottom edge for the exclusive zone.

```c
/* Prefer the bottom edge for the exclusive zone even though the surface also
 * touches the left edge */
gtk_layer_set_exclusive_edge_enabled(window, GTK_LAYER_SHELL_EDGE_BOTTOM, TRUE);
gtk_layer_set_exclusive_edge_enabled(window, GTK_LAYER_SHELL_EDGE_LEFT, FALSE);
```

--------------------------------

### Run mock server and client separately

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/test/README.md

Runs the mock server and a test client separately, useful for running under wayland-debug or GDB. Both commands use GTKLS_TEST_DIR=/tmp.

```bash
# server:
ninja -C build && GTKLS_TEST_DIR=/tmp ./build/test/mock-server/mock-server
```

```bash
# client:
ninja -C build && GTKLS_TEST_DIR=/tmp ./build/test/[testname] --auto
```

--------------------------------

### gtk_layer_get_keyboard_mode

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Gets the current keyboard interactivity mode of a layer surface.

```APIDOC
## gtk_layer_get_keyboard_mode

### Description
Gets the current keyboard interactivity mode of a layer surface.

### Signature
```c
GtkLayerShellKeyboardMode gtk_layer_get_keyboard_mode(GtkWindow* window);
```

### Parameters
- **window** (`GtkWindow*`) - Required - a layer surface

### Returns
- `GtkLayerShellKeyboardMode` - the current interactivity mode; `NONE` for non-layer windows.

### Example
```c
if (gtk_layer_get_keyboard_mode(window) == GTK_LAYER_SHELL_KEYBOARD_MODE_NONE) { /* passive */ }
```
```

--------------------------------

### Pin layer surface to monitor under an existing surface

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Shows how to set the monitor to the one under an existing surface using gdk_display_get_monitor_at_surface and gtk_layer_set_monitor.

```c
GdkMonitor* mon = gdk_display_get_monitor_at_surface(gdk_display_get_default(), surface);
gtk_layer_set_monitor(window, mon); /* pin to the monitor under an existing surface */
```

--------------------------------

### Build and manage CI container image with podman

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/test/README.md

Commands to build, push, run, and inspect the CI container image. Requires a GitHub token with write:packages, read:packages, and delete:packages scopes, and podman login to ghcr.io.

```bash
podman login ghcr.io -u wmww
```

```bash
podman build -f test/Containerfile -t ghcr.io/wmww/gtk4-layer-shell-ci:latest .
```

```bash
podman push ghcr.io/wmww/gtk4-layer-shell-ci:latest
```

```bash
podman run -it --replace --name gtk4-layer-shell-ci-0 ghcr.io/wmww/gtk4-layer-shell-ci:latest bash
```

```bash
podman exec -it gtk4-layer-shell-ci-0 bash
```

```bash
echo "$(("$(podman image inspect ghcr.io/wmww/gtk4-layer-shell-ci:latest --format '{{ .Size }}')" / 1024 / 1024)) MB"
```

--------------------------------

### Get exclusive zone

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Retrieves the current exclusive zone value for a layer surface.

```c
int zone = gtk_layer_get_exclusive_zone(window);
```

--------------------------------

### gtk_layer_get_respect_close

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Gets whether respect-close is enabled for the given layer surface. Returns `FALSE` by default.

```APIDOC
## gtk_layer_get_respect_close

### Description
Gets whether respect-close is enabled for the given layer surface. Returns `FALSE` by default.

### Signature
```c
gboolean gtk_layer_get_respect_close(GtkWindow *window);
```

### Parameters
- **window** (`GtkWindow *`) - Required - a layer surface

### Returns
- `gboolean` - whether respect-close is enabled (`FALSE` default)

### Example
```c
if (!gtk_layer_get_respect_close(window)) gtk_layer_set_respect_close(window, TRUE);
```
```

--------------------------------

### Python GI: SessionLock.Instance usage

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Shows how to create a SessionLock.Instance, connect to its signals, and request the lock using the Gtk4SessionLock typelib. The comment indicates that in the _on_monitor handler, assign_window_to_monitor should be called.

```python
from gi.repository import Gtk4SessionLock as SessionLock
lock = SessionLock.Instance.new()
lock.connect('locked', self._on_locked)
lock.connect('failed', self._on_failed)
lock.connect('unlocked', self._on_unlocked)
lock.connect('monitor', self._on_monitor)
# in _on_monitor: lock.assign_window_to_monitor(window, monitor)
lock.lock()
```

--------------------------------

### Get top margin value

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Retrieves the margin size for the top edge using gtk_layer_get_margin.

```c
int top_margin = gtk_layer_get_margin(window, GTK_LAYER_SHELL_EDGE_TOP);
```

--------------------------------

### Check if keyboard mode is NONE

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Example of checking if the current keyboard mode is GTK_LAYER_SHELL_KEYBOARD_MODE_NONE, which indicates passive interactivity.

```c
if (gtk_layer_get_keyboard_mode(window) == GTK_LAYER_SHELL_KEYBOARD_MODE_NONE) { /* passive */ }
```

--------------------------------

### Release validation and tagging commands

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/release_process.md

Commands for validating the release: run tests with Valgrind, manually test the demo, tag the release, and push the tag.

```bash
GTKLS_VALGRIND=1 ninja -C build test
```

```bash
build/examples/gtk4-layer-demo
```

```bash
git tag vA.B.C
```

```bash
git push origin vA.B.C
```

--------------------------------

### gtk_layer_init_for_window

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Initializes a GTK window as a layer surface. Must be called before the window is realized or while unmapped.

```APIDOC
## gtk_layer_init_for_window

### Description
Initializes a GTK window as a layer surface. Must be called before the window is realized (before `gtk_window_present()`) or while unmapped.

### Signature
```c
void gtk_layer_init_for_window(GtkWindow* window);
```

### Parameters
- **window** (`GtkWindow*`) - Required - GTK window to be turned into a layer surface

### Returns
- `void` - nothing

### When to Call
- Before the window is realized (before `gtk_window_present()`), or while unmapped.

### Throws/Guards
- `g_warning()` (returns without initializing) when not on Wayland, `window == NULL`, no layer shell global, or the libwayland shim is not initialized (link order).

### Side Effects
- Sets the window undecorated.
- Connects `notify::default-width` / `notify::default-height` handlers that invalidate the cached preferred size (so `gtk_window_set_default_size()` re-sizes the layer surface).
- Stores the per-window `gtk_layer_surface_t` as object data under key `"wayland_layer_surface"` (destroyed with the window).
- Installs the global layer-surface hook on first call.
- Remaps an already-mapped window (unrealize + map).

### Example
```c
GtkWindow* window = GTK_WINDOW(gtk_application_window_new(app));
gtk_layer_init_for_window(window);  // must precede present()
gtk_window_present(window);
```

```c
gtk_layer_init_for_window(window);            // 1: initialize
gtk_layer_set_anchor(window, GTK_LAYER_SHELL_EDGE_BOTTOM, TRUE);
gtk_layer_set_margin(window, GTK_LAYER_SHELL_EDGE_BOTTOM, 20);
gtk_layer_auto_exclusive_zone_enable(window); // push maximized windows away
gtk_window_present(window);                   // 2: realize — init must be first
```

### Notes
- Initializing an already-realized window is a programming error; the setup will not take effect properly.
```

--------------------------------

### gtk_layer_get_margin

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Gets the margin size for a given edge of the layer surface. Returns 0 for non-layer windows or invalid edges.

```APIDOC
## gtk_layer_get_margin

### Description
Gets the margin size for a given edge of the layer surface. Returns 0 for non-layer windows or invalid edges.

### Function Signature
```c
int gtk_layer_get_margin(GtkWindow* window, GtkLayerShellEdge edge);
```

### Parameters
- **window** (`GtkWindow*`) - Required - a layer surface
- **edge** (`GtkLayerShellEdge`) - Required - edge to query

### Returns
- `int` - margin size for `edge` (`0` for non-layer windows or invalid edges)

### Notes
- Source: `include/gtk4-layer-shell.h:273`, `src/gtk4-layer-shell.c:330`

### Example
```c
int top_margin = gtk_layer_get_margin(window, GTK_LAYER_SHELL_EDGE_TOP);
```
```

--------------------------------

### Python: Preload libgtk4-layer-shell with ctypes.CDLL

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/linking.md

Place at the top of the main script to force the dynamic linker to load libgtk4-layer-shell.so before libwayland-client when using GI Repository. Without this, GI may load dependencies in the wrong order and the shim fails.

```python
# For GTK4 Layer Shell to get linked before libwayland-client we must explicitly load it before importing with gi
from ctypes import CDLL
CDLL('libgtk4-layer-shell.so')
```

--------------------------------

### Create GtkSessionLockInstance and connect signals

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Creates a new session lock instance and connects to its signals: locked, failed, unlocked, and monitor.

```c
GtkSessionLockInstance* lock = gtk_session_lock_instance_new();
g_signal_connect(lock, "locked",   G_CALLBACK(on_session_locked), NULL);
g_signal_connect(lock, "failed",   G_CALLBACK(on_session_lock_failed), NULL);
g_signal_connect(lock, "unlocked", G_CALLBACK(on_session_unlocked), NULL);
g_signal_connect(lock, "monitor",  G_CALLBACK(on_monitor_present), NULL);
```

--------------------------------

### gtk_layer_get_exclusive_edge_enabled

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Gets whether exclusivity is enabled for the given edge. The surface may still have no actual exclusive zone depending on anchors.

```APIDOC
## gtk_layer_get_exclusive_edge_enabled

### Description
Gets whether exclusivity is enabled for the given edge. The surface may still have no actual exclusive zone depending on anchors.

### Signature
```c
gboolean gtk_layer_get_exclusive_edge_enabled(GtkWindow* window, GtkLayerShellEdge edge);
```

### Parameters
- **window** (`GtkWindow*`) - Required - a layer surface
- **edge** (`GtkLayerShellEdge`) - Required - the anchored edge

### Returns
- `gboolean` - whether exclusivity is enabled for `edge`

### Example
```c
gboolean bottom_exclusive = gtk_layer_get_exclusive_edge_enabled(window, GTK_LAYER_SHELL_EDGE_BOTTOM);
```
```

--------------------------------

### gtk_layer_get_monitor

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Gets the monitor that the surface has requested or will request. Returns NULL if unset or not a layer surface. To learn where it actually is, use gdk_display_get_monitor_at_surface().

```APIDOC
## gtk_layer_get_monitor

### Description
Gets the monitor that the surface has requested or will request. Returns `NULL` if unset or not a layer surface. To learn where it actually is, use `gdk_display_get_monitor_at_surface()`.

### Function Signature
```c
GdkMonitor* gtk_layer_get_monitor(GtkWindow* window);
```

### Parameters
- **window** (`GtkWindow*`) - Required - a layer surface

### Returns
- `GdkMonitor*` - *(transfer none, nullable)* the monitor the surface has/will request (`NULL` if unset or not a layer surface).

### Example
```c
if (gtk_layer_get_monitor(window)) { /* a monitor was requested */ }
```
```

--------------------------------

### Let compositor decide monitor

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Shows how to reset the monitor to NULL so the compositor decides. This also happens automatically when the monitor is invalidated.

```c
gtk_layer_set_monitor(window, NULL); /* compositor decides; also auto on monitor invalidate */
```

--------------------------------

### gtk_layer_get_exclusive_zone

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Gets the effective exclusive zone for a layer surface. Returns the cached automatic value when auto mode is on, otherwise the explicit value.

```APIDOC
## gtk_layer_get_exclusive_zone

### Description
Gets the effective exclusive zone for a layer surface. Returns the cached automatic value when auto mode is on, otherwise the explicit value.

### Function Signature
```c
int gtk_layer_get_exclusive_zone(GtkWindow* window);
```

### Parameters
- **window** (`GtkWindow*`) - Required - a layer surface

### Returns
- `int` - the effective exclusive zone: the cached automatic value when auto mode is on, otherwise the explicit value. `0` for non-layer windows.

### Example
```c
int zone = gtk_layer_get_exclusive_zone(window);
```
```

--------------------------------

### Run a single test with meson

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/test/README.md

Runs a single test by name with verbose output. Requires a prior build.

```bash
ninja -C build && meson test -C build --verbose [testname]
```

--------------------------------

### Anchor wallpaper to stretch across output

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Anchors a window to all four edges, stretching it across the whole output.

```c
/* Wallpaper: stretch across the whole output */
gtk_layer_set_anchor(window, GTK_LAYER_SHELL_EDGE_LEFT, TRUE);
gtk_layer_set_anchor(window, GTK_LAYER_SHELL_EDGE_RIGHT, TRUE);
gtk_layer_set_anchor(window, GTK_LAYER_SHELL_EDGE_TOP, TRUE);
gtk_layer_set_anchor(window, GTK_LAYER_SHELL_EDGE_BOTTOM, TRUE);
```

--------------------------------

### GtkLayerShellLayer enum definition

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/types.md

Defines the GtkLayerShellLayer enum with values matching zwlr_layer_shell_v1_layer. The ENTRY_NUMBER sentinel is not a valid layer and should only be used to get the number of entries.

```c
typedef enum {
    GTK_LAYER_SHELL_LAYER_BACKGROUND = 0,
    GTK_LAYER_SHELL_LAYER_BOTTOM = 1,
    GTK_LAYER_SHELL_LAYER_TOP = 2,
    GTK_LAYER_SHELL_LAYER_OVERLAY = 3,
    GTK_LAYER_SHELL_LAYER_ENTRY_NUMBER, // Should not be used except to get the number of entries
} GtkLayerShellLayer;
```

--------------------------------

### Run all tests

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/README.md

Run all tests for GTK Layer Shell. This command executes the test suite after building.

```bash
ninja -C build test
```

--------------------------------

### Check if a monitor was requested

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Shows how to use gtk_layer_get_monitor to check whether a monitor has been requested for the window.

```c
if (gtk_layer_get_monitor(window)) { /* a monitor was requested */ }
```

--------------------------------

### Run all tests under valgrind

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/test/README.md

Runs all tests under valgrind by setting the GTKLS_VALGRIND environment variable.

```bash
GTKLS_VALGRIND=1 ninja -C build test
```

--------------------------------

### Shell: Use LD_PRELOAD to force library load order

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/linking.md

Run the program with LD_PRELOAD set to the path of gtk4-layer-shell to force it to load before libwayland-client. This is a general workaround for most applications.

```shell
LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libgtk4-layer-shell.so my-app
```

--------------------------------

### Set layer to overlay and get current layer

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Sets the layer to GTK_LAYER_SHELL_LAYER_OVERLAY and then retrieves the current layer. On older compositors, setting the layer may cause a remap.

```c
gtk_layer_set_layer(window, GTK_LAYER_SHELL_LAYER_OVERLAY); // remaps if protocol too old
GtkLayerShellLayer current = gtk_layer_get_layer(window);
```

--------------------------------

### Check session lock support

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Shows how to check for session lock support before proceeding. If the function returns FALSE, it logs a message and exits with status 1.

```c
if (!gtk_session_lock_is_supported()) {
    g_message("Session lock not supported");
    return 1;
}
```

--------------------------------

### Check lock status with gtk_session_lock_instance_is_locked

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Use this function to determine if a session lock instance is currently active. The example demonstrates checking the status before updating a UI indicator.

```c
gboolean gtk_session_lock_instance_is_locked(GtkSessionLockInstance* self);
```

```c
if (gtk_session_lock_instance_is_locked(lock)) {
    /* show a "locked" indicator in your control surface */
}
```

--------------------------------

### gtk_session_lock_instance_new()

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Creates a new session lock instance. Connect signals to handle lock, failed, unlocked, and monitor events.

```APIDOC
## gtk_session_lock_instance_new()

### Description
Creates a new session lock instance. Connect signals to handle lock, failed, unlocked, and monitor events.

### Method
Constructor

### Parameters
None

### Returns
A new GtkSessionLockInstance object.

### Example (Python GI)
```python
from gi.repository import Gtk4SessionLock as SessionLock
lock = SessionLock.Instance.new()
```
```

--------------------------------

### Run test under wayland-debug

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/test/README.md

Runs a test against the current compositor under wayland-debug, filtering for zwlr_*, xdg_*, and ext_* protocols.

```bash
ninja -C build && wayland-debug -f 'zwlr_*, xdg_*, ext_*' -r ./build/test/<testname> --auto
```

--------------------------------

### gtk_layer_init_for_window declaration

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Declares the function that turns a GTK window into a layer surface. Must be called before the window is realized (before gtk_window_present()) or while unmapped. Emits a g_warning() and returns without initializing when not on Wayland, when window is NULL, when no layer shell global exists, or when the libwayland shim is not initialized.

```c
void gtk_layer_init_for_window(GtkWindow* window);
```

--------------------------------

### gtk_layer_get_protocol_version

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Returns the version of zwlr_layer_shell_v1 supported by the compositor, or 0 if unsupported. May block for a Wayland roundtrip on first call.

```c
guint gtk_layer_get_protocol_version();
```

--------------------------------

### Run a specific test with verbose output

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/README.md

Run a specific test and print complete output. Replace <testname> with the actual test name. The command rebuilds first and then runs the specified test with verbose output.

```bash
ninja -C build && meson test -C build --verbose <testname>
```

--------------------------------

### gtk_layer_is_supported

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Returns TRUE if the platform is Wayland and the compositor supports zwlr_layer_shell_v1. May block for a Wayland roundtrip on first call and implicitly calls gtk_init().

```c
gboolean gtk_layer_is_supported();
```

--------------------------------

### Set and reset layer namespace

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Shows how to set a custom namespace and reset it to the default. The namespace is a compositor-side hint, typically generic values like "panel" or "osk".

```c
gtk_layer_set_namespace(window, "panel");
gtk_layer_set_namespace(window, NULL); /* back to default "gtk4-layer-shell" */
```

--------------------------------

### Anchor panel to bottom-left corner

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Anchors a window to the left and bottom edges, pinning it to the bottom-left corner.

```c
/* Panel pinned to the bottom-left corner */
gtk_layer_set_anchor(window, GTK_LAYER_SHELL_EDGE_LEFT, TRUE);
gtk_layer_set_anchor(window, GTK_LAYER_SHELL_EDGE_BOTTOM, TRUE);
```

--------------------------------

### gtk_session_lock_instance_new

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Creates a new GtkSessionLockInstance object.

```APIDOC
## gtk_session_lock_instance_new

### Description
Creates a new (unlocked) session lock instance.

### Method
Constructor

### Signature
```c
GtkSessionLockInstance* gtk_session_lock_instance_new();
```

### Returns
- **GtkSessionLockInstance*** - a new (unlocked) session lock instance.

### Example
```c
GtkSessionLockInstance* lock = gtk_session_lock_instance_new();
g_signal_connect(lock, "locked",   G_CALLBACK(on_session_locked), NULL);
g_signal_connect(lock, "failed",   G_CALLBACK(on_session_lock_failed), NULL);
g_signal_connect(lock, "unlocked", G_CALLBACK(on_session_unlocked), NULL);
g_signal_connect(lock, "monitor",  G_CALLBACK(on_monitor_present), NULL);
```
```

--------------------------------

### gtk_layer_get_micro_version

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Returns the micro/patch version of the library as a guint. For v1.3.0 this is 0.

```c
guint gtk_layer_get_micro_version();
```

--------------------------------

### gtk_layer_get_micro_version

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-layer-shell.md

Returns the micro/patch version of the library.

```APIDOC
## gtk_layer_get_micro_version

### Description
Returns the micro/patch version of the library.

### Signature
```c
guint gtk_layer_get_micro_version();
```

### Returns
- **guint** — micro/patch version (`0` for v1.3.0).

### Source
- `include/gtk4-layer-shell.h:111`, `src/gtk4-layer-shell.c:32`
```

--------------------------------

### gtk_session_lock_is_supported

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Documentation for the gtk_session_lock_is_supported function, which checks platform support for session locking.

```APIDOC
## gtk_session_lock_is_supported

### Description
Checks whether the session lock functionality is supported on the current platform. Returns TRUE if the platform is Wayland and the compositor binds the `ext_session_lock_manager_v1` global. May block for a Wayland roundtrip the first time it is called.

### Method
Function call

### Signature
```c
gboolean gtk_session_lock_is_supported();
```

### Parameters
None

### Returns
- **gboolean** - TRUE if the platform is Wayland and the compositor binds `ext_session_lock_manager_v1`.

### Example
```c
if (!gtk_session_lock_is_supported()) {
    g_message("Session lock not supported");
    return 1;
}
```
```

--------------------------------

### Run test against current compositor

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/test/README.md

Runs a test against the current Wayland compositor with the --auto flag. Useful for debugging because you can see the output. Avoid running session lock tests this way as they may soft-brick the compositor.

```bash
ninja -C build && ./build/test/<testname> --auto
```

--------------------------------

### Lock the session and handle immediate failure

Source: https://github.com/wmww/gtk4-layer-shell/blob/main/_autodocs/api-reference/gtk4-session-lock.md

Calls gtk_session_lock_instance_lock() and quits the application if it returns false, noting that ::failed was already emitted.

```c
if (!gtk_session_lock_instance_lock(lock)) {
    /* ::failed was emitted already */
    g_application_quit(G_APPLICATION(app));
    return;
}
/* ::locked will be emitted asynchronously once the compositor confirms */
```
Tokens:
Raw