gnoblin.window_rule

Add an ordered window or layer-surface rule. All fields in match must match. Later matching rules override only the fields they provide.

See the window rules guide for usage patterns.

gnoblin.window_rule {
    match = {type = "window", app_id = "^org.example.App$"},
    opacity = 0.9,
}

Match fields

All supplied match fields must match. Text patterns use Lua 5.4 string.find syntax. They are case-sensitive and search anywhere by default. Use ^ and $ to match the whole value.

In Lua patterns, . matches any character and %. matches a literal dot. For example, ^org%.example%.App$ matches the complete ID org.example.App. JavaScript and PCRE regex syntax is not supported. workspace_id matches an exact, case-sensitive ID.

See the window rules guide for examples and ways to find a live app ID, title, or layer namespace.

Declare persistent workspace IDs in gnoblin.configure.workspaces. A matcher can also name an explicitly assigned runtime ID. Generated @session-N IDs are temporary and should not be saved in configuration. A {id = ...} placement target must exist when a matching window opens; if it does not, Gnoblin leaves the window in place and logs a warning.

Rule fields

To change one of these effects for one window while the session runs, use window:set_effect.

Blur follows the opacity of the surface it sits behind. When a layer-shell panel fades in or out, whether through a layer-open animation or its own alpha, the blur fades with it. Panels need no extra protocol or setting for this.

If a backdrop capture fails, Gnoblin shows the current backdrop without blur for that frame. Blur resumes after the next successful capture.

Uniform names must be valid GLSL-style identifiers; the gnoblin_ prefix is reserved. Values must fit in a finite 32-bit float.

Workspace match fields select a window's current workspace and update when the window changes workspaces.

The workspace placement effect runs once when a normal window is created. It is not reapplied when its title or focus changes or when the configuration reloads. Transient and modal windows stay with their parent. See the workspaces section of the window rules guide.

Corners

Shadows

The single native outline is configured by corners.border_width and corners.border_color above. Positive widths draw inward; negative widths draw outward where the client's existing buffer has room. The corners.shadow field accepts false, true for the default, one table, or a list of 1–4 shadow layers.

Animation fields

Choose a built-in or registered animation name. To select names by event, use a table:

• Use layer_open and layer_close for layer surfaces.
• duration and easing override the selected animation.

See the animation guide for supported events and presets.

Omitted values inherit shell settings. in needs brackets because it is a Lua keyword.

Frame fields

The generic default mode is off. GTK Wayland windows that create a KDE server-decoration object use auto behavior by default and receive Gnoblin's native frame. X11 apps running through Xwayland use auto when no rule sets frame.mode, because an X11 app has always left decorations to the window manager. A matching rule's frame.mode overrides that behavior.

An X11 app asks for a server frame when it is a normal, dialog or utility window and does not turn decorations off. An app that sets its Motif decorations hint to 0 draws its own frame and gets none under auto.

• _GTK_FRAME_EXTENTS declares the visible bounds, like xdg_surface.set_window_geometry.
• client_type = "x11" in match gives X11 apps their own frame rule.

auto supplies SSD only for explicit client requests. replace crops client pixels and adds a frame.

With prefer-server, Gnoblin clips CSD buffer margins to the app's declared visible bounds and applies Gnoblin's configured border and shadow there. It does not estimate margin sizes. An app that omits visible bounds uses its full surface.

frame.button_layout sets the right-side buttons in Gnoblin's built-in native frame, including the fallback shown while an external renderer is unavailable. It is not sent to external renderers. Those renderers use their own layout settings; Bingux follows GTK settings or its --button-layout argument.

The global window_management.button_layout preference does not control these frames. See titlebar button placement.

See the window frames guide for frame modes and extents. Register renderers with gnoblin.configure.

remove_csd

Enable remove_csd when an application draws its own rounded corners and you want Gnoblin's configured shape to control the result. Gnoblin inspects the window's rendered pixels to detect the corner cutouts, then fills those gaps from the app's nearby background before applying the configured corners.

Gnoblin adapts to each window's actual content instead of assuming a particular toolkit, corner radius, or background colour.

It also handles the narrow antialiased edge around the detected curve while preserving opaque content.

gnoblin.window_rule {
    match = {type = "window", app_id = "^org.example.App$"},
    corners = {
        radius = 12,
        mode = "force",
        remove_csd = true,
    },
}

This is opt-in because detecting and sampling the window image has a cost. Use it on rules for apps whose own rounded corners conflict with Gnoblin's shape; leave it off for other windows. The option changes corner rendering only. It does not remove client-side titlebars or other decorations.

If the app's corner background varies sharply near the edge, Gnoblin may not find a safe fill, so the original corner can remain visible.

Type definition

This is schema pseudocode in Lua table form. ? marks an optional field; | separates accepted alternatives. Every supplied match field must match.

gnoblin.window_rule {
    match = {
        type = "window" | "layer"?,
        focused = boolean?,
        app_id = string?, -- Lua 5.4 pattern
        title = string?, -- Lua 5.4 pattern
        layer = string?, -- Lua 5.4 pattern
        client_type = "wayland" | "x11"?,
        workspace_id = string?,
        workspace_number = integer?, -- 1–1024
    },
    blur = integer?, -- 0–100
    opacity = number?, -- 0–1
    blur_ignore_shadows = boolean?,
    shader = string?,
    shader_uniforms = {string = number}?,
    animation = string | {
        open = string?, close = string?,
        dialog_open = string?, dialog_close = string?,
        layer_open = string?, layer_close = string?,
        minimize = string?, restore = string?, workspace_switch = string?,
        shadow_change = string?,
        resize = string?,
        duration = integer?, -- 0–5000 ms
        easing = string?,
    }?,
    workspace = {id = string} | {number = integer}?,
    corners = {
        radius = number?, -- 0–200
        smoothing = number?, -- 0–1
        mode = "auto" | "force" | "off"?,
        padding = {number, number, number, number}?,
        border_width = number?, -- -40 to 40
        border_color = string?, -- #RRGGBB or #RRGGBBAA
        keep_maximized = boolean?,
        keep_fullscreen = boolean?,
        keep_tiled = boolean?,
        skip_libadwaita = boolean?,
        skip_libhandy = boolean?,
        remove_csd = boolean?,
        shadow = false | Shadow | {Shadow, ...}?,
        keep_shadow = boolean?,
        shadow_animation = {
        animation = string?,
            duration = integer?, -- 0–2000 ms
            easing = "linear" | "ease-out-cubic" | "ease-out-quad" | "ease-in-out-cubic"?,
        }?,
    }?,
    frame = {
        mode = "off" | "auto" | "prefer-server" | "replace"?,
        extents = {integer, integer, integer, integer}?, -- 0–256 each
        crop = {integer, integer, integer, integer}?, -- 0–256 each
        renderer = string?,
        style = string?,
        background = string?,
        foreground = string?,
        inactive_background = string?,
        button_layout = {"minimize" | "maximize" | "close", ...} | {}?,
    }?,
}

-- Shadow = {x = number?, y = number?, blur = number?, spread = number?,
--           opacity = number?, color = string?}