Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
WindowPlacement.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
9
10#include <QHash>
11#include <QJsonArray>
12#include <QJsonObject>
13#include <QLatin1String>
14#include <QRect>
15#include <QString>
16#include <QStringList>
17
18#include <utility>
19
20namespace PhosphorEngine {
21
27inline constexpr int MAX_PLAUSIBLE_VIRTUAL_DESKTOP = 1024;
28
41{
42 QString state;
43 QStringList zoneIds;
44 int order = -1;
63 QHash<int, QStringList> zonesByDesktop;
64
65 bool operator==(const EngineSlot& o) const
66 {
67 return state == o.state && zoneIds == o.zoneIds && order == o.order && zonesByDesktop == o.zonesByDesktop;
68 }
69 bool operator!=(const EngineSlot& o) const
70 {
71 return !(*this == o);
72 }
73 bool isEmpty() const
74 {
75 return state.isEmpty();
76 }
77};
78
96{
97 // ── Identity (the two store keys) ──
98 QString windowId;
99 QString appId;
100
101 // ── Context (the universal restore + disabled-context gate) ──
102 QString screenId;
113 QString activity;
115
116 // ── Per-engine managed state, keyed by engineId() ──
117 QHash<QString, EngineSlot> engines;
118
119 // ── Shared free/float geometry, keyed by screenId ──
120 QHash<QString, QRect> freeGeometryByScreen;
121
122 // ── Recency (most-recent-wins ordering; stamped by the store) ──
123 quint64 sequence = 0;
124
125 // ── Retired reclaim credit (INERT, kept for ABI layout) ──
132 bool reclaimEligible = true;
134 qint64 closedAtMsecs = 0;
135
136 bool isValid() const
137 {
138 return !windowId.isEmpty() && !appId.isEmpty();
139 }
140
143 EngineSlot slotFor(const QString& engineId) const
144 {
145 return engines.value(engineId);
146 }
147
166 QRect freeGeometryFor(const QString& screenId) const
167 {
168 const auto exact = freeGeometryByScreen.constFind(screenId);
169 if (exact != freeGeometryByScreen.constEnd() && exact.value().isValid()) {
170 return exact.value();
171 }
172 if (screenId.isEmpty()) {
173 return {};
174 }
175 // Deterministic among siblings: QHash iteration order is unspecified,
176 // so without a total order the answer would differ run to run. Same
177 // lexicographic-smallest rule anyFreeGeometryScreenId uses.
178 QString bestKey;
179 QRect best;
180 for (auto it = freeGeometryByScreen.constBegin(); it != freeGeometryByScreen.constEnd(); ++it) {
181 if (!it.value().isValid() || !PhosphorIdentity::VirtualScreenId::samePhysical(it.key(), screenId)) {
182 continue;
183 }
184 if (bestKey.isEmpty() || it.key() < bestKey) {
185 bestKey = it.key();
186 best = it.value();
187 }
188 }
189 return best;
190 }
191
198 {
199 QString best;
200 for (auto it = freeGeometryByScreen.constBegin(); it != freeGeometryByScreen.constEnd(); ++it) {
201 if (it.value().isValid() && (best.isEmpty() || it.key() < best)) {
202 best = it.key();
203 }
204 }
205 return best;
206 }
207
212 QRect anyFreeGeometry() const
213 {
215 }
216
233 {
234 if (anyFreeGeometry().isValid()) {
235 return true;
236 }
237 for (auto it = engines.constBegin(); it != engines.constEnd(); ++it) {
238 const EngineSlot& s = it.value();
239 if (s.state == stateSnapped() || s.state == stateTiled()) {
240 return true;
241 }
242 if (!s.zoneIds.isEmpty() || s.order >= 0 || !s.zonesByDesktop.isEmpty()) {
243 return true;
244 }
245 }
246 return false;
247 }
248
255 bool sameContentAs(const WindowPlacement& o) const
256 {
257 return windowId == o.windowId && appId == o.appId && screenId == o.screenId
258 && virtualDesktop == o.virtualDesktop && activity == o.activity && kind == o.kind && engines == o.engines
260 }
261
267 static QLatin1String snapEngineId()
268 {
269 return QLatin1String("snap");
270 }
271 static QLatin1String autotileEngineId()
272 {
273 return QLatin1String("autotile");
274 }
275 static QLatin1String scrollingEngineId()
276 {
277 return QLatin1String("scrolling");
278 }
279
287 static QLatin1String stateFree()
288 {
289 return QLatin1String("free");
290 }
291 static QLatin1String stateFloating()
292 {
293 return QLatin1String("floating");
294 }
295 static QLatin1String stateSnapped()
296 {
297 return QLatin1String("snapped");
298 }
299 static QLatin1String stateTiled()
300 {
301 return QLatin1String("tiled");
302 }
303
314 static QLatin1String stateReleased()
315 {
316 return QLatin1String("released");
317 }
318
319 QJsonObject toJson() const
320 {
321 QJsonObject obj;
322 obj[QLatin1String("windowId")] = windowId;
323 obj[QLatin1String("screen")] = screenId;
324 obj[QLatin1String("desktop")] = virtualDesktop;
325 if (!activity.isEmpty()) {
326 obj[QLatin1String("activity")] = activity;
327 }
328 obj[QLatin1String("kind")] = static_cast<int>(kind);
329
330 QJsonObject eng;
331 for (auto it = engines.constBegin(); it != engines.constEnd(); ++it) {
332 const EngineSlot& s = it.value();
333 if (s.isEmpty()) {
334 continue;
335 }
336 QJsonObject so;
337 so[QLatin1String("state")] = s.state;
338 if (!s.zoneIds.isEmpty()) {
339 QJsonArray z;
340 for (const QString& id : s.zoneIds) {
341 z.append(id);
342 }
343 so[QLatin1String("zoneIds")] = z;
344 }
345 if (s.order >= 0) {
346 so[QLatin1String("order")] = s.order;
347 }
348 if (!s.zonesByDesktop.isEmpty()) {
349 // Desktop number as the key, stringified because JSON objects
350 // take no integer keys. Only written when the window actually
351 // spans desktops, so an ordinary record is byte-identical to
352 // what it was before this field existed.
353 QJsonObject byDesktop;
354 for (auto d = s.zonesByDesktop.constBegin(); d != s.zonesByDesktop.constEnd(); ++d) {
355 if (d.value().isEmpty()) {
356 continue;
357 }
358 QJsonArray dz;
359 for (const QString& id : d.value()) {
360 dz.append(id);
361 }
362 byDesktop[QString::number(d.key())] = dz;
363 }
364 if (!byDesktop.isEmpty()) {
365 so[QLatin1String("zonesByDesktop")] = byDesktop;
366 }
367 }
368 eng[it.key()] = so;
369 }
370 if (!eng.isEmpty()) {
371 obj[QLatin1String("engines")] = eng;
372 }
373
374 QJsonObject fg;
375 for (auto it = freeGeometryByScreen.constBegin(); it != freeGeometryByScreen.constEnd(); ++it) {
376 const QRect& g = it.value();
377 if (!g.isValid()) {
378 continue;
379 }
380 QJsonObject go;
381 go[QLatin1String("x")] = g.x();
382 go[QLatin1String("y")] = g.y();
383 go[QLatin1String("w")] = g.width();
384 go[QLatin1String("h")] = g.height();
385 fg[it.key()] = go;
386 }
387 if (!fg.isEmpty()) {
388 obj[QLatin1String("freeGeo")] = fg;
389 }
390
391 obj[QLatin1String("seq")] = static_cast<double>(sequence);
392 obj[QLatin1String("liveAtSave")] = reclaimEligible;
393 return obj;
394 }
395
396 static WindowPlacement fromJson(const QString& appId, const QJsonObject& obj)
397 {
399 p.appId = appId;
400 p.windowId = obj.value(QLatin1String("windowId")).toString();
401 p.screenId = obj.value(QLatin1String("screen")).toString();
402 // session.json is on-disk input this process does not control, so the
403 // desktop number is range-checked here rather than trusted all the way
404 // to the compositor. Anything outside a plausible desktop count is
405 // treated as unknown (0), which reads as "no remembered desktop" and
406 // leaves the window wherever it opens — the same outcome as a record
407 // that never carried one.
408 const int rawDesktop = obj.value(QLatin1String("desktop")).toInt();
409 p.virtualDesktop = (rawDesktop > 0 && rawDesktop <= MAX_PLAUSIBLE_VIRTUAL_DESKTOP) ? rawDesktop : 0;
410 p.activity = obj.value(QLatin1String("activity")).toString();
411 p.kind = clampWindowKindFromWire(obj.value(QLatin1String("kind")).toInt());
412
413 const QJsonObject eng = obj.value(QLatin1String("engines")).toObject();
414 for (auto it = eng.constBegin(); it != eng.constEnd(); ++it) {
415 const QJsonObject so = it.value().toObject();
416 EngineSlot s;
417 s.state = so.value(QLatin1String("state")).toString();
418 for (const QJsonValue& v : so.value(QLatin1String("zoneIds")).toArray()) {
419 const QString z = v.toString();
420 if (!z.isEmpty()) {
421 s.zoneIds.append(z);
422 }
423 }
424 s.order = so.value(QLatin1String("order")).toInt(-1);
425 const QJsonObject byDesktop = so.value(QLatin1String("zonesByDesktop")).toObject();
426 for (auto d = byDesktop.constBegin(); d != byDesktop.constEnd(); ++d) {
427 bool ok = false;
428 const int desktop = d.key().toInt(&ok);
429 // Desktop numbers are 1-based and bounded the same way the
430 // record-level desktop above is; a key outside that range is a
431 // corrupt or hand-edited file and is dropped rather than
432 // resurrected as desktop 0, which no context resolves to, or
433 // as a number that would mint a per-desktop store nothing
434 // else ever prunes.
435 if (!ok || desktop < 1 || desktop > MAX_PLAUSIBLE_VIRTUAL_DESKTOP) {
436 continue;
437 }
438 QStringList zones;
439 for (const QJsonValue& v : d.value().toArray()) {
440 const QString z = v.toString();
441 if (!z.isEmpty()) {
442 zones.append(z);
443 }
444 }
445 if (!zones.isEmpty()) {
446 s.zonesByDesktop.insert(desktop, zones);
447 }
448 }
449 if (!s.isEmpty()) {
450 p.engines.insert(it.key(), s);
451 }
452 }
453
454 const QJsonObject fg = obj.value(QLatin1String("freeGeo")).toObject();
455 for (auto it = fg.constBegin(); it != fg.constEnd(); ++it) {
456 const QJsonObject go = it.value().toObject();
457 const QRect g(go.value(QLatin1String("x")).toInt(), go.value(QLatin1String("y")).toInt(),
458 go.value(QLatin1String("w")).toInt(), go.value(QLatin1String("h")).toInt());
459 if (g.isValid()) {
460 p.freeGeometryByScreen.insert(it.key(), g);
461 }
462 }
463
464 p.sequence = static_cast<quint64>(obj.value(QLatin1String("seq")).toDouble());
465 // Inert field, read back only so it round-trips (see its declaration).
466 p.reclaimEligible = obj.value(QLatin1String("liveAtSave")).toBool(true);
467 return p;
468 }
469};
470
506
515inline bool hasStableAppIdFor(const QString& appId, const QString& windowId)
516{
517 return !appId.isEmpty() && appId != windowId;
518}
519
535inline bool recordContextMatchesLive(const WindowPlacement& p, int liveDesktop, const QString& liveActivity)
536{
537 if (p.virtualDesktop != 0 && liveDesktop != 0 && p.virtualDesktop != liveDesktop) {
538 return false;
539 }
540 return p.activity.isEmpty() || liveActivity.isEmpty() || p.activity == liveActivity;
541}
542
543template<typename IsEngineMode>
544bool pendingCrossScreenManagedRestore(const WindowPlacement& p, QLatin1String engineId, QLatin1String managedState,
545 const QString& openingScreenId, IsEngineMode&& isEngineMode)
546{
547 if (p.slotFor(engineId).state != managedState) {
548 return false;
549 }
550 if (p.screenId.isEmpty() || p.screenId == openingScreenId) {
551 return false; // same screen (or unscreened): the opening context's engine owns it
552 }
553 return isEngineMode(p.screenId, p.virtualDesktop, p.activity);
554}
555
559template<typename IsSnappingMode>
560bool pendingCrossScreenSnapRestore(const WindowPlacement& p, const QString& openingScreenId,
561 IsSnappingMode&& isSnappingMode)
562{
564 openingScreenId, std::forward<IsSnappingMode>(isSnappingMode));
565}
566
576template<typename IsEngineMode>
577bool pendingCrossScreenManagedRestore(const WindowPlacement& p, QLatin1String engineId, QLatin1String managedState,
578 const QString& openingWindowId, const QString& openingScreenId,
579 IsEngineMode&& isEngineMode)
580{
582 return false;
583 }
585 return false;
586 }
587 return pendingCrossScreenManagedRestore(p, engineId, managedState, openingScreenId,
588 std::forward<IsEngineMode>(isEngineMode));
589}
590
592template<typename IsSnappingMode>
593bool pendingCrossScreenSnapRestore(const WindowPlacement& p, const QString& openingWindowId,
594 const QString& openingScreenId, IsSnappingMode&& isSnappingMode)
595{
597 openingWindowId, openingScreenId,
598 std::forward<IsSnappingMode>(isSnappingMode));
599}
600
607inline bool ownRecordLeftScreen(const WindowPlacement& own, const QString& openingScreenId)
608{
609 if (own.screenId.isEmpty() || openingScreenId.isEmpty() || own.screenId == openingScreenId) {
610 return false;
611 }
612 for (auto it = own.engines.constBegin(); it != own.engines.constEnd(); ++it) {
613 if (!it.value().state.isEmpty() && it.value().state != WindowPlacement::stateReleased()) {
614 return true;
615 }
616 }
617 return false;
618}
619
620} // namespace PhosphorEngine
Definition DesktopRemap.h:12
bool pendingCrossScreenSnapRestore(const WindowPlacement &p, const QString &openingScreenId, IsSnappingMode &&isSnappingMode)
The snap-engine specialization of the 5-argument form.
Definition WindowPlacement.h:560
constexpr int MAX_PLAUSIBLE_VIRTUAL_DESKTOP
Upper sanity bound for a virtual desktop number read back from disk.
Definition WindowPlacement.h:27
bool recordContextMatchesLive(const WindowPlacement &p, int liveDesktop, const QString &liveActivity)
Whether a record's own (desktop, activity) context is compatible with the live context an engine woul...
Definition WindowPlacement.h:535
WindowKind clampWindowKindFromWire(int wire)
Clamp an integer wire value to a valid WindowKind.
Definition EngineTypes.h:89
bool hasStableAppIdFor(const QString &appId, const QString &windowId)
The REOPEN CONTRACT, which the predicates below implement: a window is restored only on the KWin outp...
Definition WindowPlacement.h:515
WindowKind
Coarse structural classification of a window, carried on the open and close wire calls and on the pla...
Definition EngineTypes.h:77
@ Unknown
Definition EngineTypes.h:78
bool pendingCrossScreenManagedRestore(const WindowPlacement &p, QLatin1String engineId, QLatin1String managedState, const QString &openingScreenId, IsEngineMode &&isEngineMode)
Definition WindowPlacement.h:544
bool ownRecordLeftScreen(const WindowPlacement &own, const QString &openingScreenId)
Whether a window's OWN record names a different screen than the one it is opening on while some engin...
Definition WindowPlacement.h:607
bool samePhysical(const QString &idA, const QString &idB)
Check if two screen IDs share the same physical screen.
Definition VirtualScreenId.h:70
bool sameWindowInstance(const QString &lhs, const QString &rhs)
Do two window ids name the same live window instance?
Definition WindowId.h:97
One engine's view of a window: which managed slot it occupies (or that it is floating / unmanaged) in...
Definition WindowPlacement.h:41
QHash< int, QStringList > zonesByDesktop
Snap slot — the zones this window occupies on EACH desktop it is present on, keyed by x11 desktop num...
Definition WindowPlacement.h:63
bool isEmpty() const
Definition WindowPlacement.h:73
int order
autotile slot — tile index within the screen; -1 for snap
Definition WindowPlacement.h:44
bool operator==(const EngineSlot &o) const
Definition WindowPlacement.h:65
bool operator!=(const EngineSlot &o) const
Definition WindowPlacement.h:69
QStringList zoneIds
snap slot — zone UUIDs (first is primary); empty for autotile
Definition WindowPlacement.h:43
QString state
engine-defined token: snap "snapped"/"floating"; autotile "tiled"/"floating" ("free" retired)
Definition WindowPlacement.h:42
One window's single, authoritative placement record — the unit of the unified, engine-agnostic restor...
Definition WindowPlacement.h:96
EngineSlot slotFor(const QString &engineId) const
The slot for engineId, or a default (empty) slot if this engine has no recorded state for the window.
Definition WindowPlacement.h:143
static QLatin1String snapEngineId()
Built-in engine-slot ids.
Definition WindowPlacement.h:267
static QLatin1String stateFree()
Common state-token vocabulary.
Definition WindowPlacement.h:287
QRect freeGeometryFor(const QString &screenId) const
The shared free/float geometry for screenId, or an invalid rect if none has been captured on that scr...
Definition WindowPlacement.h:166
static QLatin1String autotileEngineId()
Definition WindowPlacement.h:271
static QLatin1String scrollingEngineId()
Definition WindowPlacement.h:275
WindowKind kind
Definition WindowPlacement.h:114
bool isValid() const
Definition WindowPlacement.h:136
static QLatin1String stateTiled()
Definition WindowPlacement.h:299
bool sameContentAs(const WindowPlacement &o) const
Content equality IGNORING sequence (the store stamps a fresh sequence on every record(),...
Definition WindowPlacement.h:255
static QLatin1String stateReleased()
An engine that KNOWINGLY GAVE THE WINDOW UP (a cross-mode handoff) leaves this instead of its managed...
Definition WindowPlacement.h:314
int virtualDesktop
0 = all-desktops / sticky / unknown.
Definition WindowPlacement.h:112
QString activity
empty = all-activities / unknown
Definition WindowPlacement.h:113
static QLatin1String stateFloating()
Definition WindowPlacement.h:291
QRect anyFreeGeometry() const
Any captured free/float geometry (the deterministic pick of anyFreeGeometryScreenId()),...
Definition WindowPlacement.h:212
QJsonObject toJson() const
Definition WindowPlacement.h:319
QString anyFreeGeometryScreenId() const
The screenId of the deterministic cross-screen fallback pick: the lexicographically-smallest screenId...
Definition WindowPlacement.h:197
qint64 closedAtMsecs
INERT, kept for ABI layout. Never stamped or read.
Definition WindowPlacement.h:134
static QLatin1String stateSnapped()
Definition WindowPlacement.h:295
static WindowPlacement fromJson(const QString &appId, const QJsonObject &obj)
Definition WindowPlacement.h:396
QString screenId
last managed-context screen
Definition WindowPlacement.h:102
quint64 sequence
Definition WindowPlacement.h:123
QHash< QString, EngineSlot > engines
Definition WindowPlacement.h:117
bool reclaimEligible
The cross-screen reclaim's credit, retired with the reclaim: a window is now restored only on the out...
Definition WindowPlacement.h:132
QString appId
window class; FIFO key for close/reopen (uuid changes)
Definition WindowPlacement.h:99
QHash< QString, QRect > freeGeometryByScreen
Definition WindowPlacement.h:120
QString windowId
full appId|uuid; exact key for daemon-restart (uuid stable)
Definition WindowPlacement.h:98
bool hasRestorableContent() const
Whether this record carries anything worth restoring.
Definition WindowPlacement.h:232