Repository files navigation

KDE KWin Script for snapping windows into zones. Handy when using a (super) ultrawide monitor, an alternative to PowerToys FancyZones and Windows 11 snap layouts.

The Zone Selector is a small widget that appears when you drag a window to the top of the screen. It allows you to snap the window to a zone regardless of the current layout.

The Zone Overlay is a fullscreen overlay that appears when you move a window. It shows all zones from the current layout and the window will snap to the zone you drop it on.

Edge Snapping allows you to snap windows to zones by dragging them to the edge of the screen.

Create multiple layouts and cycle between them.

KZones comes with a set ofshortcuts to move your windows between zones and layouts.

By using the same colors as your selected color scheme, KZones will blend in perfectly with your desktop.

To install KZones you can either use the built-in script manager or clone the repo and build it yourself.

Navigate toSystem Settings / Window Management / KWin Scripts / Get New… and search for KZones.

Depending on your Plasma version, one of these packages will be downloaded and installed:

• KZones
• KZones for Plasma 5

Make sure you have "zip" installed on your system before building.

git clone https://github.com/gerritdevriese/kzonescd kzones&& make

The script settings can be found underSystem Settings / Window Management / KWin Scripts / KZones / ⚙️

The zone selector is a small widget that appears when you drag a window to the top of the screen. It allows you to snap the window to a zone regardless of the current layout.

• Enable or disable the zone selector.
• Set the distance from the top of the screen at which the zone selector will start to appear.

The zone overlay is a fullscreen overlay that appears when you move a window. It shows all zones from the current layout and the window will snap to the zone you drop it on.

• Enable or disable the zone overlay.
• Choose whether the overlay should be shown when you start moving a window or when you press the toggle overlay shortcut.
• Choose where the cursor needs to be in order to highlight a zone, either in the center of the zone or anywhere inside the zone.
• Choose if you want the indicator to display all zones or only the highlighted zone.

Edge Snapping allows you to snap windows to zones by dragging them to the edge of the screen. Make sure to disable the default edge snapping functionality before enabling this.

• Enable or disable edge snapping.
• Set the distance from the edge of the screen at which the edge snapping will start to appear.

The script will remember the geometry of each window when it's moved to a zone. When the window is moved out of the zone, it will be restored to it's original geometry.

• Enable or disable this behavior.

If you have multiple monitors, you can enable this to track the active layout per screen. This will allow you to have different active layouts on different screens.

• Enable or disable this behavior.

When a new window is launched, the script will automatically snap it to its closest zone.

• Enable or disable this behavior.

Disable this if you don't want to see any OSD messages.

• Enable or disable this behavior.

Reduce the opacity of other windows while the active window is being moved.

• Enable or disable this behavior.

You can define your own layouts by modifying the JSON in theLayouts tab in the script settings, here are some examples to get you started:

[    {"name":"Layout 1","padding":0,"zones": [            {"x":0,"y":0,"height":100,"width":25            },            {"x":25,"y":0,"height":100,"width":50            },            {"x":75,"y":0,"height":100,"width":25            }        ]    }]

[    {"name":"Priority Grid","padding":0,"zones": [            {"x":0,"y":0,"height":100,"width":25            },            {"x":25,"y":0,"height":100,"width":50,"applications": ["firefox"]            },            {"x":75,"y":0,"height":100,"width":25            }        ]    },    {"name":"Quadrant Grid","padding":0,"zones": [            {"x":0,"y":0,"height":50,"width":50            },            {"x":0,"y":50,"height":50,"width":50            },            {"x":50,"y":50,"height":50,"width":50            },            {"x":50,"y":0,"height":50,"width":50            }        ]    },    {"name":"Columns","padding":0,"zones": [            {"x":0,"y":0,"height":100,"width":25            },            {"x":25,"y":0,"height":100,"width":25            },            {"x":50,"y":0,"height":100,"width":25            },            {"x":75,"y":0,"height":100,"width":25            }        ]    }]

The main array can contain as many layouts as you want:

Eachlayout object needs the following keys:

• name: The name of the layout, shown when cycling between layouts
• padding: The amount of space between the window and the zone in pixels
• zones: An array containing all zone objects for this layout

Eachzone object can contain the following keys:

• x,y: position of the top left corner of the zone in screen percentage
• width,height: size of the zone in screen percentage
• applications: an array of window classes that should snap to this zone when launched (optional)
• indicator: an object containing the indicator settings (optional)
  • position: default iscenter, other options aretop-left,top-center,top-right,right-center,bottom-right,bottom-center,bottom-left,left-center
  • margin: an object containing the margin for the indicator
    • top,right,bottom,left: margin in pixels
• color: a color name or hex value to tint the zone with (optional)

Stop certain windows from snapping to zones by adding them to the filter list.

• Select the filter mode, eitherInclude orExclude.
• Add window classes to the list seperated by a newline.

You can enable the debug overlay to see the window class of the active window.

The polling rate is the amount of time between each zone check when dragging a window. The default is 100ms, a faster polling rate is more accurate but will use more CPU. You can change this to your liking.

Here you can enable logging or turn on the debug overlay.

List of all available shortcuts:

To change the default bindings, go toSystem Settings / Shortcuts and search for KZones

Install the "Geometry change" KWin effect to animate window movements:https://store.kde.org/p/2136283

Replace the last part with any shortcut from the list above:

qdbus org.kde.kglobalaccel /component/kwin invokeShortcut"KZones: Cycle layouts"

Sometimes KWin can leave behind corrupt or missing shortcuts in the Settings after uninstalling or updating scripts, you can remove those using this command:

qdbus org.kde.kglobalaccel /component/kwin org.kde.kglobalaccel.Component.cleanUp

Check if your KDE Plasma version is at 6 or higher (for older versions, check the releases)
Make sure there is at least one layout defined in the script settings and that it contains at least one zone.

After changing settings, reload the script by disabling, saving and enabling it again.
This is a known issue with the KWin Scripting API

If you are using X11 make sure your compositor is enabled, as it is needed to draw transparent windows.
You can find this setting inSystem Settings / Display and Monitor / Compositor

Due to API changes in KWin 6, the newer versions of the script are not backwards compatible with Plasma 5.
If you were already subscribed to KZones using the script manager and updated to the latest version by accident, you will need to uninstall the script and subscribe to "KZones for Plasma 5" instead.