KWin Scripting

Overview & Architecture

KWin scripting runs JavaScript inside a QJSEngine instance embedded in the compositor process. Scripts execute in the same thread as KWin itself — there is no sandbox, no async I/O, and no separate process. A poorly-written script can stall frame delivery.

Scripts interact with windows and the compositor through two primary channels: the workspace singleton (window enumeration, signals, virtual desktop control) and individual Window objects (properties, geometry, stacking).

KDE Plasma 6 (KWin 6) migrated from KWin 5's custom QScriptEngine to a stricter QJSEngine. Several APIs were removed or renamed. Effect scripts now use a different API surface than window management scripts and are not covered here.

Installation & Loading

Script package layout

~/.local/share/kwin/scripts/myscript/
├── metadata.json          # required
└── contents/
    └── code/
        └── main.js        # entry point

metadata.json

{
  "KPlugin": {
    "Name": "My Script",
    "Description": "Does something useful",
    "Version": "1.0.0",
    "License": "GPL-2.0+",
    "Website": "",
    "Authors": [{ "Name": "You", "Email": "" }],
    "Id": "myscript",            // must match directory name
    "ServiceTypes": ["KWin/Script"]
  }
}

Enabling a script

# Enable via KWin's D-Bus interface (no restart required)
qdbus org.kde.KWin /Scripting org.kde.kwin.Scripting.loadScript \
    "~/.local/share/kwin/scripts/myscript/contents/code/main.js" \
    "myscript"

# Or through System Settings → Window Management → KWin Scripts
# Reload all loaded scripts:
qdbus org.kde.KWin /Scripting org.kde.kwin.Scripting.start

Global Objects

The scripting environment injects several globals into every script's scope at load time. You do not need to import or require them.

Window Objects

Each open window is represented by a Window object (formerly Client in KWin 5). These objects are live references — property changes on the real window are reflected immediately.

Key properties

Window methods

// Close (sends WM_DELETE_WINDOW):
win.closeWindow();

// Move to virtual desktop by object:
win.desktops = [workspace.desktops[0]];

// Move to a specific output:
win.output = workspace.screens[1];

// Set maximize state (h, v flags):
workspace.setMaximize(win, true, true);

// Resize and reposition:
win.geometry = Qt.rect(0, 0, 1280, 800);

Signals

KWin exposes Qt signals on both the workspace object and individual Window objects. Connect with standard JavaScript function assignment — there is no connect() wrapper in QJSEngine; you assign directly.

// Workspace-level signal: fires when any new window is mapped
workspace.windowAdded.connect(function(win) {
    print("added: " + win.caption + " class=" + win.resourceClass);
});

// Window-level signal: fires when geometry changes
workspace.windowAdded.connect(function(win) {
    win.frameGeometryChanged.connect(function() {
        print(win.caption + " moved to " + win.x + "," + win.y);
    });
});

Workspace signals

Window signals

Workspace API

Window enumeration

// All mapped windows (normal + special):
var all = workspace.windowList();

// Filter to normal application windows:
var normal = workspace.windowList().filter(function(w) {
    return w.normalWindow;
});

// Currently active window:
var active = workspace.activeWindow;

// Set focus:
workspace.activeWindow = someWindow;

Workspace properties

Workspace methods

clientArea AreaOption values

KWin.PlacementArea      // usable area (minus panels)
KWin.MaximizeArea       // area a maximized window occupies
KWin.MaximizeFullArea   // full screen area ignoring struts
KWin.FullScreenArea     // area for fullscreen windows
KWin.MovementArea       // area window centers may move within
KWin.ScreenArea         // full screen geometry
KWin.WorkArea           // union of all placement areas
KWin.FullArea           // union of all screen areas

Virtual Desktops & Screens

VirtualDesktop object

var desktops = workspace.desktops;

desktops.forEach(function(vd) {
    print(vd.id, vd.name, vd.x11DesktopNumber);
});

// Switch to first desktop:
workspace.currentDesktop = desktops[0];

// Assign window to desktop:
win.desktops = [desktops[2]];

// Pin window to all desktops:
win.onAllDesktops = true;

Output (screen) object

var screens = workspace.screens;

screens.forEach(function(out) {
    print(out.name,          // e.g. "DP-1", "HDMI-A-1"
          out.geometry,      // QRect: position and size in global coords
          out.devicePixelRatio // HiDPI scale factor
    );
});

// Move window to second screen:
if (screens.length > 1) {
    win.output = screens[1];
}

Geometry & Placement

The Qt namespace provides geometry constructors available in all scripts. Coordinates are in logical pixels (accounting for HiDPI scale).

// Center a window on its current screen:
function centerOnScreen(win) {
    var area = workspace.clientArea(KWin.PlacementArea, win);
    var nx = area.x + (area.width  - win.width)  / 2;
    var ny = area.y + (area.height - win.height) / 2;
    win.geometry = Qt.rect(nx, ny, win.width, win.height);
}

// Tile two windows side-by-side on the active screen:
function tileSideBySide(left, right) {
    var area = workspace.clientArea(KWin.MaximizeArea,
                                     workspace.activeScreen,
                                     workspace.currentDesktop);
    var half = Math.floor(area.width / 2);
    left.geometry  = Qt.rect(area.x,        area.y, half, area.height);
    right.geometry = Qt.rect(area.x + half, area.y, area.width - half, area.height);
}

Geometry constraints

KWin enforces minimum window size constraints from the client's size hints. Setting win.geometry to a rectangle smaller than win.minSize will silently clamp to the minimum. Read win.minSize (QSize) and win.maxSize (QSize) before attempting constrained placement.

var minW = win.minSize.width;
var minH = win.minSize.height;

Effects Integration

Window management scripts (under kwin/scripts/) and effect scripts (under kwin/effects/) use different API surfaces and run in different contexts. This article covers window management scripts only. Effect scripts have access to effect, effects, and the animating/painting APIs not available here.

From a window management script you can trigger built-in effects via D-Bus or by toggling window properties that effects react to:

// Trigger the present windows effect for current desktop:
callDBus("org.kde.KWin",
          "/Effects",
          "org.kde.kwin.Effects",
          "toggleEffect",
          "presentwindows");

// Activate "slide" desktop switch programmatically:
callDBus("org.kde.KWin",
          "/KWin",
          "org.kde.KWin",
          "nextDesktop");

Options & Config

Reading KWin options

// options is a read-only global reflecting kwinrc
print(options.focusPolicy);         // 0=ClickToFocus, 1=FocusFollowsMouse, etc.
print(options.xwaylandCrashPolicy);
print(options.borderSnapZone);      // snap distance in px

Reading script-specific config

Scripts can have their own configuration entries in kwinrc under a group named after the script's ID. Use readConfig() to access them:

// In kwinrc: [Script-myscript] / myKey=someValue
var val = readConfig("myKey", "defaultValue");

Scripts cannot write to their own config at runtime via the scripting API. For persistent user settings, write to kwinrc externally (e.g. via a KCM or CLI tool) and reload the script.

D-Bus & Shortcuts

D-Bus calls

// Blocking call — do not use in signal handlers that fire frequently
callDBus(service, path, iface, method[, arg1, arg2, ...][, callback]);

// With return value callback:
callDBus("org.kde.KWin", "/KWin", "org.kde.KWin", "supportInformation",
    function(result) { print(result); }
);

Keyboard shortcuts

registerShortcut(
    "Tile Left",           // display name (unique per KWin)
    "Tile Active Left",     // i18n name
    "Meta+Left",           // default key sequence (QKeySequence syntax)
    function() {
        var win = workspace.activeWindow;
        if (!win || !win.normalWindow) return;
        var area = workspace.clientArea(KWin.MaximizeArea, win);
        win.geometry = Qt.rect(area.x, area.y,
                                area.width / 2, area.height);
    }
);

Screen edge triggers

// Edge constants: 0=Top, 1=TopRight, 2=Right, 3=BottomRight,
//                 4=Bottom, 5=BottomLeft, 6=Left, 7=TopLeft

registerScreenEdge(6, function() {     // left edge
    callDBus("org.kde.plasmashell",
              "/PlasmaShell",
              "org.kde.PlasmaShell",
              "toggleDashboard");
});

// Unregister with:
unregisterScreenEdge(6);

Debugging

Print output

print("message");          // writes to KWin's logger
console.log("message");   // also works; same destination

Read output with:

journalctl -f SYSLOG_IDENTIFIER=kwin_wayland
# or for X11:
journalctl -f SYSLOG_IDENTIFIER=kwin_x11

Reloading a script without restarting

# Unload by script ID, then reload:
qdbus org.kde.KWin /Scripting stopScript 1    # script id from loadScript return
qdbus org.kde.KWin /Scripting loadScript \
    "/path/to/contents/code/main.js" "myscript"

Script IDs

# List all loaded scripts and their IDs:
qdbus org.kde.KWin /Scripting org.kde.kwin.Scripting.loadedScripts

Common errors

Porting: KWin 5 → 6

KWin 6 (Plasma 6) introduced breaking changes. The main areas to update:

Minimal working KWin 6 script

// main.js — KWin 6 compatible
// Moves every newly opened normal window to the primary screen.

workspace.windowAdded.connect(function(win) {
    if (!win.normalWindow) return;

    var primary = workspace.screens[0];
    if (win.output === primary) return;

    win.output = primary;

    var area = workspace.clientArea(KWin.PlacementArea,
                                     primary,
                                     workspace.currentDesktop);
    win.geometry = Qt.rect(
        area.x + (area.width  - win.width)  / 2,
        area.y + (area.height - win.height) / 2,
        win.width,
        win.height
    );
});