PlasmaZones

Window zone management for Wayland compositors

Define zones on your screen. Drag windows into them. Done.

---

Table of Contents

• How It Works
• Features
  • Window Snapping
  • Layout Editor
  • Autotiling
  • Shader Effects
  • Snap Assist
  • Zone Selector
  • Layout Picker
  • Multi-Monitor & Virtual Desktops
  • Settings App
• Installation
• Quick Start
• Keyboard Shortcuts
• Configuration
• Troubleshooting
• D-Bus API
• Project Structure
• Contributing
• Support

---

How It Works

Hold Alt (or your configured modifier) while dragging a window. Zones light up. Drop the window into one and it resizes to fill that zone.

---

Features

Window Snapping

Snapping

• Drag with modifier key or mouse button to snap windows to zones
• Always-active mode: zones activate on every drag without a modifier
• Enable/disable snapping globally
• Snap all visible windows to zones at once
• Auto-assign windows to first empty zone per layout
• Snap to multiple zones at once
• App-to-zone rules: auto-snap apps to specific zones on launch

Movement

• Move windows between zones with keyboard shortcuts
• Swap windows between zones directionally
• Rotate windows clockwise/counterclockwise through zones
• Push window to first empty zone
• Restore original size on unsnap
• Per-window floating toggle
• Staggered animations with elastic and bounce easing curves

Focus & Cycling

• Focus adjacent zones without mouse
• Cycle through windows stacked in the same zone

Layout Editor

• Visual canvas for drawing and resizing zones
• 26 built-in templates (columns, grids, fibonacci, master-stack, focus+stack, and more)
• Undo/redo, copy/paste, cut, duplicate
• Split zones horizontally or vertically
• Grid and edge snapping
• Fill available space / auto-expand
• Fullscreen editing mode
• Per-zone colors and styling
• Restrict layouts to specific screens, desktops, or activities

Autotiling

24 built-in JavaScript tiling algorithms including master+stack, dwindle, BSP, spiral, grid, monocle, and more. All algorithms run in a sandboxed engine and support hot-reload. You can create your own custom algorithms — see the full list and authoring guide on the Tiling Algorithms wiki page.

• Per-screen algorithm selection with independent settings
• Configurable master ratio and master count (separate settings for Centered Master vs Master+Stack)
• Inner and outer gaps with per-side control (top/bottom/left/right)
• Smart gaps — no gaps when only one window is tiled
• Max windows cap — overflow windows float automatically
• Hide title bars on tiled windows, with colored borders
• Window insertion position: end, after focused, or as master
• Focus follows mouse and focus new windows
• Minimized windows float, unminimized windows rejoin tiling
• Per-window floating toggle
• Staggered tiling animations
• Respect window minimum sizes (toggleable) — tiles expand to honor size hints reported by the application

Tip: Some apps enforce a minimum size that prevents tiles from reaching their intended geometry. To fix this, create a KWin Window Rule: System Settings → Window Management → Window Rules → add a rule matching the window class, set Minimum Size to Force 0×0 under the Size & Position tab. This removes the constraint so PlasmaZones can tile the window at any size.

Shader Effects

23 built-in GLSL shader effects for zone overlays, including audio-reactive visuals, distro-themed drifts, and procedural effects. Supports up to 4 custom image textures per shader plus desktop wallpaper sampling.

Custom shaders supported — see the full effect list and authoring guide in the Shader Guide on the wiki.

Snap Assist

After snapping a window, an overlay shows the remaining empty zones with thumbnails of other windows. Click a thumbnail to snap it into a zone.

Zone Selector

Drag to screen edge to reveal a layout picker. Jump straight to any layout and zone.

Layout Picker

Press Meta+Alt+Space to open a fullscreen layout picker. Click any layout to switch.

Visual Layout OSD

See a preview of the layout when switching, not just text.

Navigation OSD

Move, focus, swap, rotate, and push actions show a brief overlay with the affected zone numbers.

Multi-Monitor & Virtual Desktops

• Per-monitor layouts (same or different)
• Per-virtual-desktop layouts
• Per-activity layouts (optional, requires PlasmaActivities)
• Per-monitor zone selector settings
• Per-screen shader selection
• Screen-targeted app-to-zone rules

Settings App

Standalone settings app (plasmazones-settings) with sidebar navigation:

• Overview — Per-screen mode (snapping/tiling) with live context display
• Layouts — Create, duplicate, import/export zone layouts with 26 templates
• Snapping — Activation, zone appearance (colors, opacity, borders, blur, shaders), animations, zone selector, per-monitor/desktop/activity assignments
• Tiling — Per-screen algorithm selection, master ratio/count, gaps, title bar hiding, insertion order, focus behavior, per-monitor/desktop/activity assignments
• App Rules — Per-app zone assignment rules with interactive window picker
• Exclusions — Window class exclusion lists with interactive picker, minimum size thresholds
• Editor — Layout editor preferences and shortcut configuration
• General — OSD style, layout switch notifications, global behavior
• About — Version info, update checker, daemon status

On KDE Plasma, a System Settings entry provides version info and a launcher to the settings app.

---

Installation

Requirements

• Any Wayland compositor with layer-shell support
• Qt 6.6+
• qt6-wayland / Wayland::Client
• CMake 3.16+
• C++20 compiler
• wayland-scanner (build-time only)

Optional (for full KDE integration):

• KDE Frameworks 6.6+ (KWin effect, System Settings, KGlobalAccel shortcuts)
• PlasmaActivities (activity-based layouts)

Arch Linux (AUR)

# Binary package (prebuilt)
yay -S plasmazones-bin

# Source package (builds locally)
yay -S plasmazones

Fedora (COPR)

sudo dnf copr enable fuddlesworth/PlasmaZones
sudo dnf install plasmazones

openSUSE Tumbleweed (OBS)

Community-maintained package by ilFrance:

sudo zypper addrepo https://download.opensuse.org/repositories/home:ilFrance/openSUSE_Tumbleweed/home:ilFrance.repo
sudo zypper refresh
sudo zypper install plasmazones

Note: Do not use the Fedora RPM on openSUSE — it has incompatible Qt private API dependencies.

Nix

nix profile install github:fuddlesworth/PlasmaZones

Or add to your flake inputs. A flake.nix is included in the repository.

Building from Source

git clone https://github.com/fuddlesworth/PlasmaZones.git
cd PlasmaZones
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build -j$(nproc)
sudo cmake --install build

Portable build (no KDE dependencies):

cmake -B build -DUSE_KDE_FRAMEWORKS=OFF \
    -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build -j$(nproc)
sudo cmake --install build

This builds only the daemon and editor — no KWin effect or KCM. See Compositor Integration for shortcut and config setup on non-KDE compositors.

After installation, enable the daemon:

systemctl --user enable --now plasmazones.service

On KDE Plasma, also refresh the service cache for KCM:

kbuildsycoca6 --noincremental

Open the settings app:

plasmazones-settings

On KDE Plasma, PlasmaZones also appears in System Settings → Window Management → PlasmaZones with a launcher to the settings app.

Local install (no root)

cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/.local
cmake --build . -j$(nproc)
cmake --install .

Add these to your ~/.bashrc or ~/.zshrc:

export QT_PLUGIN_PATH=$HOME/.local/lib/qt6/plugins:$QT_PLUGIN_PATH
export QML2_IMPORT_PATH=$HOME/.local/lib/qt6/qml:$QML2_IMPORT_PATH
export XDG_DATA_DIRS=$HOME/.local/share:$XDG_DATA_DIRS

Then reload your shell and refresh the cache:

source ~/.bashrc  # or ~/.zshrc
kbuildsycoca6 --noincremental
systemctl --user enable --now plasmazones.service

RPM-based distros (Fedora/openSUSE)

An RPM spec is included in packaging/rpm/plasmazones.spec for building packages on Fedora, openSUSE, and other RPM-based distributions.

Universal Linux / Fedora Atomic (Portable Tarball)

For distributions where installing system packages is difficult (Fedora Atomic/Silverblue) or if you lack root privileges:

1. Download plasmazones-linux-x86_64.tar.gz from the Latest Release.
2. Extract the archive.
3. Run the installer script:

tar xzf plasmazones-linux-x86_64.tar.gz
cd plasmazones-linux-x86_64
./install.sh

The script installs PlasmaZones to ~/.local and sets up your environment variables.

Or use the one-liner:

bash <(curl -s https://raw.githubusercontent.com/fuddlesworth/PlasmaZones/main/packaging/local-install/web-install.sh)

Upgrading:

Run the installer again with a newer tarball. It will detect the existing installation and upgrade in place.

Uninstalling:

~/.local/share/plasmazones/uninstall.sh

---

Quick Start

1. Enable the daemon: systemctl --user enable --now plasmazones.service
2. Open settings: plasmazones-settings (or System Settings → PlasmaZones on KDE)
3. Click Open Editor to create a layout
4. Draw zones or pick a template
5. Save with Ctrl+S
6. Drag any window while holding Alt — zones appear, drop to snap

Tip: The settings app works on any compositor. On KDE, it also appears in System Settings.

---

Keyboard Shortcuts

Global Shortcuts

All configurable in System Settings → Shortcuts → PlasmaZones (KDE) or in the PlasmaZones settings app.

Layout switching

Action	Default Shortcut
Previous layout	Meta+Alt+[
Next layout	Meta+Alt+]
Quick layout 1–9	Meta+Alt+1 through Meta+Alt+9
Open layout picker	Meta+Alt+Space
Resnap windows to new layout	Meta+Ctrl+Z

Window movement & snapping

Action	Default Shortcut
Snap to zone 1–9	Meta+Ctrl+1 through Meta+Ctrl+9
Move window left/right/up/down	Meta+Alt+Shift+Arrow
Swap window left/right/up/down	Meta+Ctrl+Alt+Arrow
Push to empty zone	Meta+Alt+Return
Snap all windows to zones	Meta+Ctrl+S
Restore window size	Meta+Alt+Escape
Toggle float	Meta+F

Focus & cycling

Action	Default Shortcut
Focus zone left/right/up/down	Alt+Shift+Arrow
Cycle window forward	Meta+Alt+.
Cycle window backward	Meta+Alt+,
Rotate windows clockwise	Meta+Ctrl+]
Rotate windows counterclockwise	Meta+Ctrl+[

Autotiling

Action	Default Shortcut
Toggle autotile	Meta+Shift+T
Toggle float	Meta+F
Focus master window	Meta+Shift+M
Swap with master	Meta+Shift+Return
Increase master ratio	Meta+Shift+L
Decrease master ratio	Meta+Shift+H
Increase master count	Meta+Shift+]
Decrease master count	Meta+Shift+[
Retile windows	Meta+Shift+R

Other

Action	Default Shortcut
Open editor	Meta+Shift+E
Open settings	Meta+Shift+P
Toggle layout lock	Meta+Ctrl+L

Shortcut pattern (avoids conflicts with KDE defaults):

• Meta+Alt+{key} — Layout operations and actions
• Meta+Alt+Shift+Arrow — Zone movement (avoids KDE's Meta+Shift+Arrow screen movement)
• Meta+Ctrl+Alt+Arrow — Swap windows (avoids KDE's Meta+Ctrl+Arrow desktop switching)
• Alt+Shift+Arrow — Focus navigation (avoids KDE's Meta+Arrow quick tile)

Editor Shortcuts

Action	Shortcut
Save	Ctrl+S
Undo / Redo	Ctrl+Z / Ctrl+Shift+Z
Select all	Ctrl+A
Copy / Cut / Paste	Ctrl+C / Ctrl+X / Ctrl+V
Paste with offset	Ctrl+Shift+V
Delete zone	Delete
Duplicate zone	Ctrl+D
Split horizontal	Ctrl+Shift+H
Split vertical	Ctrl+Alt+V
Fill available space	Ctrl+Shift+F
Toggle fullscreen	F11
Move zone	Arrow keys
Resize zone	Shift+Arrow keys
Next / previous zone	Ctrl+Tab / Ctrl+Shift+Tab

---

Configuration

Open the settings app:

plasmazones-settings                    # opens on overview page
plasmazones-settings -p layouts         # opens directly to layouts page
plasmazones-settings --page tiling-behavior  # opens to tiling behavior page

The app is single-instance — launching it again while running raises the existing window and switches to the requested page.

Settings stored in ~/.config/plasmazones/config.json. Layouts stored as JSON in ~/.local/share/plasmazones/layouts/.

---

Troubleshooting

PlasmaZones not appearing in System Settings (KDE only)

Refresh the KDE service cache after installing from source:

kbuildsycoca6 --noincremental

Or log out and back in. The standalone settings app is always available:

plasmazones-settings

Daemon not starting

# Check status
systemctl --user status plasmazones.service

# View logs
journalctl --user -u plasmazones.service -f

# Restart
systemctl --user restart plasmazones.service

Zones not appearing when dragging

1. Ensure daemon is running: systemctl --user status plasmazones.service
2. Check drag modifier in settings (default: Alt)
3. Verify you have at least one layout with zones
4. Check if the application is excluded in settings

---

D-Bus API

PlasmaZones exposes 10 D-Bus interfaces on org.plasmazones for scripting and integration — Autotile, Control, LayoutManager, Overlay, Screen, Settings, Shader, and more.

# Quick examples
qdbus6 org.plasmazones /PlasmaZones org.plasmazones.LayoutManager.getLayoutList
qdbus6 org.plasmazones /PlasmaZones org.plasmazones.Overlay.showOverlay

Full API reference, scripting examples, and per-interface documentation: D-Bus API on the wiki.

---

Project Structure

See the full directory tree and data locations on the Project Structure wiki page.

---

Contributing

See CONTRIBUTING.md for guidelines on code style, license headers, testing, and translations.

---

Support

If PlasmaZones is useful to you, consider supporting development:

• Ko-fi
• GitHub Sponsors

Bug reports and feature requests: GitHub Issues

---

License

GPL-3.0-or-later

---

Inspired by FancyZones from PowerToys.

Works on KDE Plasma, Hyprland, Sway, GNOME, and any Wayland compositor with layer-shell support.