Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IWindowTrackingService.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#include "phosphorengine_export.h"
10
11#include <QHash>
12#include <QList>
13#include <QRect>
14#include <QSet>
15#include <QString>
16#include <QStringList>
17#include <QUuid>
18#include <QVector>
19
20#include <optional>
21
22class QObject;
23
24namespace PhosphorZones {
25class Layout;
26}
27
28namespace PhosphorScreens {
29class ScreenManager;
30}
31
32namespace PhosphorEngine {
33
34class PHOSPHORENGINE_EXPORT IWindowTrackingService
35{
36public:
37 virtual ~IWindowTrackingService() = default;
38
39 virtual QObject* asQObject() = 0;
40
41 // ═══════════════════════════════════════════════════════════════════════════
42 // Screen manager access
43 // Tech debt: returns concrete ScreenManager* — should be an IScreenManager
44 // interface once one exists. Acceptable as a stepping stone; the
45 // IScreenManager extraction is tracked separately.
46 // ═══════════════════════════════════════════════════════════════════════════
47
49
54 virtual QRect screenAvailableGeometry(const QString& screenId) const = 0;
55
56 // ═══════════════════════════════════════════════════════════════════════════
57 // Zone assignment management
58 // ═══════════════════════════════════════════════════════════════════════════
59
60 virtual void assignWindowToZone(const QString& windowId, const QString& zoneId, const QString& screenId,
61 int virtualDesktop) = 0;
62 virtual void assignWindowToZones(const QString& windowId, const QStringList& zoneIds, const QString& screenId,
63 int virtualDesktop) = 0;
64 virtual void unassignWindow(const QString& windowId) = 0;
65
73 virtual QStringList recordedSnapZones(const QString& windowId) const = 0;
74
75 virtual QString zoneForWindow(const QString& windowId) const = 0;
76 virtual QStringList zonesForWindow(const QString& windowId) const = 0;
82 virtual QString screenForWindow(const QString& windowId) const = 0;
84 virtual QString screenForWindow(const QString& windowId, const QString& defaultScreen) const = 0;
85 virtual QStringList windowsInZone(const QString& zoneId) const = 0;
86 virtual bool isWindowSnapped(const QString& windowId) const = 0;
87 virtual QString findEmptyZone(const QString& screenId = QString()) const = 0;
88
89 // ═══════════════════════════════════════════════════════════════════════════
90 // Auto-snap
91 // ═══════════════════════════════════════════════════════════════════════════
92
93 virtual void recordSnapIntent(const QString& windowId, bool wasUserInitiated) = 0;
94
95 // ═══════════════════════════════════════════════════════════════════════════
96 // Floating state
97 // ═══════════════════════════════════════════════════════════════════════════
98
99 virtual bool isWindowFloating(const QString& windowId) const = 0;
105 virtual bool isSuspensionFloat(const QString& windowId) const
106 {
107 Q_UNUSED(windowId)
108 return false;
109 }
110
116 virtual void clearSuspensionFloat(const QString& windowId)
117 {
118 Q_UNUSED(windowId)
119 }
120 virtual void setWindowFloating(const QString& windowId, bool floating) = 0;
121 virtual void unsnapForFloat(const QString& windowId) = 0;
122 virtual bool clearFloatingForSnap(const QString& windowId) = 0;
123
124 // ═══════════════════════════════════════════════════════════════════════════
125 // Sticky state
126 // ═══════════════════════════════════════════════════════════════════════════
127
128 virtual bool isWindowSticky(const QString& windowId) const = 0;
129
130 // ═══════════════════════════════════════════════════════════════════════════
131 // Pre-float zone/screen restore
132 // ═══════════════════════════════════════════════════════════════════════════
133
134 virtual QStringList preFloatZones(const QString& windowId) const = 0;
135 virtual QString preFloatScreen(const QString& windowId) const = 0;
140 virtual void clearPreFloatZone(const QString& windowId) = 0;
141
142 // ═══════════════════════════════════════════════════════════════════════════
143 // Auto-snap
144 // ═══════════════════════════════════════════════════════════════════════════
145
146 virtual bool clearAutoSnapped(const QString& windowId) = 0;
147
148 // ═══════════════════════════════════════════════════════════════════════════
149 // Last-used zone tracking
150 // ═══════════════════════════════════════════════════════════════════════════
151
152 virtual void updateLastUsedZone(const QString& zoneId, const QString& screenId, const QString& windowClass,
153 int virtualDesktop) = 0;
154
155 // ═══════════════════════════════════════════════════════════════════════════
156 // App identity
157 // ═══════════════════════════════════════════════════════════════════════════
158
159 virtual QString currentAppIdFor(const QString& anyWindowId) const = 0;
160
161 // ═══════════════════════════════════════════════════════════════════════════
162 // Geometry resolution
163 // ═══════════════════════════════════════════════════════════════════════════
164
194 virtual std::optional<QRect> validatedUnmanagedGeometry(const QString& windowId, const QString& screenId) const = 0;
195
213 virtual bool geometryBelongsToScreen(const QRect& geometry, const QString& screenId) const = 0;
214
221 virtual void recordFreeGeometry(const QString& windowId, const QString& screenId, const QRect& geometry,
222 bool overwrite) = 0;
223
227 virtual void clearFreeGeometry(const QString& windowId) = 0;
228
236 virtual void releaseEngineSlot(const QString& windowId, const QString& engineId)
237 {
238 Q_UNUSED(windowId)
239 Q_UNUSED(engineId)
240 }
241
248 virtual void forgetDesktopZones(const QString& windowId, const QString& engineId, int desktop)
249 {
250 Q_UNUSED(windowId)
251 Q_UNUSED(engineId)
252 Q_UNUSED(desktop)
253 }
254
259 virtual void renumberDesktopZones(int removedDesktop)
260 {
261 Q_UNUSED(removedDesktop)
262 }
263
267 virtual void clearFreeGeometry(const QString& windowId, const QString& screenId)
268 {
269 Q_UNUSED(screenId)
270 clearFreeGeometry(windowId);
271 }
272
276 virtual QRect zoneGeometry(const QString& zoneId, const QString& screenId) const = 0;
277 virtual QRect resolveZoneGeometry(const QStringList& zoneIds, const QString& screenId) const = 0;
278 virtual QString resolveEffectiveScreenId(const QString& screenId) const = 0;
279
283 // Tech debt: takes concrete Layout* — should take an opaque layout identifier
284 // once the layout interface is extracted. Acceptable for this extraction phase.
285 virtual QString findEmptyZoneInLayout(PhosphorZones::Layout* layout, const QString& screenId,
286 int desktopFilter = 0) const = 0;
287 virtual QSet<QUuid> buildOccupiedZoneSet(const QString& screenFilter = QString(), int desktopFilter = 0) const = 0;
288
289 // ═══════════════════════════════════════════════════════════════════════════
290 // Resnap buffer
291 // ═══════════════════════════════════════════════════════════════════════════
292
293 virtual QVector<ResnapEntry> takeResnapBuffer() = 0;
294
297 {
298 }
299
305 virtual void remapDesktopZones(const DesktopRemap& remap)
306 {
307 if (const int removed = remap.singleRemoval(); removed > 0) {
308 renumberDesktopZones(removed);
309 }
310 }
311};
312
313} // 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
int singleRemoval() const
The old position when this change is exactly one desktop removed with every other keeping its order,...
Definition IWindowTrackingService.h:35
virtual bool isSuspensionFloat(const QString &windowId) const
Whether the window's float is a MINIMIZE SUSPENSION rather than placement intent.
Definition IWindowTrackingService.h:105
virtual QStringList windowsInZone(const QString &zoneId) const =0
virtual QStringList preFloatZones(const QString &windowId) const =0
virtual bool geometryBelongsToScreen(const QRect &geometry, const QString &screenId) const =0
Does geometry plausibly belong to the coordinate space screenId names?
virtual std::optional< QRect > validatedUnmanagedGeometry(const QString &windowId, const QString &screenId) const =0
The window's remembered UNMANAGED (free/float-back) geometry, resolved FOR screenId,...
virtual QString resolveEffectiveScreenId(const QString &screenId) const =0
virtual bool clearFloatingForSnap(const QString &windowId)=0
virtual void recordFreeGeometry(const QString &windowId, const QString &screenId, const QRect &geometry, bool overwrite)=0
Record a window's SHARED free/float geometry (the placement record's freeGeometryByScreen),...
virtual void clearSuspensionFloat(const QString &windowId)
Drop the suspension classification.
Definition IWindowTrackingService.h:116
virtual QStringList recordedSnapZones(const QString &windowId) const =0
A window's recorded snap zone(s), preferring the LIVE assignment but falling back to the DURABLE plac...
virtual void updateLastUsedZone(const QString &zoneId, const QString &screenId, const QString &windowClass, int virtualDesktop)=0
virtual QString screenForWindow(const QString &windowId) const =0
The screen a window is assigned to (empty when none), canonicalizing the id so a window resolves acro...
virtual void remapDesktopZones(const DesktopRemap &remap)
renumberDesktopZones for any change of KWin's desktop list (F763): move every persisted per-desktop z...
Definition IWindowTrackingService.h:305
virtual void assignWindowToZones(const QString &windowId, const QStringList &zoneIds, const QString &screenId, int virtualDesktop)=0
virtual void releaseEngineSlot(const QString &windowId, const QString &engineId)
Downgrade engineId's slot on windowId's record to WindowPlacement::stateReleased() and mark the place...
Definition IWindowTrackingService.h:236
virtual QString screenForWindow(const QString &windowId, const QString &defaultScreen) const =0
Same, returning defaultScreen when the window has no assignment.
virtual QSet< QUuid > buildOccupiedZoneSet(const QString &screenFilter=QString(), int desktopFilter=0) const =0
virtual WindowPlacementStore & placementStore()=0
The unified, engine-agnostic placement store.
virtual void setWindowFloating(const QString &windowId, bool floating)=0
virtual QString findEmptyZone(const QString &screenId=QString()) const =0
virtual QString zoneForWindow(const QString &windowId) const =0
virtual QRect resolveZoneGeometry(const QStringList &zoneIds, const QString &screenId) const =0
virtual QString currentAppIdFor(const QString &anyWindowId) const =0
virtual bool isWindowFloating(const QString &windowId) const =0
virtual QRect screenAvailableGeometry(const QString &screenId) const =0
The area of screenId a window may occupy (the output minus panels and struts), or an invalid rect whe...
virtual void assignWindowToZone(const QString &windowId, const QString &zoneId, const QString &screenId, int virtualDesktop)=0
virtual QVector< ResnapEntry > takeResnapBuffer()=0
virtual bool isWindowSnapped(const QString &windowId) const =0
virtual bool isWindowSticky(const QString &windowId) const =0
virtual QStringList zonesForWindow(const QString &windowId) const =0
virtual void clearFreeGeometry(const QString &windowId)=0
Clear a window's shared free/float geometry (all screens) from the record, leaving its engine slots i...
virtual void unassignWindow(const QString &windowId)=0
virtual void renumberDesktopZones(int removedDesktop)
Apply a desktop removal to every persisted per-desktop zone map (drop removedDesktop,...
Definition IWindowTrackingService.h:259
virtual void unsnapForFloat(const QString &windowId)=0
virtual void clearFreeGeometry(const QString &windowId, const QString &screenId)
Screen-scoped consume-once variant: clears only screenId's remembered float-back, preserving other mo...
Definition IWindowTrackingService.h:267
virtual bool clearAutoSnapped(const QString &windowId)=0
virtual void forgetDesktopZones(const QString &windowId, const QString &engineId, int desktop)
Drop desktop's entry from engineId's per-desktop zone map on windowId's record and mark the placement...
Definition IWindowTrackingService.h:248
virtual QString findEmptyZoneInLayout(PhosphorZones::Layout *layout, const QString &screenId, int desktopFilter=0) const =0
virtual PhosphorScreens::ScreenManager * screenManager() const =0
virtual QRect zoneGeometry(const QString &zoneId, const QString &screenId) const =0
Frame for zoneId measured against screenId.
virtual void clearPreFloatZone(const QString &windowId)=0
Clear the saved pre-float zone/screen for windowId (both the windowId key and its appId alias).
virtual void recordSnapIntent(const QString &windowId, bool wasUserInitiated)=0
virtual void markLastUsedZoneDirty()
An engine cleared a last-used zone in one of its stores: persist it.
Definition IWindowTrackingService.h:296
virtual QString preFloatScreen(const QString &windowId) const =0
The single source of truth for window restore state in the unified model.
Definition WindowPlacementStore.h:38
Centralized screen-topology service.
Definition Manager.h:86
Represents a collection of zones that form a layout.
Definition Layout.h:42
Definition DesktopRemap.h:12
Definition IWindowTrackingService.h:28
Definition IWindowTrackingService.h:24