Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
WindowPlacementStore.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
7#include "phosphorengine_export.h"
8
9#include <QHash>
10#include <QJsonObject>
11#include <QList>
12#include <QPoint>
13#include <QSet>
14#include <QString>
15
16#include <functional>
17#include <optional>
18
19namespace PhosphorEngine {
20
21class DesktopRemap;
22
37class PHOSPHORENGINE_EXPORT WindowPlacementStore
38{
39public:
41
53 bool record(WindowPlacement placement);
54
75 std::optional<WindowPlacement> take(const QString& windowId, const QString& appId,
76 const std::function<bool(const WindowPlacement&)>& accept = {},
77 const std::function<bool(const WindowPlacement&)>& preferred = {});
78
101 std::optional<WindowPlacement>
102 peekLiveSibling(const QString& windowId, const QString& appId,
103 const std::function<bool(const WindowPlacement&)>& accept = {}) const;
104
154 std::optional<WindowPlacement> takeForReopen(const QString& engineId, const QString& windowId, const QString& appId,
155 const QString& screenId);
156
168 std::optional<WindowPlacement> peek(const QString& windowId, const QString& appId,
169 const std::function<bool(const WindowPlacement&)>& accept = {},
170 bool excludeLiveSiblings = false) const;
171
176 std::optional<WindowPlacement> peekExact(const QString& windowId) const
177 {
178 return peek(windowId, QString());
179 }
180
199 std::optional<WindowPlacement> peekForReclaim(const QString& windowId, const QString& appId,
200 const std::function<bool(const WindowPlacement&)>& accept = {}) const;
201
204 bool contains(const QString& windowId, const QString& appId = QString()) const;
205
210 bool markInstanceClosed(const QString& windowId, bool graceEligible = true);
211
214 void markInstanceMovedLive(const QString& windowId);
215
218 bool burnReclaimCredit(const QString& windowId, const QString& appId);
219
247 std::optional<WindowPlacement> claimForOpen(const QString& windowId, const QString& appId);
248
256 void releaseOpenClaim(const QString& windowId);
257
267 std::optional<WindowPlacement> claimForOpen(const QString& windowId, const QString& appId,
268 const QString& openingScreenId,
269 const std::function<bool(const WindowPlacement&)>& restorableHere);
270
275 int releaseOpenClaimsExcept(const QSet<QString>& aliveInstanceIds);
276
282 void setLiveInstanceProbe(std::function<bool(const QString& windowId)> probe)
283 {
284 m_liveInstanceProbe = std::move(probe);
285 }
286
292 bool isLiveInstance(const QString& windowId) const
293 {
294 return m_liveInstanceProbe && m_liveInstanceProbe(windowId);
295 }
296
325 bool collapsePureFloatSiblings(const QString& appId, const QString& keepWindowId);
326
329 bool clear(const QString& windowId);
330
336 bool clearFreeGeometry(const QString& windowId);
337 bool clearFreeGeometry(const QString& windowId, const QString& screenId);
338
369 bool releaseEngineSlot(const QString& windowId, const QString& engineId);
370
378 bool forgetDesktopZones(const QString& windowId, const QString& engineId, int desktop);
379
388 int renumberDesktopZones(int removedDesktop);
402 int remapRestoredDesktopZones(const DesktopRemap& remap, quint64 restoredUpTo);
405 quint64 sequence() const
406 {
407 return m_sequence;
408 }
409
414 int transform(const std::function<bool(WindowPlacement&)>& fn);
415
417 int removeIf(const std::function<bool(const WindowPlacement&)>& pred);
418
421 QList<WindowPlacement> records() const;
422
428 QJsonObject serialize(const std::function<bool(const WindowPlacement&)>& keep = {}) const;
429 void deserialize(const QJsonObject& obj);
430
434 using OutputOrigin = std::function<std::optional<QPoint>(const QString& screenId)>;
440 QJsonObject serialize(const std::function<bool(const WindowPlacement&)>& keep, const OutputOrigin& originFor) const;
441 void deserialize(const QJsonObject& obj, const OutputOrigin& originFor);
442
443 int size() const;
444
445private:
449 void evictForCapacity(QList<WindowPlacement>& bucket);
450
458 bool pairingAllows(const QString& windowId, const WindowPlacement& candidate) const;
459
463 void dropClaimsNaming(const QString& recordWindowId);
466 void forgetRemovedRecord(const QString& recordWindowId);
467
478 bool boundToLiveOther(const QString& askingWindowId, const WindowPlacement& p) const;
479
480public:
482 static constexpr int MaxPerApp = 16;
483
486 static constexpr qint64 ShutdownCloseGraceMs = 30000;
487
490 static constexpr int FormatVersion = 2;
493 static int formatVersionOf(const QJsonObject& stored);
494
495private:
502 QHash<QString, QList<WindowPlacement>> m_byApp;
503 quint64 m_sequence = 0;
504 std::function<bool(const QString&)> m_liveInstanceProbe;
505
519 QHash<QString, QString> m_openPairing;
520 QHash<QString, QString> m_claimedBy;
521
530 QSet<QString> m_touchedThisSession;
531
537 std::optional<WindowPlacement> claimForOpenImpl(const QString& windowId, const QString& appId, bool ownRecordFinal,
538 const QString& openingScreenId,
539 const std::function<bool(const WindowPlacement&)>& restorableHere);
540};
541
542} // namespace PhosphorEngine
How KWin's desktop positions moved in one change of its desktop list: for each 1-based position in th...
Definition DesktopRemap.h:29
void deserialize(const QJsonObject &obj, const OutputOrigin &originFor)
bool clear(const QString &windowId)
Drop any record for the same live instance (and prune the empty bucket).
bool collapsePureFloatSiblings(const QString &appId, const QString &keepWindowId)
Collapse stale pure-float duplicates for an app, keeping keepWindowId.
std::optional< WindowPlacement > claimForOpen(const QString &windowId, const QString &appId, const QString &openingScreenId, const std::function< bool(const WindowPlacement &)> &restorableHere)
The reopen-contract claim: claimForOpen restricted to what the opening screen can restore.
std::function< std::optional< QPoint >(const QString &screenId)> OutputOrigin
The top-left of the output a free-geometry key (a screen id, virtual or not) lies on,...
Definition WindowPlacementStore.h:434
int releaseOpenClaimsExcept(const QSet< QString > &aliveInstanceIds)
Drop every open claim whose instance is not in aliveInstanceIds (instance ids, as PhosphorIdentity::W...
bool forgetDesktopZones(const QString &windowId, const QString &engineId, int desktop)
Drop one desktop's entry from an engine slot's zonesByDesktop map.
int remapRestoredDesktopZones(const DesktopRemap &remap, quint64 restoredUpTo)
remapDesktopZones for the start-up renumber that KWin's first desktop list brings when it lands after...
bool markInstanceClosed(const QString &windowId, bool graceEligible=true)
The window CLOSED: drop its open claim (releaseOpenClaim).
bool releaseEngineSlot(const QString &windowId, const QString &engineId)
DOWNGRADE one engine's slot to WindowPlacement::stateReleased() on every record for the same live ins...
std::optional< WindowPlacement > claimForOpen(const QString &windowId, const QString &appId)
Reserve, once per opening window instance, the record that instance owns.
std::optional< WindowPlacement > peekForReclaim(const QString &windowId, const QString &appId, const std::function< bool(const WindowPlacement &)> &accept={}) const
Non-consuming lookup for the tiling engines' reopen claim (IPlacementEngine::claimCrossScreenReopen),...
std::optional< WindowPlacement > peekExact(const QString &windowId) const
Same-instance peek: branch 1 of peek() only, never the appId-FIFO fallback.
Definition WindowPlacementStore.h:176
static constexpr qint64 ShutdownCloseGraceMs
INERT, kept for source compatibility: the shutdown-close grace serialize() once applied to the reclai...
Definition WindowPlacementStore.h:486
std::optional< WindowPlacement > takeForReopen(const QString &engineId, const QString &windowId, const QString &appId, const QString &screenId)
Reopen resolve: the shared consumption pattern the TILING engines' open-time restores use (SnapEngine...
static constexpr int MaxPerApp
Per-app record cap (public so tests can pin the eviction contract).
Definition WindowPlacementStore.h:482
bool contains(const QString &windowId, const QString &appId=QString()) const
True if a record exists for the same live instance, or (if appId non-empty) any record in that appId ...
void markInstanceMovedLive(const QString &windowId)
INERT, kept for ABI.
QJsonObject serialize(const std::function< bool(const WindowPlacement &)> &keep, const OutputOrigin &originFor) const
The on-disk form keeps each float-back RELATIVE to its output, so a spot survives a rearrangement of ...
void setLiveInstanceProbe(std::function< bool(const QString &windowId)> probe)
Inject the live-window probe behind every live-sibling exclusion in the store (take,...
Definition WindowPlacementStore.h:282
int renumberDesktopZones(int removedDesktop)
Drop removedDesktop from every slot's zonesByDesktop map and shift the entries above it down by one,...
int transform(const std::function< bool(WindowPlacement &)> &fn)
Apply an in-place mutation to every record; fn returns true when it changed the record.
quint64 sequence() const
The stamp of the newest record.
Definition WindowPlacementStore.h:405
int removeIf(const std::function< bool(const WindowPlacement &)> &pred)
Remove every record matching pred. Returns the count removed.
static int formatVersionOf(const QJsonObject &stored)
The version stored was written in (1 when unstamped).
void releaseOpenClaim(const QString &windowId)
Drop windowId's open claim, so a claim never outlives the instance that made it.
std::optional< WindowPlacement > peek(const QString &windowId, const QString &appId, const std::function< bool(const WindowPlacement &)> &accept={}, bool excludeLiveSiblings=false) const
Non-consuming lookup (unlike take): the record for the same live instance, else the NEWEST record in ...
QList< WindowPlacement > records() const
All records, in no particular order.
static constexpr int FormatVersion
The serialized format's version, stamped as "_version".
Definition WindowPlacementStore.h:490
std::optional< WindowPlacement > take(const QString &windowId, const QString &appId, const std::function< bool(const WindowPlacement &)> &accept={}, const std::function< bool(const WindowPlacement &)> &preferred={})
Restore lookup: the first record whose accept predicate passes, trying the same-instance match before...
std::optional< WindowPlacement > peekLiveSibling(const QString &windowId, const QString &appId, const std::function< bool(const WindowPlacement &)> &accept={}) const
The EARLIEST-RECORDED record in appId's bucket that is bound to a live window OTHER than windowId's i...
bool clearFreeGeometry(const QString &windowId)
Clear ONLY the shared free/float geometry for the same live instance, leaving the engine slots and co...
QJsonObject serialize(const std::function< bool(const WindowPlacement &)> &keep={}) const
JSON shape: { "_version": FormatVersion, appId: [ record, ... ] }.
bool isLiveInstance(const QString &windowId) const
Whether the probe reports windowId's instance as a still-open window.
Definition WindowPlacementStore.h:292
int remapDesktopZones(const DesktopRemap &remap)
Move every slot's zonesByDesktop entries and the record-level desktop through remap,...
void deserialize(const QJsonObject &obj)
bool burnReclaimCredit(const QString &windowId, const QString &appId)
INERT, kept for ABI.
bool clearFreeGeometry(const QString &windowId, const QString &screenId)
bool record(WindowPlacement placement)
Record / MERGE this window's placement.
Definition DesktopRemap.h:12
One window's single, authoritative placement record — the unit of the unified, engine-agnostic restor...
Definition WindowPlacement.h:96