gnoblin.configure.window_management

Configure this part of gnoblin.configure with the window_management key.

Put these fields inside gnoblin.configure {window_management = {...}}. Changes apply on configuration reload. Omitted fields use the defaults below.

Settings at a glance

Focus and raising

Placement and responsiveness

Leave disable_workarounds set to false unless you are debugging an X11 application. Enabling it can make some applications behave incorrectly.

constrain_drag_to_work_area controls how far a dragged window can leave the work area, which is the monitor minus the space that panels reserve.

• With true, the whole window stays inside the work area.
• With false, Mutter's own rule applies: a window can move until only a strip of it stays on screen, at most 75 pixels tall.

The setting is read when a drag starts, so a reload affects the next drag.

new_window_placement applies only to normal application windows. Dialogs, modal dialogs, splash screens and transient windows keep Mutter's own placement. The values are:

• "free_space": the window opens in the first free area of the monitor, scanning from the top-left below and beside existing windows. When no area fits, it cascades from the top-left. This is Mutter's default.
• "center": the window opens centred on the monitor's work area. If that spot exactly covers an existing window, it cascades from the centre.
• "cascade": the window always steps diagonally from the top-left, past the last placed window, without looking for a free area.

The table shows the compositor default when a key is missing. The starter config that Gnoblin loads first sets these values instead, so they are what you get unless your own config changes them:

Set any of them in your own config to change it.

Titlebar buttons and actions

Focus behavior

focus_mode controls how pointer movement changes focus:

• "click" focuses a window when you click it. Moving the pointer does not change focus.
• "hover" focuses a window when the pointer enters it. If the pointer leaves all windows, focus returns to the last window you used that can take focus.
• "hover-strict" also focuses on pointer entry, but clears focus when the pointer leaves all windows.

Set focus_change_on_pointer_rest = true to change focus only after the pointer rests briefly.

Pointer bindings

Configure modified dragging and window menus with keybindings.pointer. The default Lua callbacks bind Super + left-drag to move and Super + right-drag to resize from the nearest corner. These gestures work on application windows with client or server decorations.

Titlebar button placement

window_management.button_layout stores Mutter's global layout preference. Current Gnoblin frame renderers do not use it to draw buttons, so changing it can appear in gnoblinctl config show without changing any titlebar.

For Gnoblin's built-in native frame, set frame.button_layout in a window rule. External renderers and client-side titlebars use their own layout settings. Bingux's GTK renderer follows GTK settings unless its --button-layout argument overrides them.

The global preference accepts the following values for compatibility. Its default leaves the left side empty and lists minimize, maximize, and close on the right.

Set either side to an ordered list of "menu", "minimize", "maximize", or "close". A "spacer" between two buttons adds a gap. A button can appear at most once on each side.

gnoblin.configure {
    window_management = {
        button_layout = {
            left = {"menu"},
            right = {"minimize", "maximize", "close"},
        },
    },
}

Omitting either side keeps its default. Use gnoblin.array {} to hide all buttons on a side because an unmarked empty Lua table is treated as a map. See gnoblin.array.

Mutter ignores changes to the desktop button-layout preference in its own preference cache while Gnoblin is running. This does not override GTK settings in external renderers or client applications.

focus_new_windows controls when app activation requests can focus a window. Mutter's standard policy has two choices.

• "prevent" enables Mutter's focus-stealing prevention. It is the compositor's value when the key is missing. Activation requests need recent launch or user activity. A newly opened window must also be a transient descendant of the focused window, such as a dialog opened by that app. Requests without valid recent activity leave the window unfocused, including a window you start from a launcher and a password dialog.
• "allow" is the starter config value. It allows applications to activate their windows after you have interacted with another window since they opened them.

In a Gnoblin session, "prevent" makes Mutter use its focus-stealing checks. See Gnoblin's Mutter patch for this session-specific behavior. See the focus prevention guide for a ready-to-use config example.

Declare named workspaces in the top-level workspaces field of gnoblin.configure; workspace declarations do not belong in window_management. Declared workspaces remain available even when empty.

Each entry has a required id and name. Names must be nonempty and at most 80 characters. IDs must be unique and match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.

Declare at least one workspace. List order sets their initial positions. IDs stay attached as positions change. If workspaces is omitted, Gnoblin starts with four unconfigured workspaces. A declaration list replaces that baseline, and its length sets the persistent workspace count. Scripts can add temporary workspaces at runtime.

See the workspace rules guide for matching and placement examples, and the writing workspace recipe for runtime automation. See the Lua runtime API for all callable runtime methods.

For example, use pointer-follow focus and declare two persistent workspaces:

gnoblin.configure {
    window_management = {
        focus_mode = "hover",
    },
    workspaces = {
        {id = "main", name = "Main"},
        {id = "chat", name = "Chat"},
    },
}

Titlebar actions

The three titlebar click fields accept these values:

These settings control what a click on a titlebar does, including a titlebar drawn by Gnoblin's native frame. Applications that draw their own client-side titlebars handle those clicks themselves.

GTK applications usually draw their own titlebars and read the desktop's window manager settings directly. This Lua section does not change those apps' CSD behavior. A custom SSD renderer implements its own titlebar click behavior.

See titlebars.

Type definition

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

gnoblin.configure {
    window_management = {
        focus_mode = "click" | "hover" | "hover-strict"?,
        focus_new_windows = "allow" | "prevent"?,
        auto_maximize = boolean?,
        raise_on_click = boolean?,
        auto_raise = boolean?,
        focus_change_on_pointer_rest = boolean?,
        auto_raise_delay = integer?, -- 0–10000 ms
        check_alive_timeout = integer?, -- 0–4294967295 ms; 0 disables the liveness check
        action_double_click_titlebar = TitlebarAction?,
        action_middle_click_titlebar = TitlebarAction?,
        action_right_click_titlebar = TitlebarAction?,
        button_layout = {
            left = TitlebarButton[]?,
            right = TitlebarButton[]?,
        }?,
        workspaces_only_on_primary = boolean?,
        edge_tiling = boolean?,
        new_window_placement = "free_space" | "center" | "cascade"?,
        attach_modal_dialogs = boolean?,
        disable_workarounds = boolean?,
        constrain_drag_to_work_area = boolean?,
    },
    workspaces = {
        {id = string, name = string},
        ...
    }?,
}

-- TitlebarAction = "toggle-maximize" | "toggle-maximize-horizontally"
--                | "toggle-maximize-vertically" | "minimize" | "lower"
--                | "menu" | "none"
-- TitlebarButton = "menu" | "minimize" | "maximize" | "close" | "spacer"