Files
komorebi/docs/usage/workspaces.md
T
LGUG2Z 62e37e44cf feat(kwin): workspaces are KWin's own desktops
komorebi's workspaces exist on Windows and macOS because neither has a virtual
desktop API: switching hides every window of the workspace being left. KWin has
virtual desktops, per output since 6.8, so here workspace i is KWin's desktop i
on every monitor, and each monitor shows one. KWin shows, hides and focuses the
windows of a desktop; komorebi asks for a switch, puts a window on a desktop,
and follows what anything else does.

The Backend gets the workspace methods (ensure_workspaces, switch_workspace,
set_window_workspace, window_workspace, current_workspaces), and the fake its
desktops. The bridge reports the desktops, the desktop each output shows and a
window's desktops, and carries out output_desktop and desktop commands, typed
and tested with the fixtures like the rest. The table turns a switch or a move
komorebi did not make into a WorkspaceChange or a WorkspaceMove, and records its
own when it sends them, so that KWin's report of those raises nothing. The
window manager follows a switch with no command in reply
(adopt_workspace_change), puts windows on their desktops before a desktop is
shown (focusing a window first would take the monitor back), and loads the
windows open at startup onto the workspace of their desktop.

Per-output desktops are a kwinrc setting that is off by default, and
kwriteconfig6 was not on the PATH of the user service in a live session, so
komorebi edits kwinrc itself (kwin::kwinrc) and puts the user's value back when
it stops, also after a crash.

focus-workspace, move-to-workspace and send-to-workspace come with this commit,
since the tests of switching and moving, and vm-workspace-switch, need them; the
named and cycling workspace commands follow. vm-workspace-switch runs the daemon
against a real KWin; vm-kwin-contract checks what komorebi relies on from KWin's
per-output desktops, on a headless KWin with two outputs and no komorebi.
2026-10-28 07:20:37 -07:00

2.3 KiB

Workspaces

Each monitor has workspaces, and shows one of them at a time. A workspace has its own windows and its own layout. komorebi's workspaces are KWin's virtual desktops: workspace 0 is the first desktop, workspace 1 the second, and so on, which is why the pager, the overview and KWin's shortcuts show and switch them too.

komorebi turns on KWin's per-output virtual desktops when it starts, so that each monitor shows a desktop of its own: switching the workspace of one monitor leaves the others as they are. It puts the setting back as it was when it stops.

Showing another workspace

komorebic focus-workspace shows a workspace of the focused monitor, by its number, counted from 0. KWin shows the windows of that workspace and hides the others, and the window of that workspace that had the focus has it again.

komorebic focus-workspace 1
komorebic focus-workspace 0

A workspace that does not exist yet is created, with the ones before it, and KWin gets a desktop for each, named "Workspace 2" and so on. A desktop that is there already keeps its name. The desktops komorebi creates stay when it stops.

Moving a window to another workspace

komorebic move-to-workspace takes the focused window to another workspace, puts it after the windows there, and shows that workspace. komorebic send-to-workspace does the same and stays on the workspace in front, which is tiled again without the window.

komorebic move-to-workspace 1
komorebic send-to-workspace 2

Switching with KWin

Anything that switches KWin's desktop switches komorebi's workspace: the pager, KWin's own shortcuts, the overview, or an application that raises a window of another desktop (KWin then shows that desktop and focuses the window). komorebi follows, tiles the workspace that came into view, and asks KWin for nothing in reply. A window moved to another desktop with the window menu's "Move to Desktop" moves to that workspace.

The windows that were open before

When komorebi starts, each window that is open goes to the workspace whose desktop it is on, and each monitor starts on the workspace KWin shows there. A window that is on every desktop goes to the workspace in front.