Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PlacementEngineBase.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
8#include "phosphorengine_export.h"
9
10#include <QList>
11#include <QObject>
12#include <QPointer>
13#include <QRect>
14#include <QSet>
15#include <QSize>
16#include <QString>
17#include <QStringList>
18
19namespace PhosphorEngine {
20
24
35class PHOSPHORENGINE_EXPORT PlacementEngineBase : public QObject, public IPlacementEngine
36{
37 Q_OBJECT
38
39public:
43 virtual int pruneStaleWindows(const QSet<QString>& aliveWindowIds);
44
55 virtual QRect lastManagedRect(const QString& windowId) const
56 {
57 Q_UNUSED(windowId)
58 return {};
59 }
60
61 // ═══════════════════════════════════════════════════════════════════════════
62 // Settings — universal pattern for all engines
63 //
64 // The daemon calls setEngineSettings() once at startup with a QObject*
65 // that implements the engine's specific settings interface (e.g.
66 // IAutotileSettings, ISnapSettings). Engines qobject_cast at point of
67 // use to their interface type. No caching, no bridge, no signal wiring
68 // inside the engine — the daemon handles change signals externally.
69 // A nullptr is REFUSED with a warning (there is deliberately no unset
70 // path); lifetime is handled by the QPointer member, so a destroyed
71 // settings object reads back null without a teardown-symmetry clear.
72 // ═══════════════════════════════════════════════════════════════════════════
73
74 void setEngineSettings(QObject* settings);
75 QObject* engineSettings() const
76 {
77 return m_engineSettings;
78 }
79
80 // Public dtor required for unique_ptr<PlacementEngineBase> in Daemon.
82
83 void setOpenFocusEligible(bool eligible) override
84 {
85 m_openFocusEligible = eligible;
86 }
87
91 void releaseWindowOffScreen(const QString& windowId, const QString& keepScreenId) override;
92
93protected:
94 explicit PlacementEngineBase(QObject* parent = nullptr);
95
100 bool openFocusEligible() const
101 {
102 return m_openFocusEligible;
103 }
104
114 void announceLayerSwitch(const LayerSwitchResult& result, const QString& action, const QString& screenId);
115
171 void restoreFreeSizeWhereItStands(IWindowTrackingService* tracker, const QString& windowId, const QString& screenId,
172 RestoreReason reason, bool placedBefore, const QList<QSize>& managedSizes);
173
183 static bool isManagedSize(const QList<QSize>& managedSizes, const QSize& size);
184
192 static bool placedByPreviousLineage(const WindowPlacementStore& store, const QString& windowId);
193
194Q_SIGNALS:
195 void geometryRestoreRequested(const QString& windowId, const QRect& geometry, const QString& screenId);
202 void sizeRestoreRequested(const QString& windowId, const QSize& size, const QString& screenId);
203
204 void navigationFeedback(bool success, const QString& action, const QString& reason, const QString& sourceId,
205 const QString& targetId, const QString& screenId);
206 void windowFloatingChanged(const QString& windowId, bool floating, const QString& screenId);
207 void activateWindowRequested(const QString& windowId);
208
213 void windowDesktopMoveRequested(const QString& windowId, int desktop);
214
226 void windowOutputMoveExpected(const QString& windowId, const QString& targetScreenId);
227
238 void crossModeMoveRequested(const QString& windowId, const QString& targetScreenId, int targetDesktop,
239 const QString& direction);
240
250 void crossModeSwapRequested(const QString& windowId, const QString& targetScreenId, int targetDesktop,
251 const QString& direction);
252
269 void crossModeFocusRequested(const QString& targetScreenId, const QString& direction, bool* handled);
270
275 void windowFloatingStateSynced(const QString& windowId, bool floating, const QString& screenId);
276
278 void windowsBatchFloated(const QStringList& windowIds, const QString& screenId);
279
281 void algorithmChanged(const QString& algorithmId);
282
284 void placementChanged(const QString& screenId);
285
287 void windowsReleased(const QStringList& windowIds, const QSet<QString>& releasedScreenIds);
288
292
293private:
294 QPointer<QObject> m_engineSettings;
296 bool m_openFocusEligible = true;
297};
298
299} // namespace PhosphorEngine
virtual QString algorithmId() const
Definition IPlacementEngine.h:1000
Definition IWindowTrackingService.h:35
void windowOutputMoveExpected(const QString &windowId, const QString &targetScreenId)
Emitted when daemon-initiated directional navigation moves a window across physical outputs: the engi...
void setEngineSettings(QObject *settings)
void restoreFreeSizeWhereItStands(IWindowTrackingService *tracker, const QString &windowId, const QString &screenId, RestoreReason reason, bool placedBefore, const QList< QSize > &managedSizes)
The size-only half of a float verdict, shared by every engine (#1106).
void windowFloatingStateSynced(const QString &windowId, bool floating, const QString &screenId)
Emitted to sync floating state without restoring geometry: engine-internal divergence correction,...
void windowFloatingChanged(const QString &windowId, bool floating, const QString &screenId)
void crossModeSwapRequested(const QString &windowId, const QString &targetScreenId, int targetDesktop, const QString &direction)
Emitted when a directional SWAP reaches a context boundary whose target is a DIFFERENT tiling mode th...
void crossModeFocusRequested(const QString &targetScreenId, const QString &direction, bool *handled)
Emitted when a directional FOCUS reaches a monitor boundary whose neighbour context runs a DIFFERENT ...
void algorithmChanged(const QString &algorithmId)
Emitted when the active tiling algorithm changes.
void sizeRestoreRequested(const QString &windowId, const QSize &size, const QString &screenId)
Resize windowId to size where it stands, leaving the position to the compositor.
void geometryRestoreRequested(const QString &windowId, const QRect &geometry, const QString &screenId)
void windowDesktopMoveRequested(const QString &windowId, int desktop)
Emitted when directional navigation moves a window across virtual desktops: the engine has already re...
void activateWindowRequested(const QString &windowId)
void announceLayerSwitch(const LayerSwitchResult &result, const QString &action, const QString &screenId)
Emit the activation + navigationFeedback pair for a resolved layer focus switch (resolveLayerFocusSwi...
virtual QRect lastManagedRect(const QString &windowId) const
The exact rect this engine last APPLIED to windowId while managing it (its tile rect),...
Definition PlacementEngineBase.h:55
bool openFocusEligible() const
Whether the open being handled may take focus (see IPlacementEngine::setOpenFocusEligible).
Definition PlacementEngineBase.h:100
void releaseWindowOffScreen(const QString &windowId, const QString &keepScreenId) override
A window is held on one output, so a hold on any screen but keepScreenId is released whole through ha...
PlacementEngineBase(QObject *parent=nullptr)
void placementChanged(const QString &screenId)
Emitted when the placement layout changes for a screen.
virtual int pruneStaleWindows(const QSet< QString > &aliveWindowIds)
Drop any per-engine bookkeeping for windows not in aliveWindowIds.
void settingsPersistRequested()
Emitted when the engine writes tuning values back to the settings object and wants the daemon to pers...
static bool isManagedSize(const QList< QSize > &managedSizes, const QSize &size)
Whether size is within two pixels of any entry of managedSizes on both axes.
void setOpenFocusEligible(bool eligible) override
OPTIONAL: whether the opens dispatched next may take focus ("Focus newwindows"): true for a genuine o...
Definition PlacementEngineBase.h:83
void windowsReleased(const QStringList &windowIds, const QSet< QString > &releasedScreenIds)
Emitted when windows are released from engine management.
static bool placedByPreviousLineage(const WindowPlacementStore &store, const QString &windowId)
The placedBefore snapshot for restoreFreeSizeWhereItStands: store holds a record WITH AN ENGINE SLOT ...
void crossModeMoveRequested(const QString &windowId, const QString &targetScreenId, int targetDesktop, const QString &direction)
Emitted when a directional MOVE reaches a context boundary whose target is a DIFFERENT tiling mode th...
void navigationFeedback(bool success, const QString &action, const QString &reason, const QString &sourceId, const QString &targetId, const QString &screenId)
void windowsBatchFloated(const QStringList &windowIds, const QString &screenId)
Emitted when overflow windows are batch-floated during applyTiling.
QObject * engineSettings() const
Definition PlacementEngineBase.h:75
The single source of truth for window restore state in the unified model.
Definition WindowPlacementStore.h:38
Definition DesktopRemap.h:12
RestoreReason
Why a snap restore is being resolved.
Definition EngineTypes.h:119
Outcome of resolving a layer focus switch.
Definition LayerFocusSwitch.h:53