Integrate a desktop shell

These APIs are for shell authors. The compositor bridge provides live compositor state and operations. Desktop configuration starts with the configuration guide.

On this page

Dock animation targets
Layer placement and animation
Input and window control
Global shortcut portal

Dock animation targets

A dock can tell Gnoblin where each window's icon appears. Minimise and restore animations then use that rectangle.

With Quickshell, call Toplevel.setRectangle using coordinates relative to the dock's PanelWindow:

JavaScript

function updateTarget(toplevel) {
    const point = icon.mapToItem(dock.contentItem, 0, 0);
    toplevel.setRectangle(dock, Qt.rect(point.x, point.y, icon.width, icon.height));
}

Update after layout changes and when a window joins a group. Give each grouped window the same icon rectangle before minimising it.

A zero-size rectangle clears the hint. The hint also clears when its surface or window handle disappears.

A file manager beneath the Bingux dock in a Gnoblin session

Bingux is one separate shell project using Gnoblin; its dock can provide icon targets.

Layer placement and animation

During entry and exit animations, Gnoblin moves the displayed panel without asking the client to resize its buffer. Space reserved for the panel (its exclusive zone) stays unchanged, and it remains on the same monitor.

When a panel changes size, Gnoblin keeps its previous buffer aligned to its chosen edge until the client submits the new buffer. The client must still set its Wayland anchors and margins correctly.

Use a namespace rule with animation = "none" when the client owns its whole-surface transition. See animations.

Input and window control

Choose a window interface based on what the shell needs:

Interface	Use it for	Data and limits
`ext_foreign_toplevel_list_v1`	A portable, read-only window list	Mapped windows, identifier, title and app ID. The identifier lasts only while the window is mapped; no active state or control requests.
`zwlr_foreign_toplevel_manager_v1`	A protocol-based taskbar or switcher	Title, app ID and state; requests for activation, close, minimize, maximize and fullscreen. Check state events for results. Gnoblin omits optional `output_enter` and `output_leave`.
Compositor bridge	A Gnoblin-specific shell	Live window snapshots, actions, previews, workspaces and input sessions over Gnoblin's runtime socket.

See the Wayland protocol catalogue for advertised globals and versions. For persistent keybindings, use the Lua shortcut config. Use the window-menu contract for titlebar menus and the snapping contract for layout pickers.

Global shortcut portal

The Gnoblin portal delegates shortcut approval and configuration to the active shell. The portal does not draw shortcut UI. A shell that implements the Global Shortcuts portal can provide this UI over the session D-Bus.

Own the bus name org.gnoblin.Shell.GlobalShortcutsProvider and export the interface org.gnoblin.Shell.GlobalShortcutsProvider at /org/gnoblin/Shell/GlobalShortcutsProvider.

BindShortcuts receives the application ID, parent window, a shortcut list of type a(sa{sv}), and the request handle (o). The handle is the caller's org.freedesktop.portal.Request object path. The shell uses it, together with the application ID, to identify the requester; a host process with an empty application ID is identified by its executable. Each shortcut entry can include:

description (s): a label for the shortcut.
preferred_trigger (s): the application's suggested accelerator.

Return the same IDs with a shortcuts (as) option containing only user-approved accelerators. Return an empty list for shortcuts the user did not approve. The portal registers only returned accelerators with Gnoblin.

ConfigureShortcuts receives the application ID, parent window, and the request handle (o) from the BindShortcuts call that created the session. Return the updated list in the same format. The shell owns the approval UI and any stored selection; the portal owns the portal session and activation signals.

When the user changes saved bindings, call RebindShortcuts on the org.freedesktop.impl.portal.desktop.gnoblin service at the /org/gnoblin/Shell/GlobalShortcuts path, using the org.gnoblin.Shell.GlobalShortcutsRebind method.

Pass the application ID, the updated a(sa{sv}) list, and the request handle (o) from the BindShortcuts call that created the session. The portal replaces the active bindings and emits ShortcutsChanged to portal clients.