Files
komorebi/docs/usage/sleeping-and-locking.md
T
LGUG2Z 0210ec285a feat(kwin): sleep, wake and lock
While the screen is locked or the machine is asleep, KWin sends its clients no
frame callbacks, so nothing komorebi asked for in that time is done: a window
that something else moved stays where it was moved, and the monitors can come
back in another order or at another size. Nothing told komorebi it had happened,
and it kept the layout it had until the next event.

kwin::power now watches for the two ends of it: logind's PrepareForSleep on the
system bus, which only logind may send, and the lock screen's ActiveChanged on
the session bus. When the machine wakes (2.5 seconds after it, while the outputs
are found one after another) or the screen is unlocked (0.6 seconds after it,
once the lock screen has gone), the monitor reconciliator gets a Wake and calls
wake_up: it reconciles the monitors as for an unplug, reads their sizes, follows
the windows to the monitors they are on and tiles every monitor, unless the
window manager is paused. Going to sleep and locking do nothing, and a machine
with no system bus or a session with no lock screen runs without them. The lock
screen is a window of KWin's that the bridge already does not report as an
application window, so it has no tile.

The bridge also compares KWin's active window with the one it last announced
once a second, because the window that is active again after an unlock is not
always announced. vm-lock-sleep locks and unlocks a real Plasma session and
checks that the windows come back to their tiles; a real suspend cannot be
tested in the QEMU guest, only the signal wiring, which tests/power.rs covers on
private buses.

vm-lock-sleep waits for the panel's room before it opens the windows, so that
they are tiled once, and compares the window that was moved with the tile the
daemon has for it when it looks, give or take a cell of the terminal's font, and
not with the frames read earlier: the room can come while the screen is locked,
and the tiles read before are then not the ones. The wait is not a check,
because a session on a machine as slow as TCG may never take the room.
2026-10-28 07:20:57 -07:00

2.4 KiB

Sleeping and locking

komorebi looks at the desktop again when the machine wakes up and when the screen is unlocked. There is nothing to configure and no command to run.

Why

While the screen is locked or the machine is asleep, KWin sends its clients no frame callbacks, so the windows do not draw and nothing komorebi asked for in that time is done: a window moved by something else stays where it was moved, and a window that was asked to move does not. The monitors can come back in another order, or at another size, or not all of them. A window that is where komorebi did not put it is not in its tile.

What komorebi does

  • The screen is unlocked. The lock screen is a window of KWin's, on every desktop and in no task list, and komorebi does not manage windows like that: it has no tile, and nothing is moved about while the screen is locked. Locking the screen does nothing. A moment after it is unlocked (0.6 seconds: the lock screen goes before the windows can be seen), komorebi looks at the desktop.
  • The machine wakes up. komorebi hears it from logind (PrepareForSleep, which is false when the machine is awake). Going to sleep does nothing. A moment after it wakes (2.5 seconds: the outputs are found again one after another, and the compositor moves windows about as they are), komorebi looks at the desktop.

Looking at the desktop is the same for both. komorebi reads the monitors again, as when one is unplugged or plugged in (Changing monitors), reads the size and work area of every monitor, finds every window that is on another monitor than the one it has it on, and tiles every monitor. Nothing is done while komorebi is paused (komorebic toggle-pause).

The bridge compares the window KWin has active with the one it last told komorebi about once a second, because the window that is active again after an unlock is not always announced, and komorebi's idea of the focus follows KWin's.

What is not tested

A real suspend and a real resume are not tested: the virtual machines the tests run in have no way to wake from one. The signals komorebi waits for are tested on private buses, and the lock screen against a real KWin.

Following it from a program

A subscriber is sent a notification, whose event is "Wake", when komorebi has looked at the desktop after a wake or an unlock.